From 929cbcc47bfbb7c68da4c52ccebf7851a8be023b Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 10 Sep 2026 13:42:11 -0400
Subject: [PATCH 1/3] Add versioned documentation snapshots

Compile frozen documentation snapshots from tags of the content repository
into versioned/<label>/ and serve them under /docs/versions/<label>/, so a
reader on an older DocumentDB release can find the docs that shipped with it.

The sidebar, breadcrumb and version switcher are extracted into shared
components used by both the current and the archived routes. Every link in
the sidebar stays inside the version being viewed, so a reader cannot fall
out of an archived version by navigating.

Archived pages are noindex, which is what keeps them out of sitemap.xml -
the generator already skips any page that says so about itself, so there is
no second list to keep in sync.

The base path is now derived in the workflow instead of hard-coded: upstream
resolves it to the empty string exactly as before, while a fork resolves it
to its repository name and can deploy a working preview without editing the
workflow.
---
 .github/workflows/continuous-deployment.yml   |  35 ++-
 .gitignore                                    |   3 +
 app/components/Breadcrumb.tsx                 |   4 +
 app/components/DocsBreadcrumb.tsx             |  30 +++
 app/components/DocsSidebar.tsx                | 145 ++++++++++++
 app/components/VersionSwitcher.tsx            |  55 +++++
 app/docs/[section]/[[...slug]]/page.tsx       | 127 ++++------
 app/docs/page.tsx                             |  23 ++
 .../[version]/[section]/[[...slug]]/page.tsx  | 141 +++++++++++
 app/docs/versions/[version]/page.tsx          | 102 ++++++++
 app/docs/versions/page.tsx                    | 115 +++++++++
 app/services/versionService.ts                | 222 ++++++++++++++++++
 app/types/Article.ts                          |   6 +
 articles/content.yml                          |   4 +
 schema/articles.content.schema.json           |  36 +++
 scripts/compile-clean.tsx                     |   9 +
 scripts/compile-content.tsx                   |  53 +++++
 17 files changed, 1025 insertions(+), 85 deletions(-)
 create mode 100644 app/components/DocsBreadcrumb.tsx
 create mode 100644 app/components/DocsSidebar.tsx
 create mode 100644 app/components/VersionSwitcher.tsx
 create mode 100644 app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
 create mode 100644 app/docs/versions/[version]/page.tsx
 create mode 100644 app/docs/versions/page.tsx
 create mode 100644 app/services/versionService.ts

diff --git a/.github/workflows/continuous-deployment.yml b/.github/workflows/continuous-deployment.yml
index c9c2f71..59236a2 100644
--- a/.github/workflows/continuous-deployment.yml
+++ b/.github/workflows/continuous-deployment.yml
@@ -64,8 +64,27 @@ jobs:
             sign=false
           fi
 
+          # Upstream is the organization Pages site served at the root of the
+          # custom domain (documentdb.io), so it must NOT set a base path:
+          # prefixing every internal link and asset with the repository name
+          # makes GitHub Pages 301 back to the root on every request and leaves
+          # the prefixed URL in the address bar after client-side navigation.
+          # A fork is the opposite case - it is served as a project page under
+          # /<repo>/, where the prefix is required for assets to resolve at all.
+          # Deriving it here is what lets a fork deploy a working preview of a
+          # docs change without editing the workflow.
+          if [ "$IS_UPSTREAM" = 'true' ]; then
+            base_path=''
+            jekyll_base_path='/blogs'
+          else
+            base_path="${GITHUB_REPOSITORY##*/}"
+            jekyll_base_path="/${base_path}/blogs"
+          fi
+
           echo "packages=$packages" >> "$GITHUB_OUTPUT"
           echo "sign=$sign" >> "$GITHUB_OUTPUT"
+          echo "base_path=$base_path" >> "$GITHUB_OUTPUT"
+          echo "jekyll_base_path=$jekyll_base_path" >> "$GITHUB_OUTPUT"
 
           {
             echo "### Build configuration"
@@ -75,6 +94,7 @@ jobs:
             echo "| Static site | true | always built |"
             echo "| Package repositories | $packages | \`BUILD_PACKAGES\` variable |"
             echo "| Package signing | $sign | \`GPG_PRIVATE_KEY\` secret |"
+            echo "| Base path | ${base_path:-(none)} | upstream vs. fork |"
           } >> "$GITHUB_STEP_SUMMARY"
 
           if [ "$packages" = 'true' ] && [ "$sign" != 'true' ]; then
@@ -146,15 +166,12 @@ jobs:
       - 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.
+        # Both base paths are resolved in the "Resolve optional build features"
+        # step; upstream builds resolve NEXT_BASE_PATH to the empty string,
+        # which next.config.ts treats as "no base path".
         env:
-          JEKYLL_BASE_PATH: /blogs
+          NEXT_BASE_PATH: ${{ steps.features.outputs.base_path }}
+          JEKYLL_BASE_PATH: ${{ steps.features.outputs.jekyll_base_path }}
         run: npm run build
       - name: Verify exported documentation pages
         # A partially failed content compile must never reach production as a
@@ -162,7 +179,7 @@ jobs:
         # 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; do
             if [ ! -f "$page" ]; then
               echo "Missing expected page: $page"
               exit 1
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/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/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..e3ec070
--- /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/versions/<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
new file mode 100644
index 0000000..5632f80
--- /dev/null
+++ b/app/components/VersionSwitcher.tsx
@@ -0,0 +1,55 @@
+import Link from "next/link";
+import { VersionSwitcherEntry } from "../services/versionService";
+
+/**
+ * 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({ entries }: { entries: VersionSwitcherEntry[] }) {
+    const active = entries.find((entry) => entry.active);
+
+    return (
+        <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-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"
+                >
+                    All versions →
+                </Link>
+            </div>
+        </details>
+    );
+}
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 1e91f6d..ca539d2 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -1,12 +1,18 @@
 import Link from "next/link";
 import { notFound } 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 MovedNotice from "../../../components/MovedNotice";
+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 \\
@@ -125,37 +131,53 @@ export default async function ArticlePage({ params }: PageProps) {
     // with no heading element at all. Guarded in case a future coming-soon page
     // does start with one.
     const showComingSoonHeading = isComingSoon && !/^#\s/m.test(content);
-    const sectionTitle = capitalCase(section)
-        .replace(/documentdb/i, 'DocumentDB')
-        .replace(/api/i, 'API');
-
-    // 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. Compare the final path
-        // segment exactly - a substring test marks every sibling whose slug
-        // starts with this one (packages also matching packages-operations).
+    const sectionTitle = formatSectionTitle(section);
+
+    // Pages of this section, rendered once and shared by the desktop sidebar
+    // and the mobile disclosure.
+    // For index files, match both /section and /section/index. For other files,
+    // compare the final path segment exactly - a substring test marks every
+    // sibling whose slug starts with this one (packages also matching
+    // packages-operations).
+    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`) ||
             (file !== 'index' && item.link.split('/').pop() === file);
 
-        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 };
     });
 
+    // Sibling sections, so a reader can cross to another section without
+    // returning to the docs index first.
+    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 */}
@@ -170,62 +192,15 @@ 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} />
+
+                        <DocsBreadcrumb crumbs={breadcrumbs} />
 
                         {/* Coming Soon Component for coming-soon layout */}
                         {showComingSoonHeading && (
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/versions/[version]/[section]/[[...slug]]/page.tsx b/app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
new file mode 100644
index 0000000..f77796f
--- /dev/null
+++ b/app/docs/versions/[version]/[section]/[[...slug]]/page.tsx
@@ -0,0 +1,141 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import {
+    formatSectionTitle,
+    getAllVersionedArticlePaths,
+    getVersionedArticleByPath,
+    getVersionedSections,
+    getVersionSwitcherEntries,
+    orderSections,
+} from "../../../../../services/versionService";
+import Markdown from "../../../../../components/Markdown";
+import DocsSidebar, { DocsSidebarMobile } from "../../../../../components/DocsSidebar";
+import DocsBreadcrumb from "../../../../../components/DocsBreadcrumb";
+
+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 = 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/versions/<v>/,
+    // and only the banner/switcher deliberately exit to current.
+    const navItems = navigation.map((item) => {
+        const isActive =
+            file === "index"
+                ? 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/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/versions/${version}`,
+        backLabel: `${version} documentation home`,
+        sectionTitle,
+        nav: navItems,
+        sections: sectionItems,
+        switcherEntries,
+    };
+
+    const breadcrumbs = [
+        { title: "Docs", href: "/docs" },
+        { title: version, href: `/docs/versions/${version}` },
+        ...(file === "index"
+            ? [{ title: sectionTitle }]
+            : [
+                { title: sectionTitle, href: `/docs/versions/${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">
+                <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">
+                                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>
+
+                        <Markdown
+                            content={content}
+                            sourcePath={`/docs/versions/${version}/${section}/${file}.md`}
+                        />
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}
diff --git a/app/docs/versions/[version]/page.tsx b/app/docs/versions/[version]/page.tsx
new file mode 100644
index 0000000..2d3ba5c
--- /dev/null
+++ b/app/docs/versions/[version]/page.tsx
@@ -0,0 +1,102 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+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 }));
+}
+
+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 = orderSections(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">
+                <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>. 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>
+
+                <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) => (
+                        <Link
+                            key={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>
+                            <p className="mt-1 text-sm text-gray-400">
+                                Browse this section as of {version}
+                            </p>
+                        </Link>
+                    ))}
+                </div>
+
+                <p className="mt-10 text-sm text-gray-500">
+                    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>
+                    .
+                </p>
+            </div>
+        </div>
+    );
+}
diff --git a/app/docs/versions/page.tsx b/app/docs/versions/page.tsx
new file mode 100644
index 0000000..62c3788
--- /dev/null
+++ b/app/docs/versions/page.tsx
@@ -0,0 +1,115 @@
+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({
+        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">
+                <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,
+                    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{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>
+                                </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/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">
+                                <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..2b9b753
--- /dev/null
+++ b/app/services/versionService.ts
@@ -0,0 +1,222 @@
+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/versions/<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/versions/<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/versions/${version}/${section}`
+          : `/docs/versions/${version}/${section}/${file}`;
+    }
+
+    return { ...link, link: transformedLink, children: undefined };
+  });
+}
+
+/** 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}`;
+  })();
+
+  // 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: versions[0] ? `Current (${versions[0]}, latest)` : 'Current (latest release)',
+      href: currentTarget,
+      active: viewing === 'current',
+    },
+  ];
+
+  for (const version of versions) {
+    const target = (() => {
+      if (!section) return `/docs/versions/${version}`;
+      if (!fs.existsSync(path.join(versionArticlesDir(version), section))) {
+        return `/docs/versions/${version}`;
+      }
+      if (!file || file === 'index') return `/docs/versions/${version}/${section}`;
+      if (versionedArticleExists(version, section, file)) {
+        return `/docs/versions/${version}/${section}/${file}`;
+      }
+      return `/docs/versions/${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,
+  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/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 84b6781..c1fbdf1 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -16,3 +16,7 @@ landing:
       link: /docs/architecture
     - title: Samples & Demos
       link: /samples
+  secondaryLinks:
+    - title: Documentation Versions
+      description: Current docs and archived snapshots of earlier releases
+      link: /docs/versions
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
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..ad14578 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/versions/<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

From 35eaec30b514955c913672ddfc367e3206e33ddd Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 10 Sep 2026 14:02:39 -0400
Subject: [PATCH 2/3] Label the version switcher and versions index with the
 release current docs describe

Both controls derived their "current" label from the newest snapshot label,
but a snapshot is by definition an older release - so each printed the same
version twice. The switcher showed "Current (v0.114-0, latest)" directly above
"v0.114-0 (archived)", and the versions index showed "Current - v0.114-0"
above "v0.114-0 archived snapshot", in two controls whose only job is telling
versions apart.

Read the tag from a server-safe constant instead. FALLBACK_RELEASE lives in a
client module and arrives in server code as a client reference, rendering as
"undefined", and its object literal is parsed by the CI release drift check so
it cannot be refactored. A test pins the two together so they cannot drift.
---
 app/docs/versions/page.tsx     |  3 ++-
 app/lib/currentRelease.ts      | 13 +++++++++++++
 app/services/versionService.ts | 11 ++++++++---
 tests/currentRelease.test.ts   | 13 +++++++++++++
 4 files changed, 36 insertions(+), 4 deletions(-)
 create mode 100644 app/lib/currentRelease.ts
 create mode 100644 tests/currentRelease.test.ts

diff --git a/app/docs/versions/page.tsx b/app/docs/versions/page.tsx
index 62c3788..1dae130 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 { CURRENT_RELEASE_TAG } from "../../lib/currentRelease";
 import DocsBreadcrumb from "../../components/DocsBreadcrumb";
 
 export async function generateMetadata() {
@@ -40,7 +41,7 @@ export default function VersionsPage() {
                         <div className="flex items-center justify-between">
                             <div>
                                 <p className="font-semibold text-white">
-                                    Current{hostedVersions[0] ? ` — ${hostedVersions[0]}` : ""}{" "}
+                                    Current &mdash; {CURRENT_RELEASE_TAG}{" "}
                                     <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>
diff --git a/app/lib/currentRelease.ts b/app/lib/currentRelease.ts
new file mode 100644
index 0000000..62fecfd
--- /dev/null
+++ b/app/lib/currentRelease.ts
@@ -0,0 +1,13 @@
+/**
+ * Tag of the DocumentDB release the current documentation describes.
+ *
+ * This duplicates `FALLBACK_RELEASE.tagName`, and deliberately so. That module
+ * is a client module, and a value imported from one into server code arrives as
+ * a client reference rather than the string - it renders as "undefined" in the
+ * static export. Server code that needs the release tag reads it from here.
+ *
+ * `tests/currentRelease.test.ts` asserts the two stay equal, so the CI release
+ * drift check keeps parsing the object literal it already parses, and this
+ * constant cannot silently fall behind it.
+ */
+export const CURRENT_RELEASE_TAG = "v0.117-0";
diff --git a/app/services/versionService.ts b/app/services/versionService.ts
index 2b9b753..9603e4e 100644
--- a/app/services/versionService.ts
+++ b/app/services/versionService.ts
@@ -3,6 +3,7 @@ import path from 'path';
 import { load as loadYaml } from 'js-yaml';
 import matter from 'gray-matter';
 import { Link } from '../types/Link';
+import { CURRENT_RELEASE_TAG } from '../lib/currentRelease';
 
 /**
  * Serves frozen documentation snapshots compiled by scripts/compile-content.tsx
@@ -159,12 +160,16 @@ 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.
+  // Name the release "current" actually describes, so a reader can tell at a
+  // glance whether they are on the docs for the build they installed. This has
+  // to come from the release the site documents - deriving it from the newest
+  // snapshot label instead would print the archive's own version here, which is
+  // by definition an older release, and would render the same number twice in a
+  // switcher whose whole job is telling two versions apart.
   const versions = getDocVersions();
   const entries: VersionSwitcherEntry[] = [
     {
-      label: versions[0] ? `Current (${versions[0]}, latest)` : 'Current (latest release)',
+      label: `Current (${CURRENT_RELEASE_TAG}, latest)`,
       href: currentTarget,
       active: viewing === 'current',
     },
diff --git a/tests/currentRelease.test.ts b/tests/currentRelease.test.ts
new file mode 100644
index 0000000..c64e672
--- /dev/null
+++ b/tests/currentRelease.test.ts
@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { FALLBACK_RELEASE } from '../app/lib/releaseInfo';
+import { CURRENT_RELEASE_TAG } from '../app/lib/currentRelease';
+
+describe('CURRENT_RELEASE_TAG', () => {
+  // The version switcher labels "current" with this tag. If it falls behind the
+  // release the rest of the site documents, every docs page tells the reader
+  // they are on a version they are not on - the exact confusion versioned docs
+  // exist to remove.
+  it('matches the release the site documents', () => {
+    expect(CURRENT_RELEASE_TAG).toBe(FALLBACK_RELEASE.tagName);
+  });
+});

From 21060946ff4978b8d9cdc51b95f6748e7406ae94 Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 10 Sep 2026 14:10:00 -0400
Subject: [PATCH 3/3] Demo: build the versioned docs preview from
 GuanzhouSong/docs

REVERT BEFORE MERGE. Points the content compiler at a personal fork of the
docs repository so the versioned-docs design can be previewed end to end:
documentdb/docs currently carries no tags and no release-notes/ directory,
so with the upstream config the versions list is necessarily empty and there
is nothing for reviewers to look at.

Isolated to this commit, and to two files, so dropping it once documentdb/docs
is tagged is a single revert.
---
 articles/content.yml |  3 +++
 content.config.json  | 12 +++++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/articles/content.yml b/articles/content.yml
index c1fbdf1..c03ad24 100644
--- a/articles/content.yml
+++ b/articles/content.yml
@@ -17,6 +17,9 @@ landing:
     - 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 and archived snapshots of earlier releases
       link: /docs/versions
diff --git a/content.config.json b/content.config.json
index 917e4c2..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": [
         {
@@ -27,6 +27,16 @@
         {
           "source": "kubernetes-operator",
           "target": "articles/kubernetes-operator"
+        },
+        {
+          "source": "release-notes",
+          "target": "articles/release-notes"
+        }
+      ],
+      "versions": [
+        {
+          "label": "v0.114-0",
+          "ref": "v0.114-0"
         }
       ]
     }