Simplify VS Code setup caption and fix extension troubleshooting

app/components/QuickStartTabs.tsx

@@ -7,7 +7,6 @@ import CommandSnippet from "./CommandSnippet";
 type QuickStartTabsProps = {
   dockerCommand: string;
   vscodeDeepLinkUrl: string;
-  vscodeMarketplaceUrl: string;
   dockerDocsUrl: string;
   vscodeDocsUrl: string;
 };
@@ -22,7 +21,6 @@ type TabId = (typeof TABS)[number]["id"];
 export default function QuickStartTabs({
   dockerCommand,
   vscodeDeepLinkUrl,
-  vscodeMarketplaceUrl,
   dockerDocsUrl,
   vscodeDocsUrl,
 }: QuickStartTabsProps) {
@@ -145,25 +143,16 @@ export default function QuickStartTabs({
           id="quickstart-vscode-setup-caption"
           className="mt-3 text-sm leading-6 text-gray-400"
         >
-          Requires{" "}
+          Don't have VS Code?{" "}
           <Link
             href="https://code.visualstudio.com/"
             target="_blank"
             rel="noopener noreferrer"
             className="font-semibold text-blue-300 transition-colors hover:text-blue-200"
           >
-            VS Code
-          </Link>
-          . You may be prompted to install the{" "}
-          <Link
-            href={vscodeMarketplaceUrl}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="font-semibold text-blue-300 transition-colors hover:text-blue-200"
-          >
-            DocumentDB extension
-          </Link>
-          .
+            Download it
+          </Link>{" "}
+          first.
         </p>
         <p className="mt-4 text-sm leading-6 text-gray-300">
           When setup finishes, select Open Connection.

app/page.tsx

@@ -3,7 +3,6 @@ import Link from "next/link";
 import QuickStartTabs from "./components/QuickStartTabs";
 import {
   documentdbKubernetesOperatorQuickStartUrl,
-  documentdbVsCodeExtensionMarketplaceUrl,
   documentdbVsCodeLocalQuickStartDeepLink,
 } from "./services/externalLinks";
 import { getMetadata } from "./services/metadataService";
@@ -370,7 +369,6 @@ export default function Home() {
               <QuickStartTabs
                 dockerCommand={quickRunCommand}
                 vscodeDeepLinkUrl={documentdbVsCodeLocalQuickStartDeepLink}
-                vscodeMarketplaceUrl={documentdbVsCodeExtensionMarketplaceUrl}
                 dockerDocsUrl="/docs/getting-started/docker"
                 vscodeDocsUrl="/docs/getting-started/vscode-quickstart"
               />

app/services/articleService.ts

@@ -643,7 +643,7 @@ Install the extension from the VS Code marketplace, or run:
 code --install-extension ms-azuretools.vscode-documentdb
 \`\`\`
 
-If VS Code prompts you to reload after installation, do that before creating a connection.
+To update an older install, add \`--force\`; without it the command keeps the version you have. Reload VS Code after installing or updating, because the running window keeps using the previous version until then.
 
 ## Set up DocumentDB Local
 
@@ -652,7 +652,7 @@ Use guided setup to let the extension provision DocumentDB Local and save its co
 1. Open setup using any of these:
    - Select the DocumentDB icon in the activity bar, expand **Your own DocumentDB** in the Connections view, and select **Set up DocumentDB Local**.
    - Run **DocumentDB: Set up DocumentDB Local** from the Command Palette.
-   - Open \`vscode://ms-azuretools.vscode-documentdb/local\` from your browser and confirm the prompts. If the extension is not installed, VS Code offers to install it first. This needs extension version 0.10.1 or later.
+   - Open \`vscode://ms-azuretools.vscode-documentdb/local\` from your browser and confirm the prompts. This needs extension version 0.10.1 or later, so install or update the extension first; the link cannot always install it for you.
 2. On the **Introduction** step, select **Continue**. Nothing is downloaded or created until the next step.
 3. On the **Configure** step, review the defaults and select **Start DocumentDB Local**. The defaults give you an available port (starting at \`10260\`), generated credentials, the \`latest\` official image, and optional sample data. Expand the advanced options to set the port, image tag, or credentials yourself.
 4. Wait for setup to finish. The extension creates a container named \`vscode-documentdb-local\` with a persistent volume, then waits until the database accepts connections.
@@ -723,8 +723,9 @@ After the connection works, the extension can help you continue without leaving
 
 If setup or the connection does not work on the first try:
 
-- If the browser link does nothing, confirm the extension is installed and up to date, then run **DocumentDB: Set up DocumentDB Local** from the Command Palette instead
-- If VS Code reports **No extension gallery service configured**, it could not reach a marketplace to install the extension for you. On managed devices that use a private marketplace, this can happen when the link is also what starts VS Code. Open the link again once VS Code has loaded, or install the extension yourself with \`code --install-extension ms-azuretools.vscode-documentdb\` and then open the link again
+- If the browser link does nothing, confirm VS Code is installed and that you allowed the browser to open it. If VS Code opens but setup does not start, install or update the extension, reload VS Code, and open the link again, or run **DocumentDB: Set up DocumentDB Local** from the Command Palette instead
+- If VS Code reports that **a DocumentDB deep-link was opened without a connection string**, the extension is older than 0.10.1. Run \`code --install-extension ms-azuretools.vscode-documentdb --force\`, reload VS Code, and open the link again
+- If VS Code reports **No extension gallery service configured**, or nothing happens when the extension is missing, the link could not install it for you. This is common on managed devices that use a private marketplace. Install the extension yourself with \`code --install-extension ms-azuretools.vscode-documentdb\`, then open the link again
 - If setup reports that Docker is unreachable, fix what it names (Docker not running, or Docker set to Windows containers rather than Linux) and select **Continue setup**; nothing has been created at that point
 - Verify the extension is installed and reload VS Code if the DocumentDB view does not appear
 - Confirm your local DocumentDB instance is actually running before you connect

app/services/externalLinks.ts

@@ -14,8 +14,5 @@ export const documentdbKubernetesOperatorQuickStartUrl =
 export const documentdbKubernetesOperatorGitHubUrl =
   'https://github.com/documentdb/documentdb-kubernetes-operator';
 
-export const documentdbVsCodeExtensionMarketplaceUrl =
-  'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb';
-
 export const documentdbVsCodeLocalQuickStartDeepLink =
   'vscode://ms-azuretools.vscode-documentdb/local';

tests/quickStart.test.ts

@@ -9,10 +9,7 @@ import {
   vscodeExistingConnectionSectionTitle,
 } from '../app/lib/docsAnchors';
 import { getArticleByPath } from '../app/services/articleService';
-import {
-  documentdbVsCodeExtensionMarketplaceUrl,
-  documentdbVsCodeLocalQuickStartDeepLink,
-} from '../app/services/externalLinks';
+import { documentdbVsCodeLocalQuickStartDeepLink } from '../app/services/externalLinks';
 
 const html = renderToStaticMarkup(createElement(Home));
 const cardStart = html.indexOf('id="run-with-docker"');
@@ -137,10 +134,12 @@ describe('homepage local quick start', () => {
 
     const captionStart = guided.indexOf('id="quickstart-vscode-setup-caption"');
     const caption = guided.slice(captionStart, guided.indexOf('</p>', captionStart));
-    expect(caption).toContain('Requires');
-    expect(caption).toContain('href="https://code.visualstudio.com/"');
-    expect(caption).toContain('You may be prompted to install');
-    expect(caption).toContain(`href="${documentdbVsCodeExtensionMarketplaceUrl}"`);
+    // One click covers VS Code with or without the extension; only VS Code itself must come first.
+    expect(caption).toMatch(
+      /Don&#x27;t have VS Code\? <a [^>]*href="https:\/\/code\.visualstudio\.com\/">Download it<\/a> first\./,
+    );
+    expect(caption).not.toContain('marketplace.visualstudio.com');
+    expect(caption).not.toContain('vscode:extension/');
     expect(guided).not.toContain('>Install the extension</');
   });
 
@@ -241,5 +240,10 @@ describe('VS Code quick-start guide', () => {
     expect(guideContent).toContain('DocumentDB: Set up DocumentDB Local');
     expect(guideContent).toContain('No extension gallery service configured');
     expect(guideContent).toContain('code --install-extension ms-azuretools.vscode-documentdb');
+    // Without --force the CLI keeps an older version, and old versions reject the /local link.
+    expect(guideContent).toContain('code --install-extension ms-azuretools.vscode-documentdb --force');
+    expect(guideContent).toContain('opened without a connection string');
+    expect(guideContent).toContain('Reload VS Code after installing or updating');
+    expect(guideContent).not.toContain('VS Code offers to install it first');
   });
 });