From 84271b82cd8191e8d9a9e25f6fd9895dd40eea62 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Mon, 3 Aug 2026 14:34:51 -0400
Subject: [PATCH 1/4] Add versioned documentation support

Content pipeline: content.config.json sources accept a 'versions' list
({label, ref}); compile-content clones each ref and compiles the same
mappings into versioned/<label>/, cleaned by compile-clean.

Routes: /docs/v/[version]/[section]/[[...slug]] renders archived article
snapshots with an old-version banner, noindex metadata, and a link back to
the current page; /docs/v/[version] is the snapshot landing; /docs/versions
lists current and archived versions. Current article pages get a version
switcher when archived copies of the page exist.

SEO: archived pages are noindex and excluded from the sitemap; only the
current docs are advertised to crawlers. Markdown internal links now honor
the configured base path (needed for project-page deployments).

Also maps the docs repo's release-notes section into the articles tree.
---
 .gitignore                                    |   3 +
 app/components/VersionSwitcher.tsx            |  52 +++++++
 app/docs/[section]/[[...slug]]/page.tsx       |  24 ++++
 .../[version]/[section]/[[...slug]]/page.tsx  | 131 +++++++++++++++++
 app/docs/v/[version]/page.tsx                 |  82 +++++++++++
 app/docs/versions/page.tsx                    | 111 +++++++++++++++
 app/services/versionService.ts                | 133 ++++++++++++++++++
 articles/content.yml                          |   4 +
 content.config.json                           |   7 +-
 next.config.ts                                |   5 +
 scripts/compile-clean.tsx                     |   9 ++
 scripts/compile-content.tsx                   |  53 +++++++
 scripts/generate-sitemap.mjs                  |   3 +
 13 files changed, 616 insertions(+), 1 deletion(-)
 create mode 100644 app/components/VersionSwitcher.tsx
 create mode 100644 app/docs/v/[version]/[section]/[[...slug]]/page.tsx
 create mode 100644 app/docs/v/[version]/page.tsx
 create mode 100644 app/docs/versions/page.tsx
 create mode 100644 app/services/versionService.ts

diff --git a/.gitignore b/.gitignore
index 5d29287..8405fb7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,9 @@
 # Temporary content cloning directory
 _tmp/
 
+# Compiled versioned documentation snapshots
+/versioned/
+
 # Reference files (compiled into the repo root from documentdb/docs; anchored
 # so the patterns cannot swallow tracked paths like app/docs/reference/)
 /api-reference/
diff --git a/app/components/VersionSwitcher.tsx b/app/components/VersionSwitcher.tsx
new file mode 100644
index 0000000..cd2c1dc
--- /dev/null
+++ b/app/components/VersionSwitcher.tsx
@@ -0,0 +1,52 @@
+import Link from "next/link";
+
+export interface VersionTarget {
+    label: string;
+    href: string;
+}
+
+/**
+ * Static version dropdown shown on documentation pages. Server-rendered
+ * (a <details> disclosure, no client JS) so it works in the static export.
+ */
+export default function VersionSwitcher({
+    current,
+    targets,
+}: {
+    /** Label of the version being viewed (e.g. "current (v0.114-0)"). */
+    current: string;
+    /** Other versions of this page the reader can switch to. */
+    targets: VersionTarget[];
+}) {
+    return (
+        <details className="relative inline-block text-left group">
+            <summary className="cursor-pointer list-none inline-flex items-center gap-2 rounded-lg border border-neutral-700/60 bg-neutral-800/60 px-3 py-1.5 text-xs font-medium text-gray-300 hover:text-white hover:border-neutral-500 transition-colors">
+                <svg className="h-3.5 w-3.5 text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
+                        d="M7 7h10M7 12h10M7 17h6" />
+                </svg>
+                Version: {current}
+                <svg className="h-3 w-3 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+                </svg>
+            </summary>
+            <div className="absolute z-20 mt-2 w-56 rounded-lg border border-neutral-700/60 bg-neutral-800 p-1 shadow-xl">
+                {targets.map((target) => (
+                    <Link
+                        key={target.href}
+                        href={target.href}
+                        className="block rounded-md px-3 py-2 text-xs text-gray-300 hover:bg-neutral-700/60 hover:text-white transition-colors"
+                    >
+                        {target.label}
+                    </Link>
+                ))}
+                <Link
+                    href="/docs/versions"
+                    className="block rounded-md px-3 py-2 text-xs text-blue-400 hover:bg-neutral-700/60 hover:text-blue-300 transition-colors border-t border-neutral-700/60 mt-1 pt-2"
+                >
+                    All versions →
+                </Link>
+            </div>
+        </details>
+    );
+}
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 7a0a5dc..13d6314 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -6,6 +6,8 @@ import { getMetadata } from "../../../services/metadataService";
 import ComingSoon from "../../../components/ComingSoon";
 import CommandSnippet from "../../../components/CommandSnippet";
 import Markdown from "../../../components/Markdown";
+import VersionSwitcher from "../../../components/VersionSwitcher";
+import { getDocVersions, versionedArticleExists } from "../../../services/versionService";
 
 const dockerQuickRunCommand = `docker run -dt --name documentdb \\
   -p 10260:10260 \\
@@ -321,6 +323,28 @@ export default async function ArticlePage({ params }: PageProps) {
                             </section>
                         )}
 
+                        {/* Version switcher: shown when archived snapshots of this page exist */}
+                        {(() => {
+                            const versionTargets = getDocVersions()
+                                .filter((version) => versionedArticleExists(version, section, file))
+                                .map((version) => ({
+                                    label: `${version} (archived)`,
+                                    href:
+                                        file === 'index'
+                                            ? `/docs/v/${version}/${section}`
+                                            : `/docs/v/${version}/${section}/${file}`,
+                                }));
+
+                            return versionTargets.length > 0 ? (
+                                <div className="mb-6">
+                                    <VersionSwitcher
+                                        current="current (latest release)"
+                                        targets={versionTargets}
+                                    />
+                                </div>
+                            ) : null;
+                        })()}
+
                         {/* Markdown Content */}
                         <Markdown
                             content={content}
diff --git a/app/docs/v/[version]/[section]/[[...slug]]/page.tsx b/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
new file mode 100644
index 0000000..d2732b7
--- /dev/null
+++ b/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
@@ -0,0 +1,131 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { capitalCase } from "change-case";
+import {
+    getAllVersionedArticlePaths,
+    getVersionedArticleByPath,
+} from "../../../../../services/versionService";
+import { getArticleByPath } from "../../../../../services/articleService";
+import Markdown from "../../../../../components/Markdown";
+import VersionSwitcher from "../../../../../components/VersionSwitcher";
+
+export async function generateStaticParams() {
+    return getAllVersionedArticlePaths().map((path) => ({
+        version: path.version,
+        section: path.section,
+        slug: path.slug,
+    }));
+}
+
+interface PageProps {
+    params: Promise<{
+        version: string;
+        section: string;
+        slug?: string[];
+    }>;
+}
+
+export async function generateMetadata({ params }: PageProps) {
+    const { version, section, slug = [] } = await params;
+    const articleData = getVersionedArticleByPath(version, section, slug);
+    const pageTitle = articleData?.frontmatter.title || section;
+
+    return {
+        title: `${pageTitle} (${version}) - DocumentDB Documentation`,
+        description: articleData?.frontmatter.description || "",
+        // Archived versions must never outrank the current documentation in
+        // search results.
+        robots: { index: false, follow: false },
+    };
+}
+
+export default async function VersionedArticlePage({ params }: PageProps) {
+    const { version, section, slug = [] } = await params;
+    const articleData = getVersionedArticleByPath(version, section, slug);
+
+    if (!articleData) {
+        return notFound();
+    }
+
+    const { content, frontmatter, navigation, file } = articleData;
+    const pageTitle = frontmatter.title || section;
+    const sectionTitle = capitalCase(section)
+        .replace(/documentdb/i, "DocumentDB")
+        .replace(/api/i, "API");
+
+    // Link the banner to the same page in the current docs when it still
+    // exists there, otherwise to the section root.
+    const currentEquivalent = getArticleByPath(section, slug)
+        ? slug.length > 0
+            ? `/docs/${section}/${slug.join("/")}`
+            : `/docs/${section}`
+        : "/docs";
+
+    const navigationLinks = navigation.map((item) => (
+        <Link
+            key={item.link}
+            href={item.link}
+            className="block w-full text-left px-4 py-3 rounded-lg text-sm text-gray-300 hover:text-white hover:bg-neutral-700/50 transition-all duration-200"
+        >
+            {item.title}
+        </Link>
+    ));
+
+    return (
+        <div className="min-h-screen bg-neutral-900 relative overflow-hidden">
+            <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
+
+            <div className="relative flex min-h-screen">
+                {/* Left Sidebar */}
+                <div className="hidden w-80 bg-neutral-800/50 backdrop-blur-sm border-r border-neutral-700/50 md:flex flex-col">
+                    <div className="p-6 border-b border-neutral-700/50">
+                        <Link
+                            href="/docs"
+                            className="text-blue-400 hover:text-blue-300 text-sm mb-4 flex items-center transition-colors"
+                        >
+                            ← Back to Documentation
+                        </Link>
+                        <p className="text-2xl font-bold text-white">{sectionTitle}</p>
+                        <p className="mt-1 text-xs font-semibold uppercase tracking-wider text-amber-400">
+                            {version} snapshot
+                        </p>
+                    </div>
+                    <div className="flex-1 p-4 overflow-y-auto">
+                        <nav className="space-y-1">{navigationLinks}</nav>
+                    </div>
+                </div>
+
+                {/* Main Content */}
+                <div className="flex-1 p-4 sm:p-8 overflow-y-auto">
+                    <div className="max-w-4xl">
+                        {/* Old-version banner */}
+                        <div className="mb-6 flex flex-col gap-3 rounded-xl border border-amber-500/40 bg-amber-500/10 p-4 sm:flex-row sm:items-center sm:justify-between">
+                            <p className="text-sm text-amber-200">
+                                You are viewing the frozen documentation for{" "}
+                                <span className="font-semibold">{version}</span>. It is not
+                                updated and may not reflect the latest release.
+                            </p>
+                            <Link
+                                href={currentEquivalent}
+                                className="inline-flex shrink-0 items-center rounded-lg bg-amber-500/20 border border-amber-500/40 px-3 py-1.5 text-xs font-semibold text-amber-100 hover:bg-amber-500/30 transition-colors"
+                            >
+                                View current version →
+                            </Link>
+                        </div>
+
+                        <div className="mb-6">
+                            <VersionSwitcher
+                                current={version}
+                                targets={[
+                                    { label: "current (latest release)", href: currentEquivalent },
+                                ]}
+                            />
+                        </div>
+
+                        <Markdown content={content} />
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}
diff --git a/app/docs/v/[version]/page.tsx b/app/docs/v/[version]/page.tsx
new file mode 100644
index 0000000..bcc943b
--- /dev/null
+++ b/app/docs/v/[version]/page.tsx
@@ -0,0 +1,82 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { capitalCase } from "change-case";
+import { getDocVersions, getVersionedSections } from "../../../services/versionService";
+
+export async function generateStaticParams() {
+    return getDocVersions().map((version) => ({ version }));
+}
+
+interface PageProps {
+    params: Promise<{ version: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps) {
+    const { version } = await params;
+    return {
+        title: `${version} Documentation - DocumentDB`,
+        description: `Archived DocumentDB documentation for ${version}.`,
+        robots: { index: false, follow: false },
+    };
+}
+
+export default async function VersionLandingPage({ params }: PageProps) {
+    const { version } = await params;
+    const sections = getVersionedSections(version);
+
+    if (sections.length === 0) {
+        return notFound();
+    }
+
+    return (
+        <div className="min-h-screen bg-neutral-900 relative overflow-hidden">
+            <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
+
+            <div className="relative mx-auto max-w-4xl px-4 py-16 sm:px-8">
+                <div className="mb-8 rounded-xl border border-amber-500/40 bg-amber-500/10 p-4">
+                    <p className="text-sm text-amber-200">
+                        This is the frozen documentation snapshot for{" "}
+                        <span className="font-semibold">{version}</span>.{" "}
+                        <Link href="/docs" className="font-semibold text-amber-100 underline hover:text-white">
+                            Switch to the current documentation →
+                        </Link>
+                    </p>
+                </div>
+
+                <h1 className="text-4xl font-bold text-white">
+                    DocumentDB {version} Documentation
+                </h1>
+                <p className="mt-3 text-gray-400">
+                    Documentation sections as they were at the {version} release.
+                </p>
+
+                <div className="mt-10 grid gap-4 sm:grid-cols-2">
+                    {sections.map((section) => (
+                        <Link
+                            key={section}
+                            href={`/docs/v/${version}/${section}`}
+                            className="rounded-xl border border-neutral-700/60 bg-neutral-800/50 p-5 transition-colors hover:border-blue-500/50 hover:bg-neutral-800"
+                        >
+                            <p className="font-semibold text-white">
+                                {capitalCase(section)
+                                    .replace(/documentdb/i, "DocumentDB")
+                                    .replace(/api/i, "API")}
+                            </p>
+                            <p className="mt-1 text-sm text-gray-400">
+                                {section} docs at {version}
+                            </p>
+                        </Link>
+                    ))}
+                </div>
+
+                <p className="mt-10 text-sm text-gray-500">
+                    Looking for a different version? See{" "}
+                    <Link href="/docs/versions" className="text-blue-400 hover:text-blue-300">
+                        all documentation versions
+                    </Link>
+                    .
+                </p>
+            </div>
+        </div>
+    );
+}
diff --git a/app/docs/versions/page.tsx b/app/docs/versions/page.tsx
new file mode 100644
index 0000000..1c19774
--- /dev/null
+++ b/app/docs/versions/page.tsx
@@ -0,0 +1,111 @@
+import Link from "next/link";
+import { getMetadata } from "../../services/metadataService";
+import { getDocVersions } from "../../services/versionService";
+
+export async function generateMetadata() {
+    return getMetadata({
+        title: "Documentation Versions - DocumentDB",
+        description:
+            "Browse DocumentDB documentation for the current release or archived snapshots of previous versions.",
+        path: "/docs/versions/",
+    });
+}
+
+export default function VersionsPage() {
+    const hostedVersions = getDocVersions();
+
+    return (
+        <div className="min-h-screen bg-neutral-900 relative overflow-hidden">
+            <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
+
+            <div className="relative mx-auto max-w-4xl px-4 py-16 sm:px-8">
+                <h1 className="text-4xl font-bold text-white">Documentation Versions</h1>
+                <p className="mt-3 max-w-2xl text-gray-400">
+                    The documentation site always describes the latest DocumentDB release,
+                    with in-page annotations (&quot;added in&quot;, &quot;default changed
+                    in&quot;) covering recent changes. Frozen snapshots are hosted for
+                    recent versions; older versions remain browsable as git tags.
+                </p>
+
+                <div className="mt-10 space-y-4">
+                    {/* Current */}
+                    <Link
+                        href="/docs"
+                        className="block rounded-xl border border-blue-500/40 bg-blue-500/10 p-5 transition-colors hover:bg-blue-500/20"
+                    >
+                        <div className="flex items-center justify-between">
+                            <div>
+                                <p className="font-semibold text-white">
+                                    Current{" "}
+                                    <span className="ml-2 rounded-full bg-blue-500/30 px-2 py-0.5 text-xs font-medium text-blue-200">
+                                        latest release
+                                    </span>
+                                </p>
+                                <p className="mt-1 text-sm text-gray-400">
+                                    Continuously updated documentation for the latest DocumentDB
+                                    release.
+                                </p>
+                            </div>
+                            <span className="text-blue-400">→</span>
+                        </div>
+                    </Link>
+
+                    {/* Hosted snapshots */}
+                    {hostedVersions.map((version) => (
+                        <Link
+                            key={version}
+                            href={`/docs/v/${version}`}
+                            className="block rounded-xl border border-neutral-700/60 bg-neutral-800/50 p-5 transition-colors hover:border-neutral-500"
+                        >
+                            <div className="flex items-center justify-between">
+                                <div>
+                                    <p className="font-semibold text-white">
+                                        {version}{" "}
+                                        <span className="ml-2 rounded-full bg-neutral-700 px-2 py-0.5 text-xs font-medium text-gray-300">
+                                            archived snapshot
+                                        </span>
+                                    </p>
+                                    <p className="mt-1 text-sm text-gray-400">
+                                        Frozen documentation as of the {version} release. Not
+                                        updated.
+                                    </p>
+                                </div>
+                                <span className="text-gray-500">→</span>
+                            </div>
+                        </Link>
+                    ))}
+                </div>
+
+                <div className="mt-10 rounded-xl border border-neutral-700/60 bg-neutral-800/30 p-5">
+                    <p className="font-semibold text-white">Older versions</p>
+                    <p className="mt-1 text-sm text-gray-400">
+                        Documentation for versions that are no longer hosted here is
+                        preserved as git tags on the docs repository — browse the Markdown
+                        exactly as it was at that release.
+                    </p>
+                    <div className="mt-3 flex flex-wrap gap-4 text-sm">
+                        <a
+                            href="https://github.com/documentdb/docs/tags"
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="text-blue-400 hover:text-blue-300"
+                        >
+                            Docs repository tags →
+                        </a>
+                        <a
+                            href="https://github.com/documentdb/documentdb/releases"
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="text-blue-400 hover:text-blue-300"
+                        >
+                            DocumentDB releases →
+                        </a>
+                        <Link href="/docs/release-notes" className="text-blue-400 hover:text-blue-300">
+                            Release notes →
+                        </Link>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}
diff --git a/app/services/versionService.ts b/app/services/versionService.ts
new file mode 100644
index 0000000..66b70c7
--- /dev/null
+++ b/app/services/versionService.ts
@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import { load as loadYaml } from 'js-yaml';
+import matter from 'gray-matter';
+import { Link } from '../types/Link';
+
+/**
+ * Serves frozen documentation snapshots compiled by scripts/compile-content.tsx
+ * into versioned/<label>/. The main (rolling) documentation is served by
+ * articleService.ts from articles/; this module only handles archived versions
+ * rendered under /docs/v/<label>/.
+ *
+ * Versioned pages render the snapshot content as-is: the editorial overrides
+ * that articleService applies to current pages deliberately do not apply here,
+ * because a snapshot must show the docs exactly as they were at the tag.
+ */
+
+const versionedDirectory = path.join(process.cwd(), 'versioned');
+
+/** Labels of all compiled documentation versions, newest first. */
+export function getDocVersions(): string[] {
+  if (!fs.existsSync(versionedDirectory)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(versionedDirectory, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name)
+    .sort()
+    .reverse();
+}
+
+function versionArticlesDir(version: string): string {
+  return path.join(versionedDirectory, version, 'articles');
+}
+
+/** Article sections available in a given version snapshot. */
+export function getVersionedSections(version: string): string[] {
+  const base = versionArticlesDir(version);
+
+  if (!fs.existsSync(base)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name);
+}
+
+/** Whether a specific article exists in a version snapshot. */
+export function versionedArticleExists(version: string, section: string, file: string): boolean {
+  return fs.existsSync(path.join(versionArticlesDir(version), section, `${file}.md`));
+}
+
+/** All {version, section, slug} combinations, for generateStaticParams. */
+export function getAllVersionedArticlePaths(): { version: string; section: string; slug: string[] }[] {
+  const paths: { version: string; section: string; slug: string[] }[] = [];
+
+  for (const version of getDocVersions()) {
+    for (const section of getVersionedSections(version)) {
+      const sectionPath = path.join(versionArticlesDir(version), section);
+      const files = fs
+        .readdirSync(sectionPath, { withFileTypes: true })
+        .filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
+        .map((dirent) => dirent.name.replace('.md', ''));
+
+      for (const file of files) {
+        paths.push({ version, section, slug: file === 'index' ? [] : [file] });
+      }
+    }
+  }
+
+  return paths;
+}
+
+/** Sidebar navigation for a versioned section, with links under /docs/v/<version>/. */
+export function getVersionedNavigation(version: string, section: string): Link[] {
+  const navPath = path.join(versionArticlesDir(version), section, 'navigation.yml');
+
+  if (!fs.existsSync(navPath)) {
+    return [];
+  }
+
+  const rawLinks = loadYaml(fs.readFileSync(navPath, 'utf8')) as Link[];
+
+  return rawLinks.map((link) => {
+    let transformedLink = link.link;
+
+    if (transformedLink.endsWith('.md')) {
+      const file = transformedLink.replace('.md', '');
+      transformedLink =
+        file === 'index'
+          ? `/docs/v/${version}/${section}`
+          : `/docs/v/${version}/${section}/${file}`;
+    }
+
+    return { ...link, link: transformedLink, children: undefined };
+  });
+}
+
+/** Load a versioned article: raw snapshot content plus parsed front matter. */
+export function getVersionedArticleByPath(
+  version: string,
+  section: string,
+  slug: string[] = []
+): {
+  content: string;
+  frontmatter: { title?: string; [key: string]: any };
+  navigation: Link[];
+  version: string;
+  section: string;
+  file: string;
+} | null {
+  const file = slug.length > 0 ? slug[slug.length - 1] : 'index';
+  const markdownPath = path.join(versionArticlesDir(version), section, `${file}.md`);
+
+  if (!fs.existsSync(markdownPath)) {
+    return null;
+  }
+
+  const { data: frontmatter, content } = matter(fs.readFileSync(markdownPath, 'utf8'));
+
+  return {
+    content,
+    frontmatter,
+    navigation: getVersionedNavigation(version, section),
+    version,
+    section,
+    file,
+  };
+}
diff --git a/articles/content.yml b/articles/content.yml
index 84b6781..b1a133c 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -14,5 +14,9 @@ landing:
       link: /docs/documentdb-local
     - title: Architecture under the hood (Coming soon)
       link: /docs/architecture
+    - title: Release Notes
+      link: /docs/release-notes
+    - title: Documentation Versions
+      link: /docs/versions
     - title: Samples & Demos
       link: /samples
diff --git a/content.config.json b/content.config.json
index 917e4c2..9ed62af 100644
--- a/content.config.json
+++ b/content.config.json
@@ -27,8 +27,13 @@
         {
           "source": "kubernetes-operator",
           "target": "articles/kubernetes-operator"
+        },
+        {
+          "source": "release-notes",
+          "target": "articles/release-notes"
         }
-      ]
+      ],
+      "versions": []
     }
   ],
   "include": [
diff --git a/next.config.ts b/next.config.ts
index 0fc40b9..5d341cf 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -7,6 +7,11 @@ const normalizedBasePath = rawBasePath
 
 const nextConfig: NextConfig = {
   output: "export",
+  // Expose the base path to client components (Markdown link resolution);
+  // next/link handles it automatically but raw anchors in markdown do not.
+  env: {
+    NEXT_PUBLIC_BASE_PATH: normalizedBasePath ?? "",
+  },
   // Emit directory/index.html instead of page.html so GitHub Pages serves
   // both /docs and /docs/ (without this, the trailing-slash form is a 404).
   trailingSlash: true,
diff --git a/scripts/compile-clean.tsx b/scripts/compile-clean.tsx
index 904f7f1..c3c1014 100644
--- a/scripts/compile-clean.tsx
+++ b/scripts/compile-clean.tsx
@@ -58,6 +58,15 @@ async function cleanContent(
   try {
     const cleaned: CleanedDirectory[] = [];
 
+    // Clean compiled versioned snapshots
+    if (cleanDirectory(path.join(process.cwd(), 'versioned'))) {
+      const cleanedDir: CleanedDirectory = { path: 'versioned', repository: '(versioned snapshots)' };
+      cleaned.push(cleanedDir);
+      if (onProgress) {
+        onProgress(cleanedDir);
+      }
+    }
+
     // Process each source repository
     for (const source of config.sources) {
       // Process each mapping and clean target directories
diff --git a/scripts/compile-content.tsx b/scripts/compile-content.tsx
index a69e5f3..11be011 100644
--- a/scripts/compile-content.tsx
+++ b/scripts/compile-content.tsx
@@ -15,6 +15,16 @@ interface ContentSource {
     readonly source: string;
     readonly target: string;
   }>;
+  /**
+   * Additional frozen documentation versions to compile alongside the main
+   * branch. Each entry clones the repository at the given ref (tag or branch)
+   * and copies the same mappings into versioned/<label>/<target>, which the
+   * /docs/v/<label>/ routes render as an archived snapshot.
+   */
+  readonly versions?: ReadonlyArray<{
+    readonly label: string;
+    readonly ref: string;
+  }>;
 }
 
 interface ContentConfig {
@@ -168,6 +178,7 @@ async function cloneContent(
   message?: string;
 }> {
   const TEMP_DIR = path.join(process.cwd(), '_tmp');
+  const VERSIONED_DIR = path.join(process.cwd(), 'versioned');
   const tracker = new FileTracker(onProgress);
 
   try {
@@ -175,6 +186,9 @@ async function cloneContent(
     cleanDirectory(TEMP_DIR);
     ensureDirectory(TEMP_DIR);
 
+    // Clean versioned snapshots from a previous compile
+    cleanDirectory(VERSIONED_DIR);
+
     // Process each source repository
     for (const source of config.sources) {
       const repoName = source.repository.split('/').pop() || 'repo';
@@ -235,6 +249,45 @@ async function cloneContent(
           );
         }
       }
+
+      // Compile frozen documentation versions (tags/branches) into versioned/<label>/
+      for (const version of source.versions ?? []) {
+        const versionCloneDir = path.join(TEMP_DIR, `${repoName}-${version.label}`);
+
+        const versionCloneResult = spawnSync(
+          'git',
+          ['clone', '--depth', '1', '--branch', version.ref, source.repository, versionCloneDir],
+          { stdio: 'pipe' }
+        );
+
+        if (versionCloneResult.error || versionCloneResult.status !== 0) {
+          const stderr = versionCloneResult.stderr?.toString().trim();
+          throw new Error(
+            `git clone failed for ${source.repository} at ref ${version.ref}: ${versionCloneResult.error?.message || stderr || `exit code ${versionCloneResult.status}`}`
+          );
+        }
+
+        for (const mapping of source.mappings) {
+          const sourceDir = path.join(versionCloneDir, mapping.source);
+          const targetDir = path.join(VERSIONED_DIR, version.label, mapping.target);
+
+          // Unlike the main branch, a missing folder in an old snapshot is
+          // expected (sections are added over time), so skip instead of throwing.
+          if (!fs.existsSync(sourceDir)) {
+            continue;
+          }
+
+          ensureDirectory(targetDir);
+          copyFilesRecursive(
+            sourceDir,
+            targetDir,
+            config.include,
+            config.exclude,
+            tracker,
+            `${source.repository}@${version.ref}`
+          );
+        }
+      }
     }
 
     // Clean up temp directory
diff --git a/scripts/generate-sitemap.mjs b/scripts/generate-sitemap.mjs
index b4e4f3e..6128910 100644
--- a/scripts/generate-sitemap.mjs
+++ b/scripts/generate-sitemap.mjs
@@ -78,6 +78,9 @@ function collectPages(directory, relativePath = '') {
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     if (relativePath === '' && excludedTopLevelDirectories.has(entry.name)) continue;
+    // Archived documentation versions (/docs/v/...) are noindex and must not
+    // appear in the sitemap; only the current docs are advertised to crawlers.
+    if (relativePath === 'docs' && entry.name === 'v') continue;
 
     pages.push(
       ...collectPages(

From 0e6c490381236ffe134f1907cf51f6afff6a4fa6 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Mon, 3 Aug 2026 15:25:19 -0400
Subject: [PATCH 2/4] Rework docs navigation: version-sticky sidebar,
 breadcrumbs, unified switcher

Fixes version-context leaks: on archived pages the back link now goes to the
version home (not current docs) and all sidebar links stay inside the
version. Current and versioned article pages share one sidebar shell showing
the section's pages, every other section in the same version context, an
always-present version switcher (current + each archived version, targeting
the same page where it exists), and release-notes/versions footer links.
Adds Docs / version / section / page breadcrumbs on article, version-home,
and versions pages, and moves Release Notes and Documentation Versions into
a secondary row on the docs landing.
---
 app/components/DocsBreadcrumb.tsx             |  30 ++++
 app/components/DocsSidebar.tsx                | 145 ++++++++++++++++++
 app/components/VersionSwitcher.tsx            |  69 +++++----
 app/docs/[section]/[[...slug]]/page.tsx       | 142 ++++++-----------
 app/docs/page.tsx                             |  23 +++
 .../[version]/[section]/[[...slug]]/page.tsx  | 104 +++++++------
 app/docs/v/[version]/page.tsx                 |  54 +++++--
 app/docs/versions/page.tsx                    |   4 +
 app/services/versionService.ts                |  82 ++++++++++
 app/types/Article.ts                          |   6 +
 articles/content.yml                          |   7 +-
 next.config.ts                                |   5 -
 12 files changed, 466 insertions(+), 205 deletions(-)
 create mode 100644 app/components/DocsBreadcrumb.tsx
 create mode 100644 app/components/DocsSidebar.tsx

diff --git a/app/components/DocsBreadcrumb.tsx b/app/components/DocsBreadcrumb.tsx
new file mode 100644
index 0000000..a5b57b8
--- /dev/null
+++ b/app/components/DocsBreadcrumb.tsx
@@ -0,0 +1,30 @@
+import Link from "next/link";
+
+export interface Crumb {
+    title: string;
+    href?: string;
+}
+
+/**
+ * Breadcrumb trail for documentation pages:
+ *   Docs / [version] / Section / Page
+ * The last crumb (no href) is the page being viewed.
+ */
+export default function DocsBreadcrumb({ crumbs }: { crumbs: Crumb[] }) {
+    return (
+        <nav className="mb-6 text-sm text-gray-400">
+            {crumbs.map((crumb, index) => (
+                <span key={`${crumb.title}-${index}`}>
+                    {index > 0 && <span className="mx-2">/</span>}
+                    {crumb.href ? (
+                        <Link href={crumb.href} className="hover:text-blue-400 transition-colors">
+                            {crumb.title}
+                        </Link>
+                    ) : (
+                        <span className="text-white">{crumb.title}</span>
+                    )}
+                </span>
+            ))}
+        </nav>
+    );
+}
diff --git a/app/components/DocsSidebar.tsx b/app/components/DocsSidebar.tsx
new file mode 100644
index 0000000..5724306
--- /dev/null
+++ b/app/components/DocsSidebar.tsx
@@ -0,0 +1,145 @@
+import Link from "next/link";
+import VersionSwitcher from "./VersionSwitcher";
+import { VersionSwitcherEntry } from "../services/versionService";
+
+export interface SidebarNavItem {
+    title: string;
+    href: string;
+    active?: boolean;
+}
+
+export interface DocsSidebarProps {
+    /** null when viewing current docs; the version label on archived pages. */
+    version: string | null;
+    /** Where the top back link goes: /docs for current, /docs/v/<v> for a version. */
+    backHref: string;
+    backLabel: string;
+    sectionTitle: string;
+    /** Pages of the section being viewed. */
+    nav: SidebarNavItem[];
+    /** All sections in the SAME version context (never leaves the version). */
+    sections: SidebarNavItem[];
+    switcherEntries: VersionSwitcherEntry[];
+}
+
+function navLinkClass(active?: boolean): string {
+    return `block w-full text-left px-4 py-2.5 rounded-lg text-sm transition-all duration-200 ${active
+        ? "bg-blue-500/20 text-blue-300 border border-blue-500/30"
+        : "text-gray-300 hover:text-white hover:bg-neutral-700/50"
+        }`;
+}
+
+/**
+ * Shared sidebar for current and versioned documentation pages. Every link in
+ * it stays inside the version being viewed, so readers never fall out of an
+ * archived version by navigating.
+ */
+export function DocsSidebarContent({
+    version,
+    backHref,
+    backLabel,
+    sectionTitle,
+    nav,
+    sections,
+    switcherEntries,
+}: DocsSidebarProps) {
+    return (
+        <>
+            {/* Header: back link + section title + version state */}
+            <div className="p-6 border-b border-neutral-700/50">
+                <Link
+                    href={backHref}
+                    className="text-blue-400 hover:text-blue-300 text-sm mb-3 flex items-center transition-colors"
+                >
+                    <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+                    </svg>
+                    {backLabel}
+                </Link>
+                <p className="text-2xl font-bold text-white">{sectionTitle}</p>
+                {version && (
+                    <p className="mt-1 inline-flex items-center rounded-full bg-amber-500/15 border border-amber-500/40 px-2.5 py-0.5 text-xs font-semibold text-amber-300">
+                        {version} · archived
+                    </p>
+                )}
+                <div className="mt-4">
+                    <VersionSwitcher entries={switcherEntries} />
+                </div>
+            </div>
+
+            {/* Section pages */}
+            <div className="flex-1 p-4 overflow-y-auto">
+                <nav className="space-y-1">
+                    {nav.map((item) => (
+                        <Link key={item.href} href={item.href} className={navLinkClass(item.active)}>
+                            {item.title}
+                        </Link>
+                    ))}
+                </nav>
+
+                {/* Other sections, same version context */}
+                {sections.length > 0 && (
+                    <div className="mt-6 border-t border-neutral-700/50 pt-4">
+                        <p className="px-4 pb-2 text-xs font-semibold uppercase tracking-wider text-gray-500">
+                            All sections
+                        </p>
+                        <nav className="space-y-1">
+                            {sections.map((item) => (
+                                <Link
+                                    key={item.href}
+                                    href={item.href}
+                                    className={`block w-full px-4 py-2 rounded-lg text-sm transition-colors ${item.active
+                                        ? "text-white font-medium"
+                                        : "text-gray-400 hover:text-white hover:bg-neutral-700/40"
+                                        }`}
+                                >
+                                    {item.title}
+                                </Link>
+                            ))}
+                        </nav>
+                    </div>
+                )}
+            </div>
+
+            {/* Footer meta links */}
+            <div className="p-4 border-t border-neutral-700/50 space-y-1">
+                <Link
+                    href="/docs/release-notes"
+                    className="block px-4 py-1.5 text-xs text-gray-400 hover:text-white transition-colors"
+                >
+                    Release notes
+                </Link>
+                <Link
+                    href="/docs/versions"
+                    className="block px-4 py-1.5 text-xs text-gray-400 hover:text-white transition-colors"
+                >
+                    All documentation versions
+                </Link>
+            </div>
+        </>
+    );
+}
+
+/** Desktop sidebar wrapper. */
+export default function DocsSidebar(props: DocsSidebarProps) {
+    return (
+        <div className="hidden w-80 bg-neutral-800/50 backdrop-blur-sm border-r border-neutral-700/50 md:flex flex-col">
+            <DocsSidebarContent {...props} />
+        </div>
+    );
+}
+
+/** Mobile disclosure variant of the same navigation. */
+export function DocsSidebarMobile(props: DocsSidebarProps) {
+    return (
+        <details className="mb-6 rounded-lg border border-neutral-700/50 bg-neutral-800/50 md:hidden">
+            <summary className="cursor-pointer px-4 py-3 text-sm font-semibold text-gray-200">
+                {props.sectionTitle} navigation
+                {props.version ? ` (${props.version})` : ""}
+            </summary>
+            <div className="border-t border-neutral-700/50 flex flex-col">
+                <DocsSidebarContent {...props} />
+            </div>
+        </details>
+    );
+}
diff --git a/app/components/VersionSwitcher.tsx b/app/components/VersionSwitcher.tsx
index cd2c1dc..5632f80 100644
--- a/app/components/VersionSwitcher.tsx
+++ b/app/components/VersionSwitcher.tsx
@@ -1,45 +1,48 @@
 import Link from "next/link";
-
-export interface VersionTarget {
-    label: string;
-    href: string;
-}
+import { VersionSwitcherEntry } from "../services/versionService";
 
 /**
- * Static version dropdown shown on documentation pages. Server-rendered
+ * Static version dropdown shown on every documentation page. Server-rendered
  * (a <details> disclosure, no client JS) so it works in the static export.
+ * The active entry is marked; every other entry links to the best equivalent
+ * of the page being viewed in that version.
  */
-export default function VersionSwitcher({
-    current,
-    targets,
-}: {
-    /** Label of the version being viewed (e.g. "current (v0.114-0)"). */
-    current: string;
-    /** Other versions of this page the reader can switch to. */
-    targets: VersionTarget[];
-}) {
+export default function VersionSwitcher({ entries }: { entries: VersionSwitcherEntry[] }) {
+    const active = entries.find((entry) => entry.active);
+
     return (
-        <details className="relative inline-block text-left group">
-            <summary className="cursor-pointer list-none inline-flex items-center gap-2 rounded-lg border border-neutral-700/60 bg-neutral-800/60 px-3 py-1.5 text-xs font-medium text-gray-300 hover:text-white hover:border-neutral-500 transition-colors">
-                <svg className="h-3.5 w-3.5 text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
-                        d="M7 7h10M7 12h10M7 17h6" />
-                </svg>
-                Version: {current}
-                <svg className="h-3 w-3 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <details className="relative block text-left">
+            <summary className="cursor-pointer list-none flex w-full items-center justify-between gap-2 rounded-lg border border-neutral-700/60 bg-neutral-900/60 px-3 py-2 text-xs font-medium text-gray-300 hover:text-white hover:border-neutral-500 transition-colors">
+                <span className="inline-flex items-center gap-2 truncate">
+                    <svg className="h-3.5 w-3.5 shrink-0 text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
+                            d="M7 7h10M7 12h10M7 17h6" />
+                    </svg>
+                    {active?.label ?? "Select version"}
+                </span>
+                <svg className="h-3 w-3 shrink-0 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
                 </svg>
             </summary>
-            <div className="absolute z-20 mt-2 w-56 rounded-lg border border-neutral-700/60 bg-neutral-800 p-1 shadow-xl">
-                {targets.map((target) => (
-                    <Link
-                        key={target.href}
-                        href={target.href}
-                        className="block rounded-md px-3 py-2 text-xs text-gray-300 hover:bg-neutral-700/60 hover:text-white transition-colors"
-                    >
-                        {target.label}
-                    </Link>
-                ))}
+            <div className="absolute z-20 mt-2 w-full min-w-56 rounded-lg border border-neutral-700/60 bg-neutral-800 p-1 shadow-xl">
+                {entries.map((entry) =>
+                    entry.active ? (
+                        <span
+                            key={entry.label}
+                            className="block rounded-md px-3 py-2 text-xs font-semibold text-white bg-neutral-700/40"
+                        >
+                            {entry.label} ✓
+                        </span>
+                    ) : (
+                        <Link
+                            key={entry.label}
+                            href={entry.href}
+                            className="block rounded-md px-3 py-2 text-xs text-gray-300 hover:bg-neutral-700/60 hover:text-white transition-colors"
+                        >
+                            {entry.label}
+                        </Link>
+                    )
+                )}
                 <Link
                     href="/docs/versions"
                     className="block rounded-md px-3 py-2 text-xs text-blue-400 hover:bg-neutral-700/60 hover:text-blue-300 transition-colors border-t border-neutral-700/60 mt-1 pt-2"
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 13d6314..61948bb 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -1,13 +1,17 @@
 import Link from "next/link";
 import { notFound, redirect } from 'next/navigation';
-import { capitalCase } from 'change-case';
-import { getAllArticlePaths, getArticleByPath } from "../../../services/articleService";
+import { getAllArticlePaths, getAllSections, getArticleByPath } from "../../../services/articleService";
 import { getMetadata } from "../../../services/metadataService";
 import ComingSoon from "../../../components/ComingSoon";
 import CommandSnippet from "../../../components/CommandSnippet";
 import Markdown from "../../../components/Markdown";
-import VersionSwitcher from "../../../components/VersionSwitcher";
-import { getDocVersions, versionedArticleExists } from "../../../services/versionService";
+import DocsSidebar, { DocsSidebarMobile } from "../../../components/DocsSidebar";
+import DocsBreadcrumb from "../../../components/DocsBreadcrumb";
+import {
+    formatSectionTitle,
+    getVersionSwitcherEntries,
+    orderSections,
+} from "../../../services/versionService";
 
 const dockerQuickRunCommand = `docker run -dt --name documentdb \\
   -p 10260:10260 \\
@@ -91,35 +95,47 @@ export default async function ArticlePage({ params }: PageProps) {
     // with no heading element at all. Guarded in case a future coming-soon page
     // does start with one.
     const showComingSoonHeading = isComingSoon && !/^#\s/m.test(content);
-    const sectionTitle = capitalCase(section)
-        .replace(/documentdb/i, 'DocumentDB')
-        .replace(/api/i, 'API');
+    const sectionTitle = formatSectionTitle(section);
 
-    // Rendered once, shown in the desktop sidebar and the mobile disclosure
-    const navigationLinks = navigation.map((item) => {
-        // Better matching logic for active state
-        // For index files, match both /section and /section/index
-        // For other files, match the specific file name
+    // Section pages with active-state matching: index files match both
+    // /section and /section/index; other files match their file name.
+    const navItems = navigation.map((item) => {
         const itemPath = item.link.replace('/docs/', '');
         const currentPath = file === 'index' ? section : `${section}/${file}`;
         const isActive = itemPath === currentPath ||
             (file === 'index' && itemPath === `${section}/index`) ||
             (item.link.includes(file) && file !== 'index');
 
-        return (
-            <Link
-                key={item.link}
-                href={item.link}
-                className={`block w-full text-left px-4 py-3 rounded-lg text-sm transition-all duration-200 ${isActive
-                    ? "bg-blue-500/20 text-blue-300 border border-blue-500/30"
-                    : "text-gray-300 hover:text-white hover:bg-neutral-700/50"
-                    }`}
-            >
-                {item.title}
-            </Link>
-        );
+        return { title: item.title, href: item.link, active: isActive };
     });
 
+    const sectionItems = [
+        ...orderSections(getAllSections()).map((s) => ({
+            title: formatSectionTitle(s),
+            href: `/docs/${s}`,
+            active: s === section,
+        })),
+        { title: 'API Reference', href: '/docs/reference', active: false },
+    ];
+
+    const sidebarProps = {
+        version: null,
+        backHref: '/docs',
+        backLabel: 'Back to Documentation',
+        sectionTitle,
+        nav: navItems,
+        sections: sectionItems,
+        switcherEntries: getVersionSwitcherEntries('current', section, file),
+    };
+
+    const breadcrumbs = file === 'index'
+        ? [{ title: 'Docs', href: '/docs' }, { title: sectionTitle }]
+        : [
+            { title: 'Docs', href: '/docs' },
+            { title: sectionTitle, href: `/docs/${section}` },
+            { title: pageTitle },
+        ];
+
     return (
         <div className="min-h-screen bg-neutral-900 relative overflow-hidden">
             {/* Background elements */}
@@ -134,62 +150,16 @@ export default async function ArticlePage({ params }: PageProps) {
 
             <div className="relative flex min-h-screen">
                 {/* Left Sidebar (desktop only; mobile gets the disclosure below) */}
-                <div className="hidden w-80 bg-neutral-800/50 backdrop-blur-sm border-r border-neutral-700/50 md:flex flex-col">
-                    {/* Header */}
-                    <div className="p-6 border-b border-neutral-700/50">
-                        <Link
-                            href="/docs"
-                            className="text-blue-400 hover:text-blue-300 text-sm mb-4 flex items-center transition-colors"
-                        >
-                            <svg
-                                className="w-4 h-4 mr-2"
-                                fill="none"
-                                stroke="currentColor"
-                                viewBox="0 0 24 24"
-                            >
-                                <path
-                                    strokeLinecap="round"
-                                    strokeLinejoin="round"
-                                    strokeWidth={2}
-                                    d="M15 19l-7-7 7-7"
-                                />
-                            </svg>
-                            Back to Documentation
-                        </Link>
-                        {/* Not a heading: the article's h1 comes from the markdown content */}
-                        <p className="text-2xl font-bold text-white">
-                            {sectionTitle}
-                        </p>
-                    </div>
-
-                    {/* Menu Items */}
-                    <div className="flex-1 p-4 overflow-y-auto">
-                        <nav className="space-y-1">
-                            {navigationLinks}
-                        </nav>
-                    </div>
-                </div>
+                <DocsSidebar {...sidebarProps} />
 
                 {/* Main Content */}
                 <div className="flex-1 p-4 sm:p-8 overflow-y-auto">
                     <div className="max-w-4xl">
                         {/* Mobile section navigation */}
-                        <details className="mb-6 rounded-lg border border-neutral-700/50 bg-neutral-800/50 md:hidden">
-                            <summary className="cursor-pointer px-4 py-3 text-sm font-semibold text-gray-200">
-                                {sectionTitle} navigation
-                            </summary>
-                            <div className="border-t border-neutral-700/50 p-3">
-                                <Link
-                                    href="/docs"
-                                    className="block px-4 py-2 text-sm text-blue-400 hover:text-blue-300 transition-colors"
-                                >
-                                    ← Back to Documentation
-                                </Link>
-                                <nav className="space-y-1">
-                                    {navigationLinks}
-                                </nav>
-                            </div>
-                        </details>
+                        <DocsSidebarMobile {...sidebarProps} />
+
+                        {/* Breadcrumb */}
+                        <DocsBreadcrumb crumbs={breadcrumbs} />
 
                         {/* Coming Soon Component for coming-soon layout */}
                         {showComingSoonHeading && (
@@ -323,28 +293,6 @@ export default async function ArticlePage({ params }: PageProps) {
                             </section>
                         )}
 
-                        {/* Version switcher: shown when archived snapshots of this page exist */}
-                        {(() => {
-                            const versionTargets = getDocVersions()
-                                .filter((version) => versionedArticleExists(version, section, file))
-                                .map((version) => ({
-                                    label: `${version} (archived)`,
-                                    href:
-                                        file === 'index'
-                                            ? `/docs/v/${version}/${section}`
-                                            : `/docs/v/${version}/${section}/${file}`,
-                                }));
-
-                            return versionTargets.length > 0 ? (
-                                <div className="mb-6">
-                                    <VersionSwitcher
-                                        current="current (latest release)"
-                                        targets={versionTargets}
-                                    />
-                                </div>
-                            ) : null;
-                        })()}
-
                         {/* Markdown Content */}
                         <Markdown
                             content={content}
diff --git a/app/docs/page.tsx b/app/docs/page.tsx
index 733f554..368fd85 100644
--- a/app/docs/page.tsx
+++ b/app/docs/page.tsx
@@ -105,6 +105,29 @@ export default function Docs() {
             );
           })}
         </div>
+
+        {/* Secondary meta links: releases and versions */}
+        {articleContent.landing.secondaryLinks && (
+          <div className="mt-10 flex flex-col items-center gap-3 sm:flex-row sm:justify-center">
+            {articleContent.landing.secondaryLinks.map((item) => (
+              <Link
+                key={item.link}
+                href={item.link}
+                className="group flex w-full max-w-md items-center justify-between rounded-lg border border-neutral-700/50 bg-neutral-800/60 px-5 py-3 transition-colors hover:border-blue-500/50 sm:w-auto sm:min-w-72"
+              >
+                <span>
+                  <span className="block text-sm font-medium text-white group-hover:text-blue-300 transition-colors">
+                    {item.title}
+                  </span>
+                  {item.description && (
+                    <span className="block text-xs text-gray-500">{item.description}</span>
+                  )}
+                </span>
+                <span className="ml-4 text-gray-500 group-hover:text-blue-400 transition-colors">→</span>
+              </Link>
+            ))}
+          </div>
+        )}
       </div>
     </div>
   );
diff --git a/app/docs/v/[version]/[section]/[[...slug]]/page.tsx b/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
index d2732b7..8ad86d4 100644
--- a/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
+++ b/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
@@ -1,13 +1,16 @@
 import Link from "next/link";
 import { notFound } from "next/navigation";
-import { capitalCase } from "change-case";
 import {
+    formatSectionTitle,
     getAllVersionedArticlePaths,
     getVersionedArticleByPath,
+    getVersionedSections,
+    getVersionSwitcherEntries,
+    orderSections,
 } from "../../../../../services/versionService";
-import { getArticleByPath } from "../../../../../services/articleService";
 import Markdown from "../../../../../components/Markdown";
-import VersionSwitcher from "../../../../../components/VersionSwitcher";
+import DocsSidebar, { DocsSidebarMobile } from "../../../../../components/DocsSidebar";
+import DocsBreadcrumb from "../../../../../components/DocsBreadcrumb";
 
 export async function generateStaticParams() {
     return getAllVersionedArticlePaths().map((path) => ({
@@ -49,55 +52,63 @@ export default async function VersionedArticlePage({ params }: PageProps) {
 
     const { content, frontmatter, navigation, file } = articleData;
     const pageTitle = frontmatter.title || section;
-    const sectionTitle = capitalCase(section)
-        .replace(/documentdb/i, "DocumentDB")
-        .replace(/api/i, "API");
-
-    // Link the banner to the same page in the current docs when it still
-    // exists there, otherwise to the section root.
-    const currentEquivalent = getArticleByPath(section, slug)
-        ? slug.length > 0
-            ? `/docs/${section}/${slug.join("/")}`
-            : `/docs/${section}`
-        : "/docs";
-
-    const navigationLinks = navigation.map((item) => (
-        <Link
-            key={item.link}
-            href={item.link}
-            className="block w-full text-left px-4 py-3 rounded-lg text-sm text-gray-300 hover:text-white hover:bg-neutral-700/50 transition-all duration-200"
-        >
-            {item.title}
-        </Link>
-    ));
+    const sectionTitle = formatSectionTitle(section);
+    const switcherEntries = getVersionSwitcherEntries(version, section, file);
+    const currentEquivalent =
+        switcherEntries.find((entry) => entry.label.startsWith("Current"))?.href ?? "/docs";
+
+    // Every navigation element on this page stays inside the version: the back
+    // link goes to the version home, section links stay under /docs/v/<v>/,
+    // and only the banner/switcher deliberately exit to current.
+    const navItems = navigation.map((item) => {
+        const isActive =
+            file === "index"
+                ? item.link === `/docs/v/${version}/${section}`
+                : item.link.endsWith(`/${file}`);
+        return { title: item.title, href: item.link, active: isActive };
+    });
+
+    const sectionItems = orderSections(getVersionedSections(version)).map((s) => ({
+        title: formatSectionTitle(s),
+        href: `/docs/v/${version}/${s}`,
+        active: s === section,
+    }));
+
+    const sidebarProps = {
+        version,
+        backHref: `/docs/v/${version}`,
+        backLabel: `${version} documentation home`,
+        sectionTitle,
+        nav: navItems,
+        sections: sectionItems,
+        switcherEntries,
+    };
+
+    const breadcrumbs = [
+        { title: "Docs", href: "/docs" },
+        { title: version, href: `/docs/v/${version}` },
+        ...(file === "index"
+            ? [{ title: sectionTitle }]
+            : [
+                { title: sectionTitle, href: `/docs/v/${version}/${section}` },
+                { title: pageTitle },
+            ]),
+    ];
 
     return (
         <div className="min-h-screen bg-neutral-900 relative overflow-hidden">
             <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
 
             <div className="relative flex min-h-screen">
-                {/* Left Sidebar */}
-                <div className="hidden w-80 bg-neutral-800/50 backdrop-blur-sm border-r border-neutral-700/50 md:flex flex-col">
-                    <div className="p-6 border-b border-neutral-700/50">
-                        <Link
-                            href="/docs"
-                            className="text-blue-400 hover:text-blue-300 text-sm mb-4 flex items-center transition-colors"
-                        >
-                            ← Back to Documentation
-                        </Link>
-                        <p className="text-2xl font-bold text-white">{sectionTitle}</p>
-                        <p className="mt-1 text-xs font-semibold uppercase tracking-wider text-amber-400">
-                            {version} snapshot
-                        </p>
-                    </div>
-                    <div className="flex-1 p-4 overflow-y-auto">
-                        <nav className="space-y-1">{navigationLinks}</nav>
-                    </div>
-                </div>
+                <DocsSidebar {...sidebarProps} />
 
                 {/* Main Content */}
                 <div className="flex-1 p-4 sm:p-8 overflow-y-auto">
                     <div className="max-w-4xl">
+                        <DocsSidebarMobile {...sidebarProps} />
+
+                        <DocsBreadcrumb crumbs={breadcrumbs} />
+
                         {/* Old-version banner */}
                         <div className="mb-6 flex flex-col gap-3 rounded-xl border border-amber-500/40 bg-amber-500/10 p-4 sm:flex-row sm:items-center sm:justify-between">
                             <p className="text-sm text-amber-200">
@@ -113,15 +124,6 @@ export default async function VersionedArticlePage({ params }: PageProps) {
                             </Link>
                         </div>
 
-                        <div className="mb-6">
-                            <VersionSwitcher
-                                current={version}
-                                targets={[
-                                    { label: "current (latest release)", href: currentEquivalent },
-                                ]}
-                            />
-                        </div>
-
                         <Markdown content={content} />
                     </div>
                 </div>
diff --git a/app/docs/v/[version]/page.tsx b/app/docs/v/[version]/page.tsx
index bcc943b..f35e903 100644
--- a/app/docs/v/[version]/page.tsx
+++ b/app/docs/v/[version]/page.tsx
@@ -1,7 +1,14 @@
 import Link from "next/link";
 import { notFound } from "next/navigation";
-import { capitalCase } from "change-case";
-import { getDocVersions, getVersionedSections } from "../../../services/versionService";
+import {
+    formatSectionTitle,
+    getDocVersions,
+    getVersionedSections,
+    getVersionSwitcherEntries,
+    orderSections,
+} from "../../../services/versionService";
+import DocsBreadcrumb from "../../../components/DocsBreadcrumb";
+import VersionSwitcher from "../../../components/VersionSwitcher";
 
 export async function generateStaticParams() {
     return getDocVersions().map((version) => ({ version }));
@@ -22,7 +29,7 @@ export async function generateMetadata({ params }: PageProps) {
 
 export default async function VersionLandingPage({ params }: PageProps) {
     const { version } = await params;
-    const sections = getVersionedSections(version);
+    const sections = orderSections(getVersionedSections(version));
 
     if (sections.length === 0) {
         return notFound();
@@ -33,22 +40,35 @@ export default async function VersionLandingPage({ params }: PageProps) {
             <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
 
             <div className="relative mx-auto max-w-4xl px-4 py-16 sm:px-8">
+                <DocsBreadcrumb
+                    crumbs={[{ title: "Docs", href: "/docs" }, { title: version }]}
+                />
+
                 <div className="mb-8 rounded-xl border border-amber-500/40 bg-amber-500/10 p-4">
                     <p className="text-sm text-amber-200">
                         This is the frozen documentation snapshot for{" "}
-                        <span className="font-semibold">{version}</span>.{" "}
+                        <span className="font-semibold">{version}</span>. It is not updated
+                        and may not reflect the latest release.{" "}
                         <Link href="/docs" className="font-semibold text-amber-100 underline hover:text-white">
                             Switch to the current documentation →
                         </Link>
                     </p>
                 </div>
 
-                <h1 className="text-4xl font-bold text-white">
-                    DocumentDB {version} Documentation
-                </h1>
-                <p className="mt-3 text-gray-400">
-                    Documentation sections as they were at the {version} release.
-                </p>
+                <div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+                    <div>
+                        <h1 className="text-4xl font-bold text-white">
+                            DocumentDB {version} Documentation
+                        </h1>
+                        <p className="mt-3 text-gray-400">
+                            Documentation sections exactly as they were at the {version}{" "}
+                            release.
+                        </p>
+                    </div>
+                    <div className="w-full sm:w-64">
+                        <VersionSwitcher entries={getVersionSwitcherEntries(version, null, null)} />
+                    </div>
+                </div>
 
                 <div className="mt-10 grid gap-4 sm:grid-cols-2">
                     {sections.map((section) => (
@@ -57,20 +77,20 @@ export default async function VersionLandingPage({ params }: PageProps) {
                             href={`/docs/v/${version}/${section}`}
                             className="rounded-xl border border-neutral-700/60 bg-neutral-800/50 p-5 transition-colors hover:border-blue-500/50 hover:bg-neutral-800"
                         >
-                            <p className="font-semibold text-white">
-                                {capitalCase(section)
-                                    .replace(/documentdb/i, "DocumentDB")
-                                    .replace(/api/i, "API")}
-                            </p>
+                            <p className="font-semibold text-white">{formatSectionTitle(section)}</p>
                             <p className="mt-1 text-sm text-gray-400">
-                                {section} docs at {version}
+                                Browse this section as of {version}
                             </p>
                         </Link>
                     ))}
                 </div>
 
                 <p className="mt-10 text-sm text-gray-500">
-                    Looking for a different version? See{" "}
+                    The API Reference is maintained on the current documentation only —{" "}
+                    <Link href="/docs/reference" className="text-blue-400 hover:text-blue-300">
+                        open the current API Reference
+                    </Link>
+                    . Looking for a different version? See{" "}
                     <Link href="/docs/versions" className="text-blue-400 hover:text-blue-300">
                         all documentation versions
                     </Link>
diff --git a/app/docs/versions/page.tsx b/app/docs/versions/page.tsx
index 1c19774..d8e5f02 100644
--- a/app/docs/versions/page.tsx
+++ b/app/docs/versions/page.tsx
@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { getMetadata } from "../../services/metadataService";
 import { getDocVersions } from "../../services/versionService";
+import DocsBreadcrumb from "../../components/DocsBreadcrumb";
 
 export async function generateMetadata() {
     return getMetadata({
@@ -19,6 +20,9 @@ export default function VersionsPage() {
             <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
 
             <div className="relative mx-auto max-w-4xl px-4 py-16 sm:px-8">
+                <DocsBreadcrumb
+                    crumbs={[{ title: "Docs", href: "/docs" }, { title: "Versions" }]}
+                />
                 <h1 className="text-4xl font-bold text-white">Documentation Versions</h1>
                 <p className="mt-3 max-w-2xl text-gray-400">
                     The documentation site always describes the latest DocumentDB release,
diff --git a/app/services/versionService.ts b/app/services/versionService.ts
index 66b70c7..1f86179 100644
--- a/app/services/versionService.ts
+++ b/app/services/versionService.ts
@@ -100,6 +100,88 @@ export function getVersionedNavigation(version: string, section: string): Link[]
   });
 }
 
+/** Human-readable section title (shared by current and versioned navigation). */
+export function formatSectionTitle(section: string): string {
+  const words = section
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+
+  return words.replace(/documentdb/i, 'DocumentDB').replace(/\bapi\b/i, 'API');
+}
+
+const SECTION_ORDER = [
+  'getting-started',
+  'documentdb-local',
+  'postgres-api',
+  'architecture',
+  'kubernetes-operator',
+  'release-notes',
+];
+
+/** Sort sections into their canonical display order (unknown sections last). */
+export function orderSections(sections: string[]): string[] {
+  return [...sections].sort((a, b) => {
+    const ia = SECTION_ORDER.indexOf(a);
+    const ib = SECTION_ORDER.indexOf(b);
+    return (ia === -1 ? SECTION_ORDER.length : ia) - (ib === -1 ? SECTION_ORDER.length : ib);
+  });
+}
+
+export interface VersionSwitcherEntry {
+  label: string;
+  href: string;
+  active: boolean;
+}
+
+/**
+ * Entries for the version switcher shown on every docs page.
+ *
+ * `viewing` is 'current' or a version label. For each version the target is the
+ * best equivalent of the page being viewed: the same page when it exists in
+ * that version, otherwise the section home, otherwise the version home. This
+ * keeps switching lossless where possible and predictable where not.
+ */
+export function getVersionSwitcherEntries(
+  viewing: string,
+  section: string | null,
+  file: string | null
+): VersionSwitcherEntry[] {
+  const currentArticlesDir = path.join(process.cwd(), 'articles');
+
+  const currentTarget = (() => {
+    if (!section) return '/docs';
+    if (!fs.existsSync(path.join(currentArticlesDir, section))) return '/docs';
+    if (!file || file === 'index') return `/docs/${section}`;
+    if (fs.existsSync(path.join(currentArticlesDir, section, `${file}.md`))) {
+      return `/docs/${section}/${file}`;
+    }
+    return `/docs/${section}`;
+  })();
+
+  const entries: VersionSwitcherEntry[] = [
+    { label: 'Current (latest release)', href: currentTarget, active: viewing === 'current' },
+  ];
+
+  for (const version of getDocVersions()) {
+    const target = (() => {
+      if (!section) return `/docs/v/${version}`;
+      if (!fs.existsSync(path.join(versionArticlesDir(version), section))) {
+        return `/docs/v/${version}`;
+      }
+      if (!file || file === 'index') return `/docs/v/${version}/${section}`;
+      if (versionedArticleExists(version, section, file)) {
+        return `/docs/v/${version}/${section}/${file}`;
+      }
+      return `/docs/v/${version}/${section}`;
+    })();
+
+    entries.push({ label: `${version} (archived)`, href: target, active: viewing === version });
+  }
+
+  return entries;
+}
+
 /** Load a versioned article: raw snapshot content plus parsed front matter. */
 export function getVersionedArticleByPath(
   version: string,
diff --git a/app/types/Article.ts b/app/types/Article.ts
index 8a0545a..925e418 100644
--- a/app/types/Article.ts
+++ b/app/types/Article.ts
@@ -6,5 +6,11 @@ export interface Article {
       title: string;
       link: string;
     }>;
+    /** Secondary meta links (release notes, versions) shown below the section grid. */
+    secondaryLinks?: Array<{
+      title: string;
+      description?: string;
+      link: string;
+    }>;
   };
 }
\ No newline at end of file
diff --git a/articles/content.yml b/articles/content.yml
index b1a133c..d54bf67 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -14,9 +14,12 @@ landing:
       link: /docs/documentdb-local
     - title: Architecture under the hood (Coming soon)
       link: /docs/architecture
+    - title: Samples & Demos
+      link: /samples
+  secondaryLinks:
     - title: Release Notes
+      description: What changed in each DocumentDB release
       link: /docs/release-notes
     - title: Documentation Versions
+      description: Current docs, archived snapshots, and older tags
       link: /docs/versions
-    - title: Samples & Demos
-      link: /samples
diff --git a/next.config.ts b/next.config.ts
index 5d341cf..0fc40b9 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -7,11 +7,6 @@ const normalizedBasePath = rawBasePath
 
 const nextConfig: NextConfig = {
   output: "export",
-  // Expose the base path to client components (Markdown link resolution);
-  // next/link handles it automatically but raw anchors in markdown do not.
-  env: {
-    NEXT_PUBLIC_BASE_PATH: normalizedBasePath ?? "",
-  },
   // Emit directory/index.html instead of page.html so GitHub Pages serves
   // both /docs and /docs/ (without this, the trailing-slash form is a 404).
   trailingSlash: true,

From 56cb8d69d6e37020c6cb6f152e866e3733d7fdd4 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Mon, 3 Aug 2026 15:37:28 -0400
Subject: [PATCH 3/4] UX review fixes: unify version namespace and improve
 discoverability

Moves archived snapshots from /docs/v/<version>/ to /docs/versions/<version>/
so the versions index and the versions themselves share one hackable
namespace (trimming URL segments walks up the hierarchy) and the v/v
stutter is gone. Names the current version in the switcher and on the
versions index (readers could not tell what 'current' was). Keeps the API
Reference visible from archived context, labeled as an exit to current
docs. Roots the reference breadcrumb at Docs for consistency, and fixes
the sitemap exclusion to skip only version subdirectories while keeping
the /docs/versions index listed.
---
 app/components/Breadcrumb.tsx                 |  4 +++
 app/components/DocsSidebar.tsx                |  2 +-
 .../[version]/[section]/[[...slug]]/page.tsx  | 25 +++++++++-------
 app/docs/{v => versions}/[version]/page.tsx   |  2 +-
 app/docs/versions/page.tsx                    |  4 +--
 app/services/versionService.ts                | 29 ++++++++++++-------
 scripts/compile-content.tsx                   |  2 +-
 scripts/generate-sitemap.mjs                  |  7 +++--
 8 files changed, 46 insertions(+), 29 deletions(-)
 rename app/docs/{v => versions}/[version]/[section]/[[...slug]]/page.tsx (85%)
 rename app/docs/{v => versions}/[version]/page.tsx (98%)

diff --git a/app/components/Breadcrumb.tsx b/app/components/Breadcrumb.tsx
index a3199b1..96b3bb8 100644
--- a/app/components/Breadcrumb.tsx
+++ b/app/components/Breadcrumb.tsx
@@ -9,6 +9,10 @@ export default function Breadcrumb({ type, category, name }: {
 }) {
     return (
         <nav className="mb-6 text-sm text-gray-400">
+            <Link href="/docs" className="hover:text-blue-400 transition-colors">
+                Docs
+            </Link>
+            <span className="mx-2">/</span>
             <Link href="/docs/reference" className="hover:text-blue-400 transition-colors">
                 Reference
             </Link>
diff --git a/app/components/DocsSidebar.tsx b/app/components/DocsSidebar.tsx
index 5724306..e3ec070 100644
--- a/app/components/DocsSidebar.tsx
+++ b/app/components/DocsSidebar.tsx
@@ -11,7 +11,7 @@ export interface SidebarNavItem {
 export interface DocsSidebarProps {
     /** null when viewing current docs; the version label on archived pages. */
     version: string | null;
-    /** Where the top back link goes: /docs for current, /docs/v/<v> for a version. */
+    /** Where the top back link goes: /docs for current, /docs/versions/<v> for a version. */
     backHref: string;
     backLabel: string;
     sectionTitle: string;
diff --git a/app/docs/v/[version]/[section]/[[...slug]]/page.tsx b/app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
similarity index 85%
rename from app/docs/v/[version]/[section]/[[...slug]]/page.tsx
rename to app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
index 8ad86d4..bdcdad3 100644
--- a/app/docs/v/[version]/[section]/[[...slug]]/page.tsx
+++ b/app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
@@ -58,25 +58,30 @@ export default async function VersionedArticlePage({ params }: PageProps) {
         switcherEntries.find((entry) => entry.label.startsWith("Current"))?.href ?? "/docs";
 
     // Every navigation element on this page stays inside the version: the back
-    // link goes to the version home, section links stay under /docs/v/<v>/,
+    // link goes to the version home, section links stay under /docs/versions/<v>/,
     // and only the banner/switcher deliberately exit to current.
     const navItems = navigation.map((item) => {
         const isActive =
             file === "index"
-                ? item.link === `/docs/v/${version}/${section}`
+                ? item.link === `/docs/versions/${version}/${section}`
                 : item.link.endsWith(`/${file}`);
         return { title: item.title, href: item.link, active: isActive };
     });
 
-    const sectionItems = orderSections(getVersionedSections(version)).map((s) => ({
-        title: formatSectionTitle(s),
-        href: `/docs/v/${version}/${s}`,
-        active: s === section,
-    }));
+    const sectionItems = [
+        ...orderSections(getVersionedSections(version)).map((s) => ({
+            title: formatSectionTitle(s),
+            href: `/docs/versions/${version}/${s}`,
+            active: s === section,
+        })),
+        // The API Reference only exists on current docs; keep it visible from
+        // archived context but labeled as an exit from the version.
+        { title: "API Reference (current docs ↗)", href: "/docs/reference", active: false },
+    ];
 
     const sidebarProps = {
         version,
-        backHref: `/docs/v/${version}`,
+        backHref: `/docs/versions/${version}`,
         backLabel: `${version} documentation home`,
         sectionTitle,
         nav: navItems,
@@ -86,11 +91,11 @@ export default async function VersionedArticlePage({ params }: PageProps) {
 
     const breadcrumbs = [
         { title: "Docs", href: "/docs" },
-        { title: version, href: `/docs/v/${version}` },
+        { title: version, href: `/docs/versions/${version}` },
         ...(file === "index"
             ? [{ title: sectionTitle }]
             : [
-                { title: sectionTitle, href: `/docs/v/${version}/${section}` },
+                { title: sectionTitle, href: `/docs/versions/${version}/${section}` },
                 { title: pageTitle },
             ]),
     ];
diff --git a/app/docs/v/[version]/page.tsx b/app/docs/versions/[version]/page.tsx
similarity index 98%
rename from app/docs/v/[version]/page.tsx
rename to app/docs/versions/[version]/page.tsx
index f35e903..2d3ba5c 100644
--- a/app/docs/v/[version]/page.tsx
+++ b/app/docs/versions/[version]/page.tsx
@@ -74,7 +74,7 @@ export default async function VersionLandingPage({ params }: PageProps) {
                     {sections.map((section) => (
                         <Link
                             key={section}
-                            href={`/docs/v/${version}/${section}`}
+                            href={`/docs/versions/${version}/${section}`}
                             className="rounded-xl border border-neutral-700/60 bg-neutral-800/50 p-5 transition-colors hover:border-blue-500/50 hover:bg-neutral-800"
                         >
                             <p className="font-semibold text-white">{formatSectionTitle(section)}</p>
diff --git a/app/docs/versions/page.tsx b/app/docs/versions/page.tsx
index d8e5f02..62c3788 100644
--- a/app/docs/versions/page.tsx
+++ b/app/docs/versions/page.tsx
@@ -40,7 +40,7 @@ export default function VersionsPage() {
                         <div className="flex items-center justify-between">
                             <div>
                                 <p className="font-semibold text-white">
-                                    Current{" "}
+                                    Current{hostedVersions[0] ? ` — ${hostedVersions[0]}` : ""}{" "}
                                     <span className="ml-2 rounded-full bg-blue-500/30 px-2 py-0.5 text-xs font-medium text-blue-200">
                                         latest release
                                     </span>
@@ -58,7 +58,7 @@ export default function VersionsPage() {
                     {hostedVersions.map((version) => (
                         <Link
                             key={version}
-                            href={`/docs/v/${version}`}
+                            href={`/docs/versions/${version}`}
                             className="block rounded-xl border border-neutral-700/60 bg-neutral-800/50 p-5 transition-colors hover:border-neutral-500"
                         >
                             <div className="flex items-center justify-between">
diff --git a/app/services/versionService.ts b/app/services/versionService.ts
index 1f86179..2b9b753 100644
--- a/app/services/versionService.ts
+++ b/app/services/versionService.ts
@@ -8,7 +8,7 @@ import { Link } from '../types/Link';
  * Serves frozen documentation snapshots compiled by scripts/compile-content.tsx
  * into versioned/<label>/. The main (rolling) documentation is served by
  * articleService.ts from articles/; this module only handles archived versions
- * rendered under /docs/v/<label>/.
+ * rendered under /docs/versions/<label>/.
  *
  * Versioned pages render the snapshot content as-is: the editorial overrides
  * that articleService applies to current pages deliberately do not apply here,
@@ -75,7 +75,7 @@ export function getAllVersionedArticlePaths(): { version: string; section: strin
   return paths;
 }
 
-/** Sidebar navigation for a versioned section, with links under /docs/v/<version>/. */
+/** Sidebar navigation for a versioned section, with links under /docs/versions/<version>/. */
 export function getVersionedNavigation(version: string, section: string): Link[] {
   const navPath = path.join(versionArticlesDir(version), section, 'navigation.yml');
 
@@ -92,8 +92,8 @@ export function getVersionedNavigation(version: string, section: string): Link[]
       const file = transformedLink.replace('.md', '');
       transformedLink =
         file === 'index'
-          ? `/docs/v/${version}/${section}`
-          : `/docs/v/${version}/${section}/${file}`;
+          ? `/docs/versions/${version}/${section}`
+          : `/docs/versions/${version}/${section}/${file}`;
     }
 
     return { ...link, link: transformedLink, children: undefined };
@@ -159,21 +159,28 @@ export function getVersionSwitcherEntries(
     return `/docs/${section}`;
   })();
 
+  // Current tracks the latest release, whose tag is the newest snapshot label —
+  // name it so readers can tell what "current" actually is.
+  const versions = getDocVersions();
   const entries: VersionSwitcherEntry[] = [
-    { label: 'Current (latest release)', href: currentTarget, active: viewing === 'current' },
+    {
+      label: versions[0] ? `Current (${versions[0]}, latest)` : 'Current (latest release)',
+      href: currentTarget,
+      active: viewing === 'current',
+    },
   ];
 
-  for (const version of getDocVersions()) {
+  for (const version of versions) {
     const target = (() => {
-      if (!section) return `/docs/v/${version}`;
+      if (!section) return `/docs/versions/${version}`;
       if (!fs.existsSync(path.join(versionArticlesDir(version), section))) {
-        return `/docs/v/${version}`;
+        return `/docs/versions/${version}`;
       }
-      if (!file || file === 'index') return `/docs/v/${version}/${section}`;
+      if (!file || file === 'index') return `/docs/versions/${version}/${section}`;
       if (versionedArticleExists(version, section, file)) {
-        return `/docs/v/${version}/${section}/${file}`;
+        return `/docs/versions/${version}/${section}/${file}`;
       }
-      return `/docs/v/${version}/${section}`;
+      return `/docs/versions/${version}/${section}`;
     })();
 
     entries.push({ label: `${version} (archived)`, href: target, active: viewing === version });
diff --git a/scripts/compile-content.tsx b/scripts/compile-content.tsx
index 11be011..ad14578 100644
--- a/scripts/compile-content.tsx
+++ b/scripts/compile-content.tsx
@@ -19,7 +19,7 @@ interface ContentSource {
    * Additional frozen documentation versions to compile alongside the main
    * branch. Each entry clones the repository at the given ref (tag or branch)
    * and copies the same mappings into versioned/<label>/<target>, which the
-   * /docs/v/<label>/ routes render as an archived snapshot.
+   * /docs/versions/<label>/ routes render as an archived snapshot.
    */
   readonly versions?: ReadonlyArray<{
     readonly label: string;
diff --git a/scripts/generate-sitemap.mjs b/scripts/generate-sitemap.mjs
index 6128910..cce0785 100644
--- a/scripts/generate-sitemap.mjs
+++ b/scripts/generate-sitemap.mjs
@@ -78,9 +78,10 @@ function collectPages(directory, relativePath = '') {
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     if (relativePath === '' && excludedTopLevelDirectories.has(entry.name)) continue;
-    // Archived documentation versions (/docs/v/...) are noindex and must not
-    // appear in the sitemap; only the current docs are advertised to crawlers.
-    if (relativePath === 'docs' && entry.name === 'v') continue;
+    // Archived documentation versions (/docs/versions/<version>/...) are
+    // noindex and must not appear in the sitemap; the /docs/versions index
+    // page itself stays listed, so only its subdirectories are skipped.
+    if (relativePath === 'docs/versions') continue;
 
     pages.push(
       ...collectPages(

From b955efa1e0b324d29778d808b6713cc7458c5a00 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Mon, 3 Aug 2026 16:03:41 -0400
Subject: [PATCH 4/4] Allow secondaryLinks in the articles content schema

The landing page gained a secondary meta-link row (release notes,
documentation versions); the YAML schema validation in CI rejects unknown
properties, so declare the new optional field.
---
 schema/articles.content.schema.json | 36 +++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/schema/articles.content.schema.json b/schema/articles.content.schema.json
index 1ba688a..0277cad 100644
--- a/schema/articles.content.schema.json
+++ b/schema/articles.content.schema.json
@@ -66,6 +66,42 @@
             },
             "additionalProperties": false
           }
+        },
+        "secondaryLinks": {
+          "type": "array",
+          "description": "Optional secondary meta links (e.g. release notes, documentation versions) rendered in a smaller row below the main section grid. Use for cross-cutting pages that are not documentation sections themselves.",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": {
+            "type": "object",
+            "description": "A single secondary link entry with a display title, optional one-line description, and a target URL path",
+            "required": ["title", "link"],
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "The display text for the secondary link.",
+                "minLength": 1,
+                "maxLength": 100,
+                "examples": ["Release Notes", "Documentation Versions"]
+              },
+              "description": {
+                "type": "string",
+                "description": "Optional one-line subtitle shown under the title.",
+                "minLength": 1,
+                "maxLength": 200,
+                "examples": ["What changed in each DocumentDB release"]
+              },
+              "link": {
+                "type": "string",
+                "description": "The URL path (relative or absolute) that the link navigates to.",
+                "pattern": "^(/|https?://)",
+                "minLength": 1,
+                "maxLength": 500,
+                "examples": ["/docs/release-notes", "/docs/versions"]
+              }
+            },
+            "additionalProperties": false
+          }
         }
       },
       "additionalProperties": false