From c34002176a21b26136bb61320db81302a2c0141e Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Fri, 10 Apr 2026 14:24:11 -0400
Subject: [PATCH 1/2] fix page

---
 app/components/Markdown.tsx             |  12 +-
 app/data/samples.ts                     |  14 +-
 app/docs/[section]/[[...slug]]/page.tsx |  32 +-
 app/lib/packageInstall.ts               |   4 +-
 app/packages/page.tsx                   |  59 +-
 app/services/articleService.ts          | 931 +++++++++++++++++++++++-
 6 files changed, 985 insertions(+), 67 deletions(-)

diff --git a/app/components/Markdown.tsx b/app/components/Markdown.tsx
index de0c327..b547ad7 100644
--- a/app/components/Markdown.tsx
+++ b/app/components/Markdown.tsx
@@ -90,25 +90,25 @@ function getMarkdownComponents() {
       </h4>
     ),
 
-    // Unordered lists with blue round bullets
-    ul: ({ depth, ...props }: any) => (
+    // Unordered lists with consistent nested indentation
+    ul: ({ ...props }: any) => (
       <ul
-        className={depth > 0 ? "ml-6 space-y-2 text-gray-300 mb-4 list-disc list-inside" : "space-y-2 text-gray-300 mb-4 list-disc list-inside"}
+        className="mb-4 list-disc space-y-2 pl-6 text-gray-300 [&_ul]:mb-0 [&_ul]:mt-2 [&_ul]:list-[circle] [&_ul]:pl-6 [&_ol]:mb-0 [&_ol]:mt-2 [&_ol]:pl-6"
         {...props}
       />
     ),
 
-    // Ordered lists with blue numbers
+    // Ordered lists with consistent nested indentation
     ol: ({ ...props }) => (
       <ol
-        className="space-y-2 text-gray-300 mb-4 list-decimal list-inside"
+        className="mb-4 list-decimal space-y-2 pl-6 text-gray-300 [&_ul]:mb-0 [&_ul]:mt-2 [&_ul]:pl-6 [&_ol]:mb-0 [&_ol]:mt-2 [&_ol]:pl-6"
         {...props}
       />
     ),
 
     // List items
     li: ({ ...props }) => (
-      <li className="marker:text-blue-400 marker:mr-3 marker:flex-shrink-0 [&>p]:m-0 [&>p]:inline" {...props} />
+      <li className="leading-relaxed marker:text-blue-400 [&>p]:m-0 [&>p]:inline [&>ul]:mb-0 [&>ul]:mt-2 [&>ol]:mb-0 [&>ol]:mt-2" {...props} />
     ),
 
     // Inline code
diff --git a/app/data/samples.ts b/app/data/samples.ts
index b415fe0..495c737 100644
--- a/app/data/samples.ts
+++ b/app/data/samples.ts
@@ -3,6 +3,16 @@
 import { Sample } from '../types/Sample';
 
 export const samples: Sample[] = [
+  {
+    id: 'personal-memory-mcp-ts',
+    title: 'Personal AI Memory: Cross-Platform MCP Server with DocumentDB Vector Search',
+    description: 'A TypeScript MCP server that gives any AI assistant — Copilot CLI, Claude, Gemini — persistent personalized memory backed by DocumentDB. Uses a 4-layer retrieval strategy: cosmosSearch vector similarity, full-text search indexes, array tag queries, and regex fallback. Demonstrates DocumentDB\'s vector search (pgvector), MongoDB wire protocol compatibility, text indexes, atomic update operators, and flexible document schema in a practical AI application.',
+    language: 'TypeScript',
+    industry: 'AI/ML',
+    difficulty: 'Intermediate',
+    tags: ['MCP', 'AI Memory', 'Vector Search', 'Full-Text Search', 'Text Index', 'Express', 'RAG', 'DocumentDB OSS', 'Open Source'],
+    githubUrl: 'https://github.com/documentdb/documentdb-samples-gallery/tree/main/personal-memory-mcp-ts',
+  },
   {
     id: 'hotel-agent-ts',
     title: 'Hotel Recommendation Agent: RAG with Native Vector Search and LLM Synthesizer in TypeScript',
@@ -66,11 +76,11 @@ export const samples: Sample[] = [
   {
     id: 'activity-log-fastapi-py',
     title: 'Activity Log & Notification Service: Real-Time Event Ingestion with FastAPI, Beanie, and DocumentDB',
-    description: 'A production-style async Python backend that ingests high-volume activity events via FastAPI, stores them in DocumentDB using the Beanie ODM over Motor, and exposes endpoints to query recent activities, compute server-side aggregation statistics ($facet pipeline), and stream real-time ERROR alerts to clients over WebSockets.',
+    description: 'A production-style async Python backend that ingests high-volume activity events via FastAPI, stores them in DocumentDB using the Beanie ODM (backed by PyMongo async), and exposes endpoints to query recent activities, compute server-side aggregation statistics ($facet pipeline), and stream real-time ERROR alerts to clients over WebSockets.',
     language: 'Python',
     industry: 'DevOps / Observability',
     difficulty: 'Intermediate',
-    tags: ['FastAPI', 'Beanie', 'Motor', 'REST API', 'WebSocket', 'Aggregation', 'DocumentDB OSS', 'Open Source'],
+    tags: ['FastAPI', 'Beanie', 'PyMongo', 'REST API', 'WebSocket', 'Aggregation', 'DocumentDB OSS', 'Open Source'],
     githubUrl: 'https://github.com/documentdb/documentdb-samples-gallery/tree/main/activity-log-fastapi-py',
   }
 ];
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 13a5482..657c914 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -50,11 +50,16 @@ export async function generateMetadata({ params }: PageProps) {
 
 export default async function ArticlePage({ params }: PageProps) {
     const { section, slug = [] } = await params;
+    const currentSlug = slug[slug.length - 1];
 
-    if (section === 'getting-started' && slug[slug.length - 1] === 'prebuilt-packages') {
+    if (section === 'getting-started' && currentSlug === 'prebuilt-packages') {
         redirect('/docs/getting-started/packages');
     }
 
+    if (section === 'getting-started' && currentSlug === 'vscode-extension-guide') {
+        redirect('/docs/getting-started/vscode-quickstart');
+    }
+
     const articleData = getArticleByPath(section, slug);
 
     if (!articleData) {
@@ -153,14 +158,31 @@ export default async function ArticlePage({ params }: PageProps) {
 
                         {showInstallPrimer && (
                             <section className="mb-8 rounded-xl border border-blue-500/30 bg-blue-500/5 p-5">
-                                <h2 className="text-xl font-semibold text-white">Install DocumentDB first</h2>
+                                <h2 className="text-xl font-semibold text-white">Install and verify DocumentDB</h2>
                                 <p className="mt-2 text-sm text-gray-300">
-                                    Start with Docker for the fastest setup, or choose Linux packages for persistent servers.
+                                    Start with Docker for the fastest setup, or choose Linux packages for persistent servers. Then verify the connection with mongosh before moving to a driver quick start.
                                 </p>
                                 <div className="mt-4 grid gap-4 lg:grid-cols-2">
                                     <div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
                                         <p className="mb-3 text-sm font-semibold text-white">Quick run with Docker</p>
                                         <CommandSnippet command={dockerQuickRunCommand} label="Docker" />
+                                        <div className="mt-4 flex flex-wrap gap-3">
+                                            <Link
+                                                href="/docs/getting-started/mongo-shell-quickstart"
+                                                className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
+                                            >
+                                                Mongo Shell Quick Start
+                                            </Link>
+                                            <Link
+                                                href="/docs/getting-started/mongo-shell-quickstart"
+                                                className="inline-flex items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400"
+                                            >
+                                                Mongo Shell Quick Start
+                                            </Link>
+                                        </div>
+                                        <p className="mt-3 text-sm text-gray-400">
+                                            Recommended first path: Docker -&gt; Mongo Shell Quick Start -&gt; Node.js Quick Start or Python Quick Start.
+                                        </p>
                                     </div>
                                     <div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
                                         <p className="text-sm font-semibold text-white">Install from Linux packages</p>
@@ -172,7 +194,7 @@ export default async function ArticlePage({ params }: PageProps) {
                                                 href="/docs/getting-started/docker"
                                                 className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
                                             >
-                                                Docker guide
+                                                Docker Quick Start
                                             </Link>
                                             <Link
                                                 href="/packages"
@@ -184,7 +206,7 @@ export default async function ArticlePage({ params }: PageProps) {
                                                 href="/docs/getting-started/packages"
                                                 className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
                                             >
-                                                Linux packages docs
+                                                Linux Packages Quick Start
                                             </Link>
                                         </div>
                                     </div>
diff --git a/app/lib/packageInstall.ts b/app/lib/packageInstall.ts
index 3253175..1aad11f 100644
--- a/app/lib/packageInstall.ts
+++ b/app/lib/packageInstall.ts
@@ -53,7 +53,7 @@ echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] https://apt.postgresql.
 curl -fsSL https://documentdb.io/documentdb-archive-keyring.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/documentdb-archive-keyring.gpg && \\
 echo "deb [arch=${aptArch} signed-by=/usr/share/keyrings/documentdb-archive-keyring.gpg] https://documentdb.io/deb stable ${aptTarget}" | sudo tee /etc/apt/sources.list.d/documentdb.list >/dev/null && \\
 sudo apt update && \\
-sudo apt install -y postgresql-${aptPgVersion}-documentdb`;
+sudo apt install -y postgresql-${aptPgVersion}-documentdb documentdb_gateway`;
 }
 
 export function buildRpmInstallCommand(
@@ -78,5 +78,5 @@ printf '%s\\n' \\
   'enabled=1' \\
   'gpgcheck=1' \\
   'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg' | sudo tee /etc/yum.repos.d/documentdb.repo >/dev/null && \\
-sudo dnf install -y postgresql${rpmPgVersion}-documentdb`;
+sudo dnf install -y postgresql${rpmPgVersion}-documentdb documentdb-gateway`;
 }
diff --git a/app/packages/page.tsx b/app/packages/page.tsx
index c1c876d..d0bb049 100644
--- a/app/packages/page.tsx
+++ b/app/packages/page.tsx
@@ -33,17 +33,17 @@ const nextGuides = [
     href: "/docs/getting-started",
   },
   {
-    title: "Python",
+    title: "Python Quick Start",
     description: "Install PyMongo and connect to your local DocumentDB instance.",
     href: "/docs/getting-started/python-setup",
   },
   {
-    title: "Node.js",
+    title: "Node.js Quick Start",
     description: "Use the Node.js driver and run your first queries locally.",
     href: "/docs/getting-started/nodejs-setup",
   },
   {
-    title: "VS Code",
+    title: "Visual Studio Code Quick Start",
     description: "Connect through the VS Code extension for a guided local workflow.",
     href: "/docs/getting-started/vscode-quickstart",
   },
@@ -70,13 +70,19 @@ export default function PackagesPage() {
 
   const aptCommand = buildAptInstallCommand(aptTarget, aptArch, aptPgVersion);
   const rpmCommand = buildRpmInstallCommand(rpmTarget, rpmArch, rpmPgVersion);
-  const selectedPackageName =
+  const selectedPackageNames =
     packageFamily === "apt"
-      ? `postgresql-${aptPgVersion}-documentdb`
-      : `postgresql${rpmPgVersion}-documentdb`;
+      ? `postgresql-${aptPgVersion}-documentdb + documentdb_gateway`
+      : `postgresql${rpmPgVersion}-documentdb + documentdb-gateway`;
   const selectedTargetText =
     packageFamily === "apt" ? aptTargetLabels[aptTarget] : rpmTargetLabels[rpmTarget];
   const selectedArchText = packageFamily === "apt" ? aptArch : rpmArch;
+  const selectedPgVersion = packageFamily === "apt" ? aptPgVersion : rpmPgVersion;
+  const setupCommand = `sudo documentdb-setup \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD> \\
+  --pg-version ${selectedPgVersion} \\
+  --load-sample-data`;
 
   return (
     <div className="min-h-screen bg-neutral-900 py-12">
@@ -87,8 +93,8 @@ export default function PackagesPage() {
           </h1>
           <p className="mx-auto max-w-3xl text-lg text-gray-300">
             Choose Docker for the fastest local setup, or Linux packages for managed host
-            installations. The generated package commands also configure the PostgreSQL
-            dependency repositories required by DocumentDB.
+            installations. The generated package commands configure the PostgreSQL
+            dependency repositories and install the packages required by DocumentDB.
           </p>
           <div className="mt-4 flex flex-wrap justify-center gap-3 text-sm">
             <span className="rounded-full border border-green-500/30 bg-green-500/20 px-3 py-1 text-green-300">
@@ -151,7 +157,7 @@ export default function PackagesPage() {
                   href="/docs/getting-started/docker"
                   className="inline-flex items-center justify-center rounded-md border border-blue-400 bg-blue-500/10 px-4 py-2 text-sm font-semibold text-blue-200 transition-colors hover:bg-blue-500/20"
                 >
-                  Open Docker quick start →
+                  Open Docker Quick Start →
                 </Link>
               </div>
             </>
@@ -267,8 +273,8 @@ export default function PackagesPage() {
                 label={packageFamily === "apt" ? "APT" : "RPM"}
               />
               <p className="mt-3 text-sm text-gray-400">
-                Target: {selectedTargetText} · Architecture: {selectedArchText} · package name{" "}
-                <code className="text-gray-300">{selectedPackageName}</code>
+                Target: {selectedTargetText} · Architecture: {selectedArchText} · package names{" "}
+                <code className="text-gray-300">{selectedPackageNames}</code>
               </p>
               <p className="mt-2 text-sm text-gray-400">
                 The generated command adds the PostgreSQL upstream repositories that provide
@@ -276,6 +282,21 @@ export default function PackagesPage() {
                 <code className="text-gray-300">pgvector</code>, PostGIS, and{" "}
                 <code className="text-gray-300">rum</code>.
               </p>
+              <p className="mt-2 text-sm text-gray-400">
+                It also installs the PostgreSQL extension package plus the gateway package
+                required for MongoDB-compatible connections on port 10260.
+              </p>
+              <div className="mt-4 rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
+                <p className="mb-3 text-sm font-semibold text-white">
+                  Then initialize and start DocumentDB
+                </p>
+                <CommandSnippet command={setupCommand} label="Setup" />
+                <p className="mt-3 text-sm text-gray-400">
+                  Use <code className="text-gray-300">--skip-pg-init</code> and{" "}
+                  <code className="text-gray-300">--pg-port</code> if you want to attach
+                  DocumentDB to an existing PostgreSQL cluster instead of creating a new one.
+                </p>
+              </div>
               {packageFamily === "apt" ? (
                 <p className="mt-2 text-sm text-amber-300">
                   Debian 13 is now supported in the APT repository-backed install flow. Debian
@@ -435,12 +456,19 @@ export default function PackagesPage() {
               <div className="rounded-md border border-neutral-700 bg-black p-3">
                 <code className="text-xs text-green-400 sm:text-sm">
                   sudo apt update && apt search documentdb && apt-cache policy
-                  postgresql-16-documentdb
+                  postgresql-16-documentdb documentdb_gateway
+                </code>
+              </div>
+              <div className="rounded-md border border-neutral-700 bg-black p-3">
+                <code className="text-xs text-green-400 sm:text-sm">
+                  sudo dnf clean all && dnf search documentdb && rpm -qi
+                  postgresql16-documentdb documentdb-gateway
                 </code>
               </div>
               <div className="rounded-md border border-neutral-700 bg-black p-3">
                 <code className="text-xs text-green-400 sm:text-sm">
-                  sudo dnf clean all && dnf search documentdb && rpm -qi postgresql16-documentdb
+                  sudo systemctl status documentdb-gateway --no-pager && sudo journalctl -u
+                  documentdb-gateway --no-pager -n 20
                 </code>
               </div>
             </div>
@@ -453,8 +481,9 @@ export default function PackagesPage() {
               3. Connect and try it
             </h2>
             <p className="text-sm leading-6 text-gray-400">
-              Once DocumentDB is running, use port 10260 and follow one of these guides to make
-              your first connection.
+              After you run <code className="text-gray-300">documentdb-setup</code> and the
+              gateway is listening on port 10260, follow one of these guides to make your first
+              connection.
             </p>
           </div>
 
diff --git a/app/services/articleService.ts b/app/services/articleService.ts
index 32392a2..9b60ee6 100644
--- a/app/services/articleService.ts
+++ b/app/services/articleService.ts
@@ -7,12 +7,26 @@ import { Link } from '../types/Link';
 import { buildAptInstallCommand, buildRpmInstallCommand } from '../lib/packageInstall';
 
 const articlesDirectory = path.join(process.cwd(), 'articles');
-const dockerGuideContent = `# Docker
+const dockerGuideContent = `# Docker Quick Start
 
-Run DocumentDB locally in minutes using Docker.
+Run DocumentDB locally with Docker and verify the setup before moving to driver code.
+
+## Prerequisites
+
+- [Docker](https://www.docker.com/)
+- [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) for the fastest connection check
+- A local port available for DocumentDB (the examples use \`10260\`)
 
 ## Start DocumentDB
 
+If you do not already have the image locally, pull it first:
+
+\`\`\`bash
+docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
+\`\`\`
+
+Then start the container:
+
 \`\`\`bash
 docker run -dt --name documentdb \\
   -p 10260:10260 \\
@@ -25,7 +39,7 @@ docker run -dt --name documentdb \\
 >
 > DocumentDB Local loads built-in sample data into \`sampledb\` by default. See
 > [DocumentDB Local](/docs/documentdb-local) for \`--skip-init-data\`,
-> \`--init-data-path\`, and certificate options.
+> \`--init-data-path\`, certificate setup, and additional runtime options.
 
 ## Verify the container
 
@@ -33,41 +47,648 @@ docker run -dt --name documentdb \\
 docker ps --filter "name=documentdb"
 \`\`\`
 
+You should see the container in an \`Up\` state with port \`10260\` published.
+
+## Verify the connection
+
+Use \`mongosh\` to confirm authentication, TLS, and the gateway endpoint are working:
+
+\`\`\`bash
+mongosh localhost:10260 \\
+  -u <YOUR_USERNAME> \\
+  -p <YOUR_PASSWORD> \\
+  --authenticationMechanism SCRAM-SHA-256 \\
+  --tls \\
+  --tlsAllowInvalidCertificates
+\`\`\`
+
+Then run a quick health check and inspect the built-in sample data:
+
+\`\`\`javascript
+db.runCommand({ ping: 1 })
+
+use sampledb
+
+db.users.find({}, { name: 1, email: 1, _id: 0 }).limit(3)
+\`\`\`
+
+If you prefer certificate validation instead of \`--tlsAllowInvalidCertificates\`, follow the certificate steps in [DocumentDB Local](/docs/documentdb-local).
+
+## Persistence and initialization
+
+The quick start command above is ideal for disposable local environments. When you need more control:
+
+- Use \`--data-path\` with a mounted host directory to keep data across container restarts
+- Use \`--skip-init-data\` if you want an empty instance instead of the default \`sampledb\` collections
+- Use \`--init-data-path\` to run your own \`.js\` initialization scripts with \`mongosh\` at startup
+
+The built-in sample dataset includes \`users\`, \`products\`, \`orders\`, and \`analytics\` collections in \`sampledb\`.
+
+## Troubleshooting and debugging
+
+If something does not work as expected:
+
+- Confirm port \`10260\` is available and that \`docker ps\` shows the container running
+- Inspect startup, authentication, and TLS errors with \`docker logs documentdb\`
+- Restart the container with \`--log-level debug\` for more verbose local diagnostics
+- Use the certificate flow in [DocumentDB Local](/docs/documentdb-local) if your client should validate TLS certificates
+- Use [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart) for a fuller shell walkthrough
+
 ## Next steps
 
-- [Node.js Setup Guide](/docs/getting-started/nodejs-setup)
-- [Python Setup Guide](/docs/getting-started/python-setup)
-- [Linux Packages Guide](/docs/getting-started/packages)
+- [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart)
+- [Node.js Quick Start](/docs/getting-started/nodejs-setup)
+- [Python Quick Start](/docs/getting-started/python-setup)
+- [DocumentDB Local](/docs/documentdb-local)
+- [Samples Gallery](/samples)
+- [Linux Packages Quick Start](/docs/getting-started/packages)
 - [Package Finder](/packages)
 `;
 
-const linuxPackagesGuideContent = `# Linux Packages
+const linuxPackagesGuideContent = `# Linux Packages Quick Start
 
-Install DocumentDB on Linux hosts with apt/rpm packages.
+Install DocumentDB on Debian, Ubuntu, or RHEL-family hosts with repository-backed packages.
 
-## Fastest path
+## Choose the right package command
 
 Use the [Package Finder](/packages) to generate the exact install command for your distro, architecture, and PostgreSQL version.
 
+> The generated command installs both the PostgreSQL extension package and the gateway package required for MongoDB-compatible connections on port \`10260\`.
+>
 > The repository-backed install commands currently cover Ubuntu 22.04/24.04, Debian 11/12/13, and RHEL-family 8/9 systems. Debian 11 currently resolves PostgreSQL 16 and 17 in the repository-backed flow.
 
-## APT example
+## Install the packages
+
+### APT example
 
 \`\`\`bash
 ${buildAptInstallCommand('ubuntu24', 'amd64', '16')}
 \`\`\`
 
-## RPM example
+### RPM example
 
 \`\`\`bash
 ${buildRpmInstallCommand('rhel9', 'x86_64', '16')}
 \`\`\`
 
+## Initialize and start DocumentDB
+
+After the packages are installed, run the packaged setup command:
+
+\`\`\`bash
+sudo documentdb-setup \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD> \\
+  --pg-version 16 \\
+  --load-sample-data
+\`\`\`
+
+> If you selected PostgreSQL 17 or 18 in the Package Finder, use that version in \`--pg-version\`.
+>
+> If you want to attach DocumentDB to an existing PostgreSQL cluster instead of creating a new local cluster, use \`--skip-pg-init --pg-port <PORT>\`.
+
+## Verify the setup
+
+Use the gateway service status and \`mongosh\` to confirm the host install is ready:
+
+\`\`\`bash
+sudo systemctl status documentdb-gateway --no-pager
+
+mongosh localhost:10260 \\
+  -u <YOUR_USERNAME> \\
+  -p <YOUR_PASSWORD> \\
+  --authenticationMechanism SCRAM-SHA-256 \\
+  --tls \\
+  --tlsAllowInvalidCertificates
+\`\`\`
+
+Then run a quick health check and inspect the sample data:
+
+\`\`\`javascript
+db.runCommand({ ping: 1 })
+
+use sampledb
+
+db.users.find({}, { name: 1, email: 1, _id: 0 }).limit(3)
+\`\`\`
+
+If you skipped \`--load-sample-data\`, create your own collection instead of querying \`sampledb\`.
+
+## Existing PostgreSQL clusters and custom ports
+
+\`\`\`bash
+sudo documentdb-setup \\
+  --skip-pg-init \\
+  --pg-port 5432 \\
+  --gateway-port 10260 \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD>
+\`\`\`
+
+Use \`--data-dir\` and \`--pg-owner\` when your environment needs explicit PostgreSQL paths or ownership settings.
+
+## Troubleshooting and debugging
+
+If something does not work on the first try:
+
+- Confirm both packages are installed: \`postgresql-<PG>-documentdb\` plus \`documentdb_gateway\` on APT, or \`postgresql<PG>-documentdb\` plus \`documentdb-gateway\` on RPM
+- Re-run \`documentdb-setup --help\` to review cluster, port, and sample-data options
+- Use \`sudo documentdb-setup --verbose ...\` for more detailed setup output
+- Check the gateway service with \`sudo systemctl status documentdb-gateway\`
+- Inspect recent gateway logs with \`sudo journalctl -u documentdb-gateway --no-pager -n 50\`
+- If setup reports a PostgreSQL port or cluster conflict, use \`--skip-pg-init\` or choose a different \`--pg-port\`
+
+## Next steps
+
+- [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart)
+- [Node.js Quick Start](/docs/getting-started/nodejs-setup)
+- [Python Quick Start](/docs/getting-started/python-setup)
+- [API Reference](/docs/reference)
+- [Samples Gallery](/samples)
+- [Package Finder](/packages)
+- [Docker Quick Start](/docs/getting-started/docker)
+`;
+
+const vscodeQuickStartGuideContent = `# Visual Studio Code Quick Start
+
+Use DocumentDB for VS Code to connect to a local DocumentDB instance, browse sample data, and create your first database without leaving the editor.
+
+## Prerequisites
+
+- [Visual Studio Code](https://code.visualstudio.com/)
+- The [DocumentDB for VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb)
+- A local DocumentDB instance from [Docker Quick Start](/docs/getting-started/docker) or [Linux Packages Quick Start](/docs/getting-started/packages)
+- Optional: [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) for independent connection checks
+
+## Install the extension
+
+Install the extension from the VS Code marketplace, or run:
+
+\`\`\`bash
+code --install-extension ms-azuretools.vscode-documentdb
+\`\`\`
+
+If VS Code prompts you to reload after installation, do that before creating a connection.
+
+## Start DocumentDB first
+
+For the fastest local setup, start DocumentDB Local with Docker:
+
+\`\`\`bash
+docker run -dt --name documentdb \\
+  -p 10260:10260 \\
+  ghcr.io/documentdb/documentdb/documentdb-local:latest \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD>
+\`\`\`
+
+If you prefer a host installation instead of Docker, use [Linux Packages Quick Start](/docs/getting-started/packages) and complete the \`documentdb-setup\` step first.
+
+## Add a local connection in VS Code
+
+1. Open the **DocumentDB** view in the VS Code activity bar.
+2. In the local connection area, select **DocumentDB Local** and start the **New Local Connection** flow.
+3. Enter port \`10260\`, your username, and your password.
+4. At the TLS/SSL prompt:
+   - Choose **Disable TLS/SSL (Not recommended)** if you are using the default self-signed local setup and have not configured trust for the certificate yet.
+   - Keep **Enable TLS/SSL (Default)** if you already configured a trusted local certificate.
+5. Finish the wizard and confirm the new connection appears in the connections tree.
+
+## Verify the connection in the extension
+
+Once connected:
+
+1. Expand the connection and open \`sampledb\` if you started with DocumentDB Local sample data.
+2. Open a collection such as \`users\` or \`products\`.
+3. Switch between the **Table**, **Tree**, and **JSON** views to confirm the extension is reading data correctly.
+4. Create your own database and collection from the context menu, then add a test document like:
+
+\`\`\`json
+{
+  "name": "VS Code Quick Start",
+  "source": "vscode",
+  "status": "connected"
+}
+\`\`\`
+
+If you prefer to validate outside the extension first, use [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart).
+
+## Import, export, and querying
+
+After the connection works, the extension can help you continue without leaving VS Code:
+
+- Import JSON documents into a collection
+- Export query results or full collections
+- Browse documents in multiple views with pagination
+- Open the query editor and continue with commands from the [API Reference](/docs/reference)
+
+## Troubleshooting and debugging
+
+If the extension does not connect on the first try:
+
+- 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
+- If you used Docker, check \`docker ps\` and \`docker logs documentdb\`
+- If you used Linux packages, check \`sudo systemctl status documentdb-gateway\` and \`sudo journalctl -u documentdb-gateway --no-pager -n 50\`
+- If the local connection wizard fails on security, retry and choose the TLS/SSL option that matches your certificate setup
+- Use \`mongosh\` to confirm the endpoint works independently of VS Code
+
+For extension-specific help or bugs:
+
+- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb)
+- [GitHub repository](https://github.com/microsoft/vscode-documentdb)
+- [GitHub discussions](https://github.com/microsoft/vscode-documentdb/discussions)
+- [GitHub issues](https://github.com/microsoft/vscode-documentdb/issues)
+- [DocumentDB Discord](https://discord.gg/vH7bYu524D)
+
 ## Next steps
 
+- [DocumentDB for VS Code docs](https://github.com/microsoft/vscode-documentdb/tree/main/docs)
 - [Docker Quick Start](/docs/getting-started/docker)
-- [Node.js Setup Guide](/docs/getting-started/nodejs-setup)
-- [Python Setup Guide](/docs/getting-started/python-setup)
+- [Linux Packages Quick Start](/docs/getting-started/packages)
+- [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart)
+- [Node.js Quick Start](/docs/getting-started/nodejs-setup)
+- [Python Quick Start](/docs/getting-started/python-setup)
+- [API Reference](/docs/reference)
+`;
+
+const nodejsGuideContent = `# Node.js Quick Start
+
+Connect to DocumentDB from Node.js using the official MongoDB driver.
+
+## Prerequisites
+
+- Node.js 18 or later
+- npm
+- [Docker](https://www.docker.com/)
+- Basic familiarity with JavaScript
+
+## Start DocumentDB Local
+
+\`\`\`bash
+docker run -dt --name documentdb \\
+  -p 10260:10260 \\
+  ghcr.io/documentdb/documentdb/documentdb-local:latest \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD>
+\`\`\`
+
+> Replace \`<YOUR_USERNAME>\` and \`<YOUR_PASSWORD>\` with your own credentials.
+>
+> DocumentDB Local uses a self-signed certificate by default, so the quickest local
+> Node.js connection uses \`tlsAllowInvalidCertificates=true\`.
+
+## Create a project
+
+\`\`\`bash
+mkdir my-documentdb-app
+cd my-documentdb-app
+npm init -y
+npm install mongodb
+\`\`\`
+
+## Connect and run your first queries
+
+Create an \`index.js\` file:
+
+\`\`\`javascript
+const { MongoClient } = require("mongodb");
+
+const uri =
+  "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/" +
+  "?authSource=admin&tls=true&tlsAllowInvalidCertificates=true&directConnection=true";
+
+async function main() {
+  const client = new MongoClient(uri);
+
+  try {
+    await client.connect();
+
+    const db = client.db("quickstart");
+    await db.command({ ping: 1 });
+
+    const movies = db.collection("movies");
+
+    await movies.insertMany([
+      { title: "The Matrix", year: 1999, genres: ["sci-fi", "action"] },
+      { title: "Dune", year: 2021, genres: ["sci-fi", "adventure"] },
+      { title: "Arrival", year: 2016, genres: ["sci-fi", "drama"] }
+    ]);
+
+    await movies.createIndex({ title: 1 });
+
+    const recentMovies = await movies
+      .find(
+        { year: { $gte: 2000 } },
+        { projection: { _id: 0, title: 1, year: 1 } }
+      )
+      .sort({ year: -1 })
+      .toArray();
+
+    console.log("Connected to DocumentDB");
+    console.log(recentMovies);
+  } finally {
+    await client.close();
+  }
+}
+
+main().catch(console.error);
+\`\`\`
+
+Run the script:
+
+\`\`\`bash
+node index.js
+\`\`\`
+
+## Connect with a trusted local certificate instead
+
+If you want certificate validation instead of \`tlsAllowInvalidCertificates=true\`,
+copy the generated certificate from the container and point the driver at it.
+
+\`\`\`bash
+docker cp documentdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem
+\`\`\`
+
+\`\`\`javascript
+const uri =
+  "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/" +
+  "?authSource=admin&tls=true&tlsCAFile=/absolute/path/documentdb-cert.pem&directConnection=true";
+\`\`\`
+
+## Next steps
+
+- [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart)
+- [Python Quick Start](/docs/getting-started/python-setup)
+- [DocumentDB Local](/docs/documentdb-local)
+- [Samples Gallery](/samples)
+`;
+
+const pythonQuickStartContent = `# Python Quick Start
+
+Use PyMongo to connect to DocumentDB, verify authentication and TLS, and run your first document queries from Python.
+
+## Prerequisites
+
+- Python 3.9 or later
+- pip
+- A local DocumentDB instance from [Docker Quick Start](/docs/getting-started/docker) or [Linux Packages Quick Start](/docs/getting-started/packages)
+- Optional: [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) for independent connection checks
+
+## Start DocumentDB first
+
+For the fastest local setup, start DocumentDB Local with Docker:
+
+\`\`\`bash
+docker run -dt --name documentdb \\
+  -p 10260:10260 \\
+  ghcr.io/documentdb/documentdb/documentdb-local:latest \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD>
+\`\`\`
+
+If you prefer a host installation instead of Docker, use [Linux Packages Quick Start](/docs/getting-started/packages) and complete the \`documentdb-setup\` step first.
+
+> DocumentDB Local uses a self-signed certificate by default, so the quickest local
+> PyMongo connection uses \`tlsAllowInvalidCertificates=true\`.
+
+## Create a virtual environment (optional)
+
+\`\`\`bash
+python3 -m venv .venv
+source .venv/bin/activate
+\`\`\`
+
+If you do not use a virtual environment, run the next commands with the Python interpreter you plan to use for your app.
+
+## Install PyMongo
+
+\`\`\`bash
+python -m pip install pymongo
+\`\`\`
+
+> PyMongo already includes the \`bson\` package it needs. Do not install the separate \`bson\` package from PyPI.
+
+## Connect and run your first queries
+
+Create a \`quickstart.py\` file:
+
+\`\`\`python
+from pymongo import MongoClient
+
+uri = (
+    "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/"
+    "?tls=true&tlsAllowInvalidCertificates=true"
+)
+
+client = MongoClient(uri)
+
+try:
+    client.admin.command("ping")
+
+    db = client["quickstart"]
+    movies = db["movies"]
+
+    movies.delete_many({})
+    movies.insert_many(
+        [
+            {"title": "The Matrix", "year": 1999, "genres": ["sci-fi", "action"]},
+            {"title": "Dune", "year": 2021, "genres": ["sci-fi", "adventure"]},
+            {"title": "Arrival", "year": 2016, "genres": ["sci-fi", "drama"]},
+        ]
+    )
+
+    movies.create_index("title")
+
+    for movie in movies.find(
+        {"year": {"$gte": 2000}},
+        {"_id": 0, "title": 1, "year": 1},
+    ).sort("year", -1):
+        print(movie)
+finally:
+    client.close()
+\`\`\`
+
+Run the script:
+
+\`\`\`bash
+python quickstart.py
+\`\`\`
+
+You should see the recent movie documents printed after a successful \`ping\`.
+
+## Explore the built-in sample data
+
+If you started with DocumentDB Local sample data, add this snippet after \`client.admin.command("ping")\`:
+
+\`\`\`python
+for user in client["sampledb"]["users"].find(
+    {},
+    {"_id": 0, "name": 1, "email": 1},
+).limit(3):
+    print(user)
+\`\`\`
+
+## Use a trusted local certificate instead
+
+If you want certificate validation instead of \`tlsAllowInvalidCertificates=true\`, copy the generated certificate from the container and pass it to \`MongoClient\`.
+
+\`\`\`bash
+docker cp documentdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem
+\`\`\`
+
+\`\`\`python
+client = MongoClient(
+    "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true",
+    tlsCAFile="/absolute/path/documentdb-cert.pem",
+)
+\`\`\`
+
+## Troubleshooting and debugging
+
+If the Python quick start does not work on the first try:
+
+- Verify your local DocumentDB instance is running before you start Python
+- If you used Docker, check \`docker ps --filter "name=documentdb"\` and \`docker logs documentdb\`
+- If you used Linux packages, check \`sudo systemctl status documentdb-gateway\` and \`sudo journalctl -u documentdb-gateway --no-pager -n 50\`
+- If Python cannot import \`pymongo\`, verify the active interpreter with \`python -c "import sys; print(sys.executable)"\` and reinstall with \`python -m pip install pymongo\`
+- If you see TLS or certificate errors, either use the default local self-signed flow with \`tlsAllowInvalidCertificates=true\` or switch to a trusted local certificate with \`tlsCAFile\`
+- Use [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart) to validate the endpoint independently of your application code
+
+## Next steps
+
+- [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart)
+- [Node.js Quick Start](/docs/getting-started/nodejs-setup)
+- [Visual Studio Code Quick Start](/docs/getting-started/vscode-quickstart)
+- [DocumentDB Local](/docs/documentdb-local)
+- [API Reference](/docs/reference)
+- [Samples Gallery](/samples)
+`;
+
+const mongoShellQuickStartContent = `# Mongo Shell Quick Start
+
+Use \`mongosh\` to verify a local DocumentDB instance, inspect sample data, and run your first document commands.
+
+## Prerequisites
+
+- [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/)
+- A local DocumentDB instance from [Docker Quick Start](/docs/getting-started/docker) or [Linux Packages Quick Start](/docs/getting-started/packages)
+- A local port available for DocumentDB (the examples use \`10260\`)
+
+## Start DocumentDB first
+
+For the fastest local setup, start DocumentDB Local with Docker:
+
+\`\`\`bash
+docker run -dt --name documentdb \\
+  -p 10260:10260 \\
+  ghcr.io/documentdb/documentdb/documentdb-local:latest \\
+  --username <YOUR_USERNAME> \\
+  --password <YOUR_PASSWORD>
+\`\`\`
+
+If you prefer a host installation instead of Docker, use [Linux Packages Quick Start](/docs/getting-started/packages) and complete the \`documentdb-setup\` step first.
+
+> Replace \`<YOUR_USERNAME>\` and \`<YOUR_PASSWORD>\` with your own credentials.
+>
+> DocumentDB Local loads built-in sample data into \`sampledb\` by default. It also uses a self-signed certificate by default, so the fastest local \`mongosh\` connection adds \`--tlsAllowInvalidCertificates\`.
+
+## Connect and verify the connection
+
+\`\`\`bash
+mongosh localhost:10260 \\
+  -u <YOUR_USERNAME> \\
+  -p <YOUR_PASSWORD> \\
+  --authenticationMechanism SCRAM-SHA-256 \\
+  --tls \\
+  --tlsAllowInvalidCertificates
+\`\`\`
+
+After you connect, run a quick health check:
+
+\`\`\`javascript
+db.runCommand({ ping: 1 })
+
+db.adminCommand({ listDatabases: 1 })
+\`\`\`
+
+Successful output confirms authentication, TLS, and the gateway endpoint are working.
+
+## Explore the built-in sample data
+
+DocumentDB Local loads sample collections into \`sampledb\` by default.
+
+\`\`\`javascript
+use sampledb
+
+db.users.find(
+  {},
+  { name: 1, email: 1, _id: 0 }
+).limit(3)
+
+db.products.find(
+  { category: "Electronics" },
+  { name: 1, price: 1, _id: 0 }
+)
+\`\`\`
+
+## Create your own collection
+
+\`\`\`javascript
+use quickstart
+
+db.movies.deleteMany({})
+
+db.movies.insertMany([
+  { title: "The Matrix", year: 1999, genres: ["sci-fi", "action"] },
+  { title: "Dune", year: 2021, genres: ["sci-fi", "adventure"] },
+  { title: "Arrival", year: 2016, genres: ["sci-fi", "drama"] }
+])
+
+db.movies.createIndex({ title: 1 })
+
+db.movies.find(
+  { year: { $gte: 2000 } },
+  { _id: 0, title: 1, year: 1 }
+).sort({ year: -1 })
+\`\`\`
+
+## Use a trusted local certificate instead
+
+If you want certificate validation instead of \`--tlsAllowInvalidCertificates\`, copy
+the generated certificate from the container and pass it to \`mongosh\`.
+
+\`\`\`bash
+docker cp documentdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem
+
+mongosh localhost:10260 \\
+  -u <YOUR_USERNAME> \\
+  -p <YOUR_PASSWORD> \\
+  --authenticationMechanism SCRAM-SHA-256 \\
+  --tls \\
+  --tlsCAFile ~/documentdb-cert.pem
+\`\`\`
+
+## Troubleshooting and debugging
+
+If \`mongosh\` does not connect on the first try:
+
+- Verify the local DocumentDB instance is running before you connect
+- If you used Docker, check \`docker ps --filter "name=documentdb"\` and \`docker logs documentdb\`
+- If you used Linux packages, check \`sudo systemctl status documentdb-gateway\` and \`sudo journalctl -u documentdb-gateway --no-pager -n 50\`
+- If authentication fails, confirm the username and password you used when you started DocumentDB or ran \`documentdb-setup\`
+- If TLS validation fails, either keep \`--tlsAllowInvalidCertificates\` for the default local self-signed setup or switch to \`--tlsCAFile\` with a trusted certificate
+- If \`mongosh\` is not installed, follow the [mongosh install guide](https://www.mongodb.com/docs/mongodb-shell/install/)
+- Use [Python Quick Start](/docs/getting-started/python-setup) or [Node.js Quick Start](/docs/getting-started/nodejs-setup) to verify the same endpoint from an application driver
+
+## Next steps
+
+- [Visual Studio Code Quick Start](/docs/getting-started/vscode-quickstart)
+- [API Reference](/docs/reference)
+- [DocumentDB Local](/docs/documentdb-local)
+- [Python Quick Start](/docs/getting-started/python-setup)
+- [Node.js Quick Start](/docs/getting-started/nodejs-setup)
+- [Samples Gallery](/samples)
 `;
 
 const documentdbLocalDataInitializationContent = `## Data initialization
@@ -102,6 +723,160 @@ When \`--init-data-path\` is provided, DocumentDB Local skips the built-in sampl
 and runs only the scripts you mounted.
 `;
 
+const gettingStartedIndexArchitectureContent = `## Architecture Components
+
+DocumentDB consists of three primary components:
+
+1. **pg_documentdb_core**: Core PostgreSQL extension that provides native BSON storage, field access, and indexing primitives.
+2. **pg_documentdb**: Public API surface that implements document commands, CRUD operations, query execution, and index management.
+3. **pg_documentdb_gw**: Gateway that translates MongoDB wire protocol requests into PostgreSQL operations and handles authentication, sessions, and TLS.
+
+Together, these components let you use DocumentDB through MongoDB-compatible tools and drivers while still benefiting from PostgreSQL internals.
+`;
+
+const gettingStartedIndexStartHereContent = `## Start here
+
+If you're new to DocumentDB, use this order:
+
+1. [Docker Quick Start](/docs/getting-started/docker) - Fastest local install for evaluation and development
+2. [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart) - Verify connectivity, authentication, and your first queries
+3. [Node.js Quick Start](/docs/getting-started/nodejs-setup) or [Python Quick Start](/docs/getting-started/python-setup) - Connect from an application driver
+4. [Linux Packages Quick Start](/docs/getting-started/packages) or the [Package Finder](/packages) - Use this when you need a persistent Linux installation instead of Docker
+
+If you prefer an editor-first workflow, start with the [Visual Studio Code Quick Start](/docs/getting-started/vscode-quickstart).
+`;
+
+const gettingStartedIndexVerificationContent = `## Verify your setup
+
+Before moving on to application code, confirm that DocumentDB is reachable and you can run a simple query.
+
+\`\`\`bash
+docker ps --filter "name=documentdb"
+
+mongosh localhost:10260 \\
+  -u <YOUR_USERNAME> \\
+  -p <YOUR_PASSWORD> \\
+  --authenticationMechanism SCRAM-SHA-256 \\
+  --tls \\
+  --tlsAllowInvalidCertificates
+\`\`\`
+
+Then run:
+
+\`\`\`javascript
+db.runCommand({ ping: 1 })
+\`\`\`
+
+For a fuller walkthrough, use the [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart). Driver-based examples are available in the [Node.js Quick Start](/docs/getting-started/nodejs-setup) and [Python Quick Start](/docs/getting-started/python-setup).
+`;
+
+const gettingStartedIndexTroubleshootingContent = `## Troubleshooting and debugging
+
+If setup does not work on the first try:
+
+- Confirm the container is running and port \`10260\` is published with \`docker ps\`.
+- Inspect startup, authentication, and TLS errors with \`docker logs documentdb\`.
+- If you want certificate validation instead of \`tlsAllowInvalidCertificates=true\`, follow the certificate steps in [DocumentDB Local](/docs/documentdb-local).
+- For more verbose local diagnostics, restart DocumentDB Local with \`--log-level debug\`; the available runtime options are documented in [DocumentDB Local](/docs/documentdb-local).
+- If you are installing on a host instead of Docker, use [Linux Packages Quick Start](/docs/getting-started/packages) or the [Package Finder](/packages) to get the correct apt or rpm flow.
+`;
+
+const gettingStartedIndexFeatureExplorationContent = `## Explore key features
+
+Once you can connect successfully, continue with these guides:
+
+- [API Reference](/docs/reference) - MongoDB command and operator coverage
+- [Postgres Extension API](/docs/postgres-api) - PostgreSQL-side functions, types, and operators
+- [DocumentDB Local](/docs/documentdb-local) - Local runtime options, sample data, certificates, and feature notes
+- [Architecture under the hood](/docs/architecture) - How the core, extension, and gateway fit together
+- [Samples Gallery](/samples) - End-to-end examples you can adapt for your own apps
+`;
+
+const gettingStartedIndexNextStepsContent = `## Next Steps
+
+After you finish the initial setup:
+
+- Continue with the [Mongo Shell Quick Start](/docs/getting-started/mongo-shell-quickstart), [Node.js Quick Start](/docs/getting-started/nodejs-setup), or [Python Quick Start](/docs/getting-started/python-setup)
+- Explore the [API Reference](/docs/reference) for detailed command and operator documentation
+- Join our community to get support and contribute
+`;
+
+const articleTitleOverrides: Record<string, string> = {
+  'getting-started/index': 'Getting Started',
+  'getting-started/aws-setup': 'AWS Setup',
+  'getting-started/azure-setup': 'Azure Setup',
+  'getting-started/docker': 'Docker Quick Start',
+  'getting-started/gcp-setup': 'GCP Setup',
+  'getting-started/mongo-shell-quickstart': 'Mongo Shell Quick Start',
+  'getting-started/nodejs-setup': 'Node.js Quick Start',
+  'getting-started/packages': 'Linux Packages Quick Start',
+  'getting-started/python-setup': 'Python Quick Start',
+  'getting-started/vscode-extension-guide': 'Visual Studio Code Extension Guide',
+  'getting-started/vscode-quickstart': 'Visual Studio Code Quick Start',
+  'getting-started/yugabyte-setup': 'YugabyteDB Setup',
+};
+
+const articleDescriptionOverrides: Record<string, string> = {
+  'getting-started/index':
+    'Choose the fastest setup path for DocumentDB, verify your installation, and find troubleshooting and feature guides.',
+  'getting-started/azure-setup':
+    'Deploy and manage DocumentDB on Microsoft Azure for a fully managed experience.',
+  'getting-started/vscode-quickstart':
+    'Install the VS Code extension, connect to DocumentDB Local, and verify your first editor-based workflow.',
+  'getting-started/nodejs-setup':
+    'Start DocumentDB Local, connect with the MongoDB Node.js driver, and run your first queries.',
+  'getting-started/python-setup':
+    'Start DocumentDB Local, connect with PyMongo, and run your first queries from Python.',
+  'getting-started/mongo-shell-quickstart':
+    'Start DocumentDB Local, connect with mongosh, and run your first shell commands.',
+};
+
+function getArticleKey(section: string, file: string): string {
+  return `${section}/${file}`;
+}
+
+function replaceFirstHeading(content: string, heading: string): string {
+  if (/^#\s+.+$/m.test(content)) {
+    return content.replace(/^#\s+.+$/m, `# ${heading}`);
+  }
+
+  return `# ${heading}\n\n${content}`;
+}
+
+function replaceSection(content: string, pattern: RegExp, replacement: string): string {
+  const updatedContent = content.replace(pattern, replacement);
+  return updatedContent === content ? `${content.trimEnd()}\n\n${replacement}` : updatedContent;
+}
+
+function normalizeArticle(section: string, file: string, frontmatter: Record<string, any>, content: string) {
+  const articleKey = getArticleKey(section, file);
+  const headingOverride = articleTitleOverrides[articleKey];
+  const normalizedFrontmatter = {
+    ...frontmatter,
+    title: headingOverride ?? frontmatter.title,
+    description: articleDescriptionOverrides[articleKey] ?? frontmatter.description,
+  };
+
+  let normalizedContent = content;
+
+  if (section === 'getting-started' && file === 'index') {
+    normalizedContent = updateGettingStartedIndexContent(normalizedContent);
+  }
+
+  if (section === 'documentdb-local' && file === 'index') {
+    normalizedContent = updateDocumentDbLocalContent(normalizedContent);
+  }
+
+  if (headingOverride) {
+    normalizedContent = replaceFirstHeading(normalizedContent, headingOverride);
+  }
+
+  return {
+    frontmatter: normalizedFrontmatter,
+    content: normalizedContent,
+  };
+}
+
 function splitPrebuiltNavigation(section: string, links: Link[]): Link[] {
   if (section !== 'getting-started') {
     return links;
@@ -109,17 +884,19 @@ function splitPrebuiltNavigation(section: string, links: Link[]): Link[] {
 
   const isPrebuiltPackages = (link: Link) =>
     link.link.includes('prebuilt-packages') || /pre-built packages/i.test(link.title);
+  const isMergedVscodeGuide = (link: Link) =>
+    link.link.includes('vscode-extension-guide') || /visual studio code extension guide/i.test(link.title);
   const gettingStartedQuickLinks: Link[] = [
     {
-      title: 'Docker',
+      title: articleTitleOverrides['getting-started/docker'],
       link: '/docs/getting-started/docker',
     },
     {
-      title: 'Linux Packages',
+      title: articleTitleOverrides['getting-started/packages'],
       link: '/docs/getting-started/packages',
     },
   ];
-  const filteredLinks = links.filter((link) => !isPrebuiltPackages(link));
+  const filteredLinks = links.filter((link) => !isPrebuiltPackages(link) && !isMergedVscodeGuide(link));
   const gettingStartedIndex = filteredLinks.find((link) => link.link === 'index.md');
 
   if (!gettingStartedIndex) {
@@ -131,10 +908,32 @@ function splitPrebuiltNavigation(section: string, links: Link[]): Link[] {
 }
 
 function updateGettingStartedIndexContent(content: string): string {
-  return content.replace(
-    /- \[Pre-built Packages\]\([^)]+\) - [^\n]+/i,
-    '- [Docker](/docs/getting-started/docker) - Start DocumentDB locally with Docker\n- [Linux Packages](/docs/getting-started/packages) - Install via apt/rpm repositories'
+  let updatedContent = content
+    .replace(/https:\/\/documentdb\.io(?=\/(?:docs|packages|samples)\b)/g, '')
+    .replace(
+      /- Full compatibility with MongoDB wire protocol through the `pg_documentdb_api` layer/i,
+      '- MongoDB-compatible document operations through the `pg_documentdb` extension and `pg_documentdb_gw` gateway'
+    );
+
+  updatedContent = replaceSection(
+    updatedContent,
+    /## Architecture Components[\s\S]*?(?=\n## Common Use Cases)/i,
+    `${gettingStartedIndexArchitectureContent}\n\n`
+  );
+
+  updatedContent = replaceSection(
+    updatedContent,
+    /## Getting Started Options[\s\S]*?(?=\n## Community and Support)/i,
+    `${gettingStartedIndexStartHereContent}\n\n${gettingStartedIndexVerificationContent}\n\n${gettingStartedIndexTroubleshootingContent}\n\n${gettingStartedIndexFeatureExplorationContent}\n\n`
+  );
+
+  updatedContent = replaceSection(
+    updatedContent,
+    /## Next Steps[\s\S]*$/i,
+    gettingStartedIndexNextStepsContent
   );
+
+  return updatedContent;
 }
 
 function updateDocumentDbLocalContent(content: string): string {
@@ -175,22 +974,36 @@ export function getArticleNavigation(section: string): Link[] {
     // e.g., "index.md" -> "/docs/section"
     // e.g., "nodejs-setup.md" -> "/docs/section/nodejs-setup"
     let transformedLink = link.link;
+    let transformedFile = '';
     
     if (transformedLink.endsWith('.md')) {
-      const filename = transformedLink.replace('.md', '');
-      if (filename === 'index') {
+      transformedFile = transformedLink.replace('.md', '');
+      if (transformedFile === 'index') {
         transformedLink = `/docs/${section}`;
       } else {
-        transformedLink = `/docs/${section}/${filename}`;
+        transformedLink = `/docs/${section}/${transformedFile}`;
       }
+    } else if (transformedLink.startsWith(`/docs/${section}`)) {
+      const remainingPath = transformedLink.slice(`/docs/${section}`.length).replace(/^\/+|\/+$/g, '');
+      transformedFile = remainingPath || 'index';
     }
     
     return {
       ...link,
+      title: articleTitleOverrides[getArticleKey(section, transformedFile)] ?? link.title,
       link: transformedLink,
       // Recursively transform children if they exist
       children: link.children?.map(child => ({
         ...child,
+        title:
+          articleTitleOverrides[
+            getArticleKey(
+              section,
+              child.link.endsWith('.md')
+                ? child.link.replace('.md', '')
+                : child.link.slice(`/docs/${section}`.length).replace(/^\/+|\/+$/g, '') || 'index'
+            )
+          ] ?? child.title,
         link: child.link.endsWith('.md') 
           ? `/docs/${section}/${child.link.replace('.md', '')}`
           : child.link
@@ -268,8 +1081,8 @@ export function getArticleByPath(section: string, slug: string[] = []): {
     return {
       content: dockerGuideContent,
       frontmatter: {
-        title: 'Docker',
-        description: 'Run DocumentDB locally using Docker.',
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: 'Start DocumentDB Local with Docker, verify the connection, and find troubleshooting and next-step guidance.',
       },
       navigation,
       section,
@@ -281,8 +1094,60 @@ export function getArticleByPath(section: string, slug: string[] = []): {
     return {
       content: linuxPackagesGuideContent,
       frontmatter: {
-        title: 'Linux Packages',
-        description: 'Install DocumentDB via apt and rpm packages.',
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: 'Install DocumentDB with Linux packages, run documentdb-setup, verify the gateway, and find troubleshooting guidance.',
+      },
+      navigation,
+      section,
+      file,
+    };
+  }
+
+  if (section === 'getting-started' && file === 'nodejs-setup') {
+    return {
+      content: nodejsGuideContent,
+      frontmatter: {
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: articleDescriptionOverrides[getArticleKey(section, file)],
+      },
+      navigation,
+      section,
+      file,
+    };
+  }
+
+  if (section === 'getting-started' && file === 'python-setup') {
+    return {
+      content: pythonQuickStartContent,
+      frontmatter: {
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: articleDescriptionOverrides[getArticleKey(section, file)],
+      },
+      navigation,
+      section,
+      file,
+    };
+  }
+
+  if (section === 'getting-started' && file === 'vscode-quickstart') {
+    return {
+      content: vscodeQuickStartGuideContent,
+      frontmatter: {
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: articleDescriptionOverrides[getArticleKey(section, file)],
+      },
+      navigation,
+      section,
+      file,
+    };
+  }
+
+  if (section === 'getting-started' && file === 'mongo-shell-quickstart') {
+    return {
+      content: mongoShellQuickStartContent,
+      frontmatter: {
+        title: articleTitleOverrides[getArticleKey(section, file)],
+        description: articleDescriptionOverrides[getArticleKey(section, file)],
       },
       navigation,
       section,
@@ -298,19 +1163,11 @@ export function getArticleByPath(section: string, slug: string[] = []): {
 
   // Parse front matter
   const { data: frontmatter, content } = matter(rawContent);
-  let normalizedContent = content;
-
-  if (section === 'getting-started' && file === 'index') {
-    normalizedContent = updateGettingStartedIndexContent(normalizedContent);
-  }
-
-  if (section === 'documentdb-local' && file === 'index') {
-    normalizedContent = updateDocumentDbLocalContent(normalizedContent);
-  }
+  const normalizedArticle = normalizeArticle(section, file, frontmatter, content);
 
   return {
-    content: normalizedContent,
-    frontmatter,
+    content: normalizedArticle.content,
+    frontmatter: normalizedArticle.frontmatter,
     navigation,
     section,
     file

From fa4ce5e959971d127fe909919d4e912d56200138 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Fri, 10 Apr 2026 14:56:14 -0400
Subject: [PATCH 2/2] Refine getting-started install primer

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>
---
 app/docs/[section]/[[...slug]]/page.tsx | 168 +++++++++++++++++-------
 app/services/articleService.ts          |   4 +
 2 files changed, 124 insertions(+), 48 deletions(-)

diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 657c914..3e56997 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -12,6 +12,12 @@ const dockerQuickRunCommand = `docker run -dt --name documentdb \\
   --username <YOUR_USERNAME> \\
   --password <YOUR_PASSWORD>`;
 
+const primerPrimaryLinkClass =
+    "inline-flex w-full items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400 sm:w-auto";
+
+const primerSecondaryLinkClass =
+    "font-semibold text-blue-300 transition-colors hover:text-blue-200";
+
 export async function generateStaticParams() {
     const paths = getAllArticlePaths();
 
@@ -157,57 +163,123 @@ export default async function ArticlePage({ params }: PageProps) {
                         {frontmatter.layout === 'coming-soon' && <ComingSoon />}
 
                         {showInstallPrimer && (
-                            <section className="mb-8 rounded-xl border border-blue-500/30 bg-blue-500/5 p-5">
-                                <h2 className="text-xl font-semibold text-white">Install and verify DocumentDB</h2>
-                                <p className="mt-2 text-sm text-gray-300">
-                                    Start with Docker for the fastest setup, or choose Linux packages for persistent servers. Then verify the connection with mongosh before moving to a driver quick start.
+                            <section className="mb-8 rounded-2xl border border-blue-500/30 bg-gradient-to-br from-blue-500/10 via-neutral-900/90 to-neutral-900/90 p-6">
+                                <p className="text-xs font-semibold uppercase tracking-[0.18em] text-blue-200">
+                                    Recommended flow
                                 </p>
-                                <div className="mt-4 grid gap-4 lg:grid-cols-2">
-                                    <div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
-                                        <p className="mb-3 text-sm font-semibold text-white">Quick run with Docker</p>
-                                        <CommandSnippet command={dockerQuickRunCommand} label="Docker" />
-                                        <div className="mt-4 flex flex-wrap gap-3">
-                                            <Link
-                                                href="/docs/getting-started/mongo-shell-quickstart"
-                                                className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
-                                            >
-                                                Mongo Shell Quick Start
-                                            </Link>
-                                            <Link
-                                                href="/docs/getting-started/mongo-shell-quickstart"
-                                                className="inline-flex items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400"
-                                            >
-                                                Mongo Shell Quick Start
-                                            </Link>
+                                <h2 className="mt-2 text-2xl font-semibold text-white">
+                                    Install and verify DocumentDB
+                                </h2>
+                                <p className="mt-2 max-w-3xl text-sm leading-6 text-gray-300">
+                                    Choose one install path first. After DocumentDB is running, verify the
+                                    connection with mongosh before moving to a driver quick start.
+                                </p>
+                                <div className="mt-5 rounded-xl border border-neutral-800 bg-neutral-950/40 p-4">
+                                    <div className="mb-4 flex items-start gap-3">
+                                        <span className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-blue-400/30 bg-blue-500/10 text-xs font-semibold text-blue-200">
+                                            1
+                                        </span>
+                                        <div>
+                                            <p className="text-sm font-semibold text-white">
+                                                Choose an install path
+                                            </p>
+                                            <p className="mt-1 text-sm text-gray-400">
+                                                Use Docker for the fastest local setup, or Linux packages for a
+                                                persistent host installation.
+                                            </p>
                                         </div>
-                                        <p className="mt-3 text-sm text-gray-400">
-                                            Recommended first path: Docker -&gt; Mongo Shell Quick Start -&gt; Node.js Quick Start or Python Quick Start.
-                                        </p>
                                     </div>
-                                    <div className="rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
-                                        <p className="text-sm font-semibold text-white">Install from Linux packages</p>
-                                        <p className="mt-2 text-sm text-gray-400">
-                                            Use the package finder to generate the exact apt/rpm command for your distro, architecture, and PostgreSQL version.
-                                        </p>
-                                        <div className="mt-4 flex flex-wrap gap-3">
-                                            <Link
-                                                href="/docs/getting-started/docker"
-                                                className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
-                                            >
-                                                Docker Quick Start
-                                            </Link>
-                                            <Link
-                                                href="/packages"
-                                                className="inline-flex items-center justify-center rounded-md bg-blue-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-blue-400"
-                                            >
-                                                Open package finder
-                                            </Link>
-                                            <Link
-                                                href="/docs/getting-started/packages"
-                                                className="inline-flex items-center justify-center rounded-md border border-neutral-600 px-4 py-2 text-sm font-semibold text-gray-200 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
-                                            >
-                                                Linux Packages Quick Start
-                                            </Link>
+                                    <div className="grid gap-4 lg:grid-cols-2">
+                                        <div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
+                                            <p className="text-sm font-semibold text-white">
+                                                Run locally with Docker
+                                            </p>
+                                            <p className="mt-2 text-sm text-gray-400">
+                                                Best for evaluation, local development, and quick testing.
+                                            </p>
+                                            <div className="mt-4">
+                                                <CommandSnippet command={dockerQuickRunCommand} label="Docker" />
+                                            </div>
+                                            <div className="mt-4">
+                                                <Link
+                                                    href="/docs/getting-started/docker"
+                                                    className={primerPrimaryLinkClass}
+                                                >
+                                                    Docker Quick Start
+                                                </Link>
+                                            </div>
+                                        </div>
+                                        <div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
+                                            <p className="text-sm font-semibold text-white">
+                                                Install from Linux packages
+                                            </p>
+                                            <p className="mt-2 text-sm text-gray-400">
+                                                Use the repository-backed package flow when you want a persistent
+                                                server install. Generate the exact apt or rpm command with the{" "}
+                                                <Link href="/packages" className={primerSecondaryLinkClass}>
+                                                    Package Finder
+                                                </Link>
+                                                .
+                                            </p>
+                                            <div className="mt-4">
+                                                <Link
+                                                    href="/docs/getting-started/packages"
+                                                    className={primerPrimaryLinkClass}
+                                                >
+                                                    Linux Packages Quick Start
+                                                </Link>
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+                                <div className="mt-4 rounded-xl border border-neutral-800 bg-neutral-950/40 p-4">
+                                    <div className="flex items-start gap-3">
+                                        <span className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-blue-400/30 bg-blue-500/10 text-xs font-semibold text-blue-200">
+                                            2
+                                        </span>
+                                        <div className="min-w-0">
+                                            <p className="text-sm font-semibold text-white">
+                                                Recommended: verify with mongosh
+                                            </p>
+                                            <p className="mt-1 text-sm text-gray-400">
+                                                This is the fastest shared validation path after either install
+                                                option because it confirms authentication, TLS, and a working
+                                                endpoint before you add editor or driver setup. If you already
+                                                know your target workflow, you can skip this and continue directly
+                                                with VS Code or a driver quick start.
+                                            </p>
+                                            <div className="mt-4 flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:gap-4">
+                                                <Link
+                                                    href="/docs/getting-started/mongo-shell-quickstart"
+                                                    className={primerPrimaryLinkClass}
+                                                >
+                                                    Mongo Shell Quick Start
+                                                </Link>
+                                                <p className="text-sm text-gray-400">
+                                                    Or go directly to{" "}
+                                                    <Link
+                                                        href="/docs/getting-started/vscode-quickstart"
+                                                        className={primerSecondaryLinkClass}
+                                                    >
+                                                        Visual Studio Code Quick Start
+                                                    </Link>
+                                                    ,{" "}
+                                                    <Link
+                                                        href="/docs/getting-started/nodejs-setup"
+                                                        className={primerSecondaryLinkClass}
+                                                    >
+                                                        Node.js Quick Start
+                                                    </Link>{" "}
+                                                    or{" "}
+                                                    <Link
+                                                        href="/docs/getting-started/python-setup"
+                                                        className={primerSecondaryLinkClass}
+                                                    >
+                                                        Python Quick Start
+                                                    </Link>
+                                                    .
+                                                </p>
+                                            </div>
                                         </div>
                                     </div>
                                 </div>
diff --git a/app/services/articleService.ts b/app/services/articleService.ts
index 9b60ee6..aec5f59 100644
--- a/app/services/articleService.ts
+++ b/app/services/articleService.ts
@@ -863,6 +863,10 @@ function normalizeArticle(section: string, file: string, frontmatter: Record<str
     normalizedContent = updateGettingStartedIndexContent(normalizedContent);
   }
 
+  if (section === 'getting-started' && file === 'azure-setup') {
+    normalizedContent = normalizedContent.replace(/Micrtosoft/g, 'Microsoft');
+  }
+
   if (section === 'documentdb-local' && file === 'index') {
     normalizedContent = updateDocumentDbLocalContent(normalizedContent);
   }