From 58630e64d5c63da7b1f03e67b97b4c8eea348fbd 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/5] 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/Markdown.tsx                   |   9 +-
 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 +
 14 files changed, 624 insertions(+), 2 deletions(-)
 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/Markdown.tsx b/app/components/Markdown.tsx
index 84d1c72..67f9860 100644
--- a/app/components/Markdown.tsx
+++ b/app/components/Markdown.tsx
@@ -248,9 +248,16 @@ function getMarkdownComponents() {
     // /samples, #anchors) navigate in place
     a: ({ children, href, ...props }: any) => {
       const isExternal = /^https?:\/\//i.test(href ?? '');
+      // Site-root-relative links inside markdown bypass next/link, so the
+      // configured base path (project-page deployments) must be added here.
+      const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
+      const resolvedHref =
+        !isExternal && href?.startsWith('/') && basePath && !href.startsWith(`${basePath}/`)
+          ? `${basePath}${href}`
+          : href;
       return (
         <a
-          href={href}
+          href={resolvedHref}
           className="text-blue-400 hover:text-blue-300 transition-colors"
           {...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
           {...props}
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 6170f50..cf84ec9 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 \\
@@ -310,6 +312,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} />
                     </div>
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 7cf108a..02870f7 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -14,5 +14,9 @@ landing:
       link: /docs/documentdb-local
     - title: Architecture under the hood
       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 1d24560..ec770bd 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 50aa062..e6f60c5 100644
--- a/scripts/generate-sitemap.mjs
+++ b/scripts/generate-sitemap.mjs
@@ -54,6 +54,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 af9fe0e3a33136a66eec60208815e182a6cb56bb Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhou.song@gmail.com>
Date: Mon, 3 Aug 2026 14:35:47 -0400
Subject: [PATCH 2/5] Fork demo: build versioned docs from GuanzhouSong/docs
 and deploy as project page

Points the content pipeline at the docs fork (which carries the v0.114-0
snapshot tag and release-notes section), compiles the v0.114-0 archived
version, and deploys to GitHub Pages under /documentdb.github.io/ with the
package-repository build steps omitted. This commit is demo-only and is not
intended for the upstream repository.
---
 .github/workflows/continuous-deployment.yml | 118 +++-----------------
 content.config.json                         |   9 +-
 2 files changed, 20 insertions(+), 107 deletions(-)

diff --git a/.github/workflows/continuous-deployment.yml b/.github/workflows/continuous-deployment.yml
index d783e30..d1f3206 100644
--- a/.github/workflows/continuous-deployment.yml
+++ b/.github/workflows/continuous-deployment.yml
@@ -1,59 +1,27 @@
-# Workflow for building Next.js site and downloading DocumentDB packages, then deploying to GitHub Pages
-name: Deploy Next.js site and DocumentDB packages to Pages
+# Fork-demo deployment: builds the Next.js site (including versioned docs
+# snapshots) and deploys to GitHub Pages as a project page under
+# /documentdb.github.io/. The upstream workflow additionally builds the
+# APT/RPM package repositories; those steps are omitted here because the fork
+# demo only showcases the documentation site.
+name: Deploy Next.js site to Pages (fork demo)
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches:
       - main
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: pages
   cancel-in-progress: false
 jobs:
-  # Build job
   build:
     name: Build Next.js static site
-    # Sets permissions of the GITHUB_TOKEN to allow reading of repository content
     permissions:
       contents: read
     runs-on: ubuntu-22.04
-    # Without an explicit timeout a stalled step runs against GitHub's 6-hour
-    # default before failing, which for `pages` concurrency means blocking
-    # every deployment queued behind it.
     timeout-minutes: 30
     steps:
       - name: Checkout source
         uses: actions/checkout@v7
-      - name: Install required packages
-        run: |
-          until sudo apt-get update; do sleep 1; done
-          sudo apt-get install -y createrepo-c dpkg-dev dpkg-sig gnupg2 python3
-      - name: Setup GPG
-        id: import_gpg
-        uses: crazy-max/ghaction-import-gpg@v7
-        with:
-          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
-        continue-on-error: true
-      - name: Set GPG fingerprint and version config
-        run: |
-          # Configure GPG signing
-          if [ -n "${{ steps.import_gpg.outputs.fingerprint }}" ]; then
-            echo "GPG_FINGERPRINT=${{ steps.import_gpg.outputs.fingerprint }}" >> $GITHUB_ENV
-            echo "✅ GPG key loaded successfully"
-            echo "   Fingerprint: ${{ steps.import_gpg.outputs.fingerprint }}"
-            echo "   Key ID: ${{ steps.import_gpg.outputs.keyid }}"
-            echo "   User ID: ${{ steps.import_gpg.outputs.name }} <${{ steps.import_gpg.outputs.email }}>"
-          else
-            echo "⚠️ No GPG key configured - packages will not be signed"
-            echo "   To enable signing, add GPG_PRIVATE_KEY to repository secrets"
-          fi
-          
-          # Configure DocumentDB version (can be overridden by repository variables)
-          echo "DOCUMENTDB_VERSION=${{ vars.DOCUMENTDB_VERSION || 'latest' }}" >> $GITHUB_ENV
-          echo "MULTI_VERSION=${{ vars.MULTI_VERSION || 'true' }}" >> $GITHUB_ENV
       - name: Setup Node.js
         uses: actions/setup-node@v7
         with:
@@ -69,31 +37,23 @@ jobs:
         with:
           path: |
             .next/cache
-          # Generate a new cache whenever packages or source files change.
           key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
-          # If source files changed but packages didn't, rebuild from a prior cache.
           restore-keys: |
             ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
       - name: Install dependencies
         run: npm ci
       - name: Build with Next.js
-        # This repository is the organization Pages site served at the root of
-        # the custom domain (documentdb.io), so the build must NOT set
-        # NEXT_BASE_PATH. Setting it to the repository name (the usual trick
-        # for project pages) prefixes every internal link and asset URL with
-        # /documentdb.github.io/, which GitHub Pages then 301-redirects back
-        # to the root on every request and leaves the prefixed URL visible in
-        # the address bar after client-side navigation.
+        # This fork deploys as a PROJECT page at
+        # https://guanzhousong.github.io/documentdb.github.io/, so unlike the
+        # upstream org-domain deployment the base path MUST be set.
         env:
-          JEKYLL_BASE_PATH: /blogs
+          NEXT_BASE_PATH: documentdb.github.io
+          JEKYLL_BASE_PATH: /documentdb.github.io/blogs
         run: npm run build
       - name: Verify exported documentation pages
-        # A partially failed content compile must never reach production as a
-        # docs-less site. compile-content fails the build on clone/copy errors;
-        # this is the independent belt-and-braces check on the final artifact.
         run: |
           set -euo pipefail
-          for page in out/index.html out/docs/index.html out/docs/getting-started/index.html out/docs/reference/index.html; do
+          for page in out/index.html out/docs/index.html out/docs/getting-started/index.html out/docs/reference/index.html out/docs/versions/index.html out/docs/v/v0.114-0/getting-started/index.html; do
             if [ ! -f "$page" ]; then
               echo "Missing expected page: $page"
               exit 1
@@ -101,61 +61,14 @@ jobs:
           done
           reference_count=$(find out/docs/reference -name index.html | wc -l)
           echo "Reference pages exported: $reference_count"
-          # The docs repo currently holds ~240 reference entries; well under
-          # half of that means the compile silently lost content.
           if [ "$reference_count" -lt 100 ]; then
             echo "Only $reference_count reference pages exported - documentation content looks incomplete."
             exit 1
           fi
-      - name: Download DocumentDB packages from latest release
-        run: .github/scripts/download_packages.sh
-      - name: Verify generated package components
-        run: |
-          set -euo pipefail
-          python3 - <<'PY'
-          import json
-          from pathlib import Path
-
-          release_info = Path("out/packages/release-info.json")
-          if not release_info.exists():
-              raise SystemExit("release-info.json was not generated")
-
-          data = json.loads(release_info.read_text())
-          assets = [asset["name"] for asset in data.get("assets", [])]
-          components = ("deb11", "deb12", "deb13", "ubuntu22", "ubuntu24")
-
-          for component in components:
-              has_assets = any(
-                  name.endswith(".deb")
-                  and (
-                      name.startswith(f"{component}-")
-                      or name.startswith(f"{component}.04-")
-                  )
-                  for name in assets
-              )
-              if not has_assets:
-                  continue
-
-              for arch in ("amd64", "arm64"):
-                  packages = Path(f"out/deb/dists/stable/{component}/binary-{arch}/Packages")
-                  packages_gz = Path(f"out/deb/dists/stable/{component}/binary-{arch}/Packages.gz")
-                  if not packages.exists() or not packages_gz.exists():
-                      raise SystemExit(
-                          f"Missing APT metadata for {component} {arch}: "
-                          f"{packages} / {packages_gz}"
-                      )
-
-          release_file = Path("out/deb/dists/stable/Release")
-          if release_file.exists() and any(name.startswith("deb13-") and name.endswith(".deb") for name in assets):
-              release_text = release_file.read_text()
-              if "deb13" not in release_text:
-                  raise SystemExit("deb13 assets exist but deb13 is missing from the APT Release file")
-          PY
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5
         with:
           path: ./out
-  # Deployment job
   deploy:
     name: Publish site to GitHub Pages
     environment:
@@ -165,7 +78,6 @@ jobs:
     timeout-minutes: 10
     needs:
       - build
-    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
     permissions:
       pages: write
       id-token: write
@@ -173,11 +85,7 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v6
         with:
-          # Automatically inject basePath in your Next.js configuration file and disable
-          # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
-          #
-          # You may remove this line if you want to manage the configuration yourself.
-          static_site_generator: next
+          enablement: true
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5
diff --git a/content.config.json b/content.config.json
index 9ed62af..506a6e3 100644
--- a/content.config.json
+++ b/content.config.json
@@ -1,7 +1,7 @@
 {
   "sources": [
     {
-      "repository": "https://github.com/documentdb/docs",
+      "repository": "https://github.com/GuanzhouSong/docs",
       "branch": "main",
       "mappings": [
         {
@@ -33,7 +33,12 @@
           "target": "articles/release-notes"
         }
       ],
-      "versions": []
+      "versions": [
+        {
+          "label": "v0.114-0",
+          "ref": "v0.114-0"
+        }
+      ]
     }
   ],
   "include": [

From 75d8f332402bb38106806fad6d8b0a57bb42f639 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 3/5] 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 +-
 11 files changed, 466 insertions(+), 200 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 cf84ec9..458a58e 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 \\
@@ -85,35 +89,47 @@ export default async function ArticlePage({ params }: PageProps) {
     // Use title from frontmatter if available, otherwise fall back to navigation title or section name
     const pageTitle = frontmatter.title || selectedNavItem?.title || section;
     const showInstallPrimer = section === "getting-started" && file === "index";
-    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 */}
@@ -128,62 +144,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 */}
                         {frontmatter.layout === 'coming-soon' && <ComingSoon />}
@@ -312,28 +282,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} />
                     </div>
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 02870f7..4c6e846 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -14,9 +14,12 @@ landing:
       link: /docs/documentdb-local
     - title: Architecture under the hood
       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

From 63e8fafd0b3ba0f57d1b16b6129eff7ddb15687a 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 4/5] 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.
---
 .github/workflows/continuous-deployment.yml   |  2 +-
 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 +++--
 9 files changed, 47 insertions(+), 30 deletions(-)
 rename app/docs/{v => versions}/[version]/[section]/[[...slug]]/page.tsx (85%)
 rename app/docs/{v => versions}/[version]/page.tsx (98%)

diff --git a/.github/workflows/continuous-deployment.yml b/.github/workflows/continuous-deployment.yml
index d1f3206..e45b5b1 100644
--- a/.github/workflows/continuous-deployment.yml
+++ b/.github/workflows/continuous-deployment.yml
@@ -53,7 +53,7 @@ jobs:
       - name: Verify exported documentation pages
         run: |
           set -euo pipefail
-          for page in out/index.html out/docs/index.html out/docs/getting-started/index.html out/docs/reference/index.html out/docs/versions/index.html out/docs/v/v0.114-0/getting-started/index.html; do
+          for page in out/index.html out/docs/index.html out/docs/getting-started/index.html out/docs/reference/index.html out/docs/versions/index.html out/docs/versions/v0.114-0/getting-started/index.html; do
             if [ ! -f "$page" ]; then
               echo "Missing expected page: $page"
               exit 1
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 e6f60c5..d29c535 100644
--- a/scripts/generate-sitemap.mjs
+++ b/scripts/generate-sitemap.mjs
@@ -54,9 +54,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 295ab8d05e814b6785a6bc6091f6d81cc40e23a4 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 5/5] 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