feat(home): offer VS Code alongside Docker in the quick start

[GuanzhouSong]

What changed

The homepage quick start offers two paths to the same local database, as Terminal and VS Code tabs. Terminal is selected by default and keeps the original command and the public run-with-docker anchor.

The VS Code tab installs the extension and opens its DocumentDB Local setup wizard via vscode://ms-azuretools.vscode-documentdb/local.

Design review changes

A design and product review of the first version found the VS Code panel was written for someone who had already seen the wizard. The changes that came out of it:

Copy. The prerequisite now states plainly that the VS Code path still uses Docker and that the extension never installs Docker or changes the user's system, replacing the jargon "in your VS Code environment". Step 01 names what gets installed rather than pinning extension version 0.10.1, which is maintenance debt on a homepage and is noise for a new installer who gets the latest anyway. Step 02 was a four-action transcript of wizard buttons and is now click, allow, follow the wizard. Step 03 states the outcome, port and generated credentials, so the reader knows what they got. The fallback names the likely cause instead of treating "no VS Code", "no extension", and "old extension" identically.

The Docker steps were tightened in the same pass: the step that restated the command directly above it is gone, first-run pull time is called out, and the vague "continue with the docs or Linux packages for the setup you need" is now a concrete connect-and-query.

Structure. The tabs are Terminal and VS Code; labelling one "Docker" implied the other avoided Docker, when both start the same container. Install the extension is now the primary action and the deep link is secondary, matching the order of the steps — previously the most prominent control was the one that silently does nothing for a visitor without the extension. The card footer link follows the active tab and points at that path's full guide; "Download packages" is gone, since the hero already has "Download" pointing at the same page. Each panel links across to the other path, so neither is fully hidden behind a tab.

Presentation. The tablist gets a solid active state and larger hit targets (previously ~30px, under the 44px guideline), so it reads as a control rather than as a third row of small blue pills between the "Quick start" chip and the numbered step markers. The hero grid is now items-start: it was items-center, and because the card is the taller column, every tab switch nudged the DocumentDB headline vertically. Home and End keys move between tabs, completing the ARIA authoring practices for the pattern.

The VS Code guide

The card's whole VS Code pitch is that the extension sets things up so you do not run Docker commands. The guide behind "Full VS Code guide" said the opposite: start the container yourself, then create a New Local Connection and type the port and credentials by hand.

My first attempt at this fixed the wrong file. articles/** is gitignored and cloned from documentdb/docs, so I rewrote it there (documentdb/docs#77, merged). But getArticleByPath in app/services/articleService.ts short-circuits on vscode-quickstart and returns an inline vscodeQuickStartGuideContent before ever reading the cloned markdown — one of eight such inline overrides established in #70. The upstream rewrite never reached the site.

The fix therefore lands here, in the inline constant, which now leads with the setup wizard (all three ways to open it, the Continue → Start DocumentDB Local sequence, what the wizard produces) and keeps the manual flow as an explicit alternative. The loopback binding, quoted placeholders and TLS guidance that copy already got right are preserved. Verified by calling getArticleByPath('getting-started', ['vscode-quickstart']) and asserting the wizard section precedes the manual one.

The upstream docs PR stays merged and useful — documentdb/docs is canonical and consumed elsewhere — it simply is not what this site renders.

Extension compatibility

Verified against microsoft/vscode-documentdb main (013e429f) and published releases on 2026-09-10, reading extension source rather than release notes:

• vscodeUriHandler.ts routes /local as shorthand for /local/documentdb, so the published URL needs no change or query parameters, and it shows a modal confirmation before anything opens.
• LocalQuickStart.tsx drives introduction → Continue → configure → Start DocumentDB Local → Open Connection.
• quickStartTypes.ts confirms the container name, persistent volume, port 10260, and generated credentials the steps now promise.
• package.json contributes Set up DocumentDB Local under the DocumentDB category, so the Command Palette fallback string is exact.
• "Linux containers required" is a real Docker readiness state, so the prerequisite is accurate.

The deep link shipped in v0.10.1, still the latest published release. 0.10.2 exists only on main; nothing on this page depends on it shipping.

Validation

Regression coverage asserts the terminal default and public anchor, tab/panel relationships, the tab labels, link order and URLs, the Docker prerequisite and no-system-changes promise, the setup outcome, the absence of a pinned version number, the per-path guide link, and the fallback command. 94 tests across 5 files pass through the project's own vitest.config.mts, with the latest main merged in. The hero command is additionally checked against bash -n and zsh -n; both accepted it after the placeholders were quoted.

npm install still fails in this environment with a 404 for Vite's pinned postcss@8.5.28 on the configured package-feed proxy. Runtime dependencies were installed into a scratch directory and linked in for the test run; no dependency versions, package.json, or lockfiles were modified. GitHub Actions remains the authority.

Browser-to-VS-Code handoff and Docker provisioning have not been exercised end to end; the compatibility claims are verified from extension source and the released tag.

[GuanzhouSong]

Screenshots

Built locally with next build --turbopack and captured from the static export in out/ at 1440px, so this is the production output rather than a dev server.

Quick start — Terminal tab (default)

The command binds 127.0.0.1:10260:10260 and quotes the placeholders, so it matches the Docker guide and parses in both bash -n and zsh -n. The footer carries the cross-link ("Want a GUI? The VS Code extension connects to this container too") and Full Docker guide.

Quick start — VS Code tab

Install the extension is primary and the deep link secondary. The prerequisite states the path still needs Docker set to Linux containers wherever VS Code runs, and that the extension changes nothing else on the machine. Step 02 names both wizard clicks; step 03 states the outcome without promising a port it may not get.

The guide the VS Code tab opens

This is the ship-blocker fix. The page previously opened with "Start DocumentDB first" and a manual New Local Connection flow, contradicting the tab that links to it. It now leads with the wizard, with the manual flow kept below as an explicit alternative.

_{Images are hosted on the pr-179-screenshots branch of the fork, pinned to a commit SHA so they cannot change under this comment. That branch is not part of this PR and can be deleted once reviewed.}

[tnaum-ms]

@GuanzhouSong Thanks for the thorough pass on this. One area I would like to push further: the VS Code tab.

Reading the two tabs side by side, the VS Code one comes across as heavier and more intimidating than the Terminal one, and that is the opposite of what I want. The VS Code path is the one where you click and go, so it should feel like the easy option, not the one with caveats.

Three concrete changes.

1. Drop the Docker prerequisite paragraph. It is true that this path needs Docker, but it is equally true of the Terminal tab, and we do not say it there. Stating it only under VS Code makes the guided path look like the one with extra requirements. The full guide covers Docker properly, including the readiness states.

2. One button, and two steps instead of three. VS Code offers to install the extension when the deep link is opened, so "Install the extension" as a separate primary action is a step the user does not have to take on their own. A single button can carry the whole flow, with the install explained in a caption underneath so nothing is hidden. That also removes the old step 01, and the old step 02 was partly restating the button directly above it. What is left is the wizard and the payoff. Two steps against Terminal's three is worth having: the guided path should look shorter at a glance.

3. Move the troubleshooting block out of the main flow. The "If nothing happens, check that the extension is installed and up to date" paragraph sits right in the happy path. The guide already lists every way to open the wizard (activity bar, Command Palette, the vscode:// URI, version requirement), so a short link does the job without putting doubt in front of someone who has not clicked yet.

Proposed copy for the tab:

Above the button

Choose this for the smoothest experience. VS Code sets up DocumentDB Local and creates a ready-to-use connection for you. One click, then follow the wizard.

Button (single)

Set up in VS Code

Caption under the button

Opens VS Code, asks to install the DocumentDB for VS Code extension, and launches the wizard.

Steps

1. Once VS Code loads the wizard, select Continue, review the defaults, then select Start DocumentDB Local.
2. Select Open Connection to browse your data and run your first query. Sample data is included.

Footer

Not working in VS Code? The setup guide(link here) shows how to open the wizard from the activity bar or the Command Palette.

Prefer to start it yourself? The Terminal tab runs the same image with one command.