blume 1.4.2 → 1.5.0

package/src/core/data.ts

@@ -1,6 +1,6 @@
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
-import type { Navigation, RouteAlternate } from "./types.ts";
+import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 
 /**
  * The shape of the `blume:data` virtual module — the resolved, serializable
@@ -85,6 +85,14 @@ export interface BlumeRoute {
   locale: string;
   path: string;
   title: string;
+  /** Resolved docs version (`""` for the current docs). */
+  version: string;
+  /**
+   * Versions this logical page exists in within this route's locale — the
+   * current version first, then archived versions in configured order. Empty
+   * when versioning is off.
+   */
+  versionAlternates: VersionAlternate[];
 }
 
 /** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
@@ -161,6 +169,8 @@ export interface BlumeDataConfig {
    * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
    * list tool to fetch (`ai.llmsTxt.enabled`).
    */
+  /** Docs versioning config; `null` when the site is unversioned. */
+  versions: NonNullable<ResolvedConfig["versions"]> | null;
   webmcp: { enabled: boolean; llms: boolean };
   /** X (Twitter) attribution: the site's account, and a default creator. */
   x: { creator?: string; handle?: string };
@@ -188,6 +198,11 @@ export interface BlumeData {
   navigation: Navigation;
   /** Per-locale navigation trees, keyed by locale code (empty without i18n). */
   navigationByLocale: Record<string, Navigation>;
+  /**
+   * Per-archived-version navigation trees, keyed by version id and then locale
+   * code (`""` on a single-locale site). Empty when versioning is off.
+   */
+  navigationByVersion: Record<string, Record<string, Navigation>>;
   routes: BlumeRoute[];
   /** Resolved UI strings for the default locale. */
   ui: UIStrings;

package/src/core/define-components.ts

@@ -18,6 +18,10 @@ export interface IslandDescriptor {
 export type ComponentOverride = ComponentReference | IslandDescriptor;
 
 /** User-authored component overrides, grouped by surface. */
+// oxlint-disable anti-slop/no-unsafe-dictionary-type -- `ComponentOverride` is untyped by
+// design: user configs pass imported components from any framework (React
+// functions, Svelte classes, Vue SFC objects), which share no structural type.
+// `resolveSlot` and the generated components map are the runtime boundary.
 export interface ComponentOverrides {
   /**
    * Interactive framework components made available in every `.mdx` page. Like
@@ -31,6 +35,7 @@ export interface ComponentOverrides {
   /** MDX component map overrides (`Callout`, `Card`, ...). */
   mdx?: Record<string, ComponentOverride>;
 }
+// oxlint-enable anti-slop/no-unsafe-dictionary-type
 
 /**
  * Identity helper for authoring `components.ts`. Provides type inference and a

package/src/core/diagnostics.ts

@@ -27,41 +27,44 @@ const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
 
 /** Diagnostic code → the docs page that explains it. */
-const DOCS_PATHS: Record<string, string> = {
-  BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
-  BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
-  BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
-  BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
-  BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
-  BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
-  BLUME_CONFIG_INVALID: "/docs/configuration",
-  BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
-  BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
-  BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
-  BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
-  BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
-  BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
-  BLUME_META_INVALID: "/docs/content/meta",
-  BLUME_META_LOAD_FAILED: "/docs/content/meta",
-  BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
-  BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
-  BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
-  BLUME_NODE_VERSION: "/docs/quickstart",
-  BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
-  BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
-  BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
-  BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
-  BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
-};
+const DOCS_PATHS = new Map(
+  Object.entries({
+    BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
+    BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
+    BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+    BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
+    BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
+    BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
+    BLUME_CONFIG_INVALID: "/docs/configuration",
+    BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
+    BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
+    BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
+    BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
+    BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
+    BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+    BLUME_META_INVALID: "/docs/content/meta",
+    BLUME_META_LOAD_FAILED: "/docs/content/meta",
+    BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
+    BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
+    BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
+    BLUME_NODE_VERSION: "/docs/quickstart",
+    BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
+    BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
+    BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
+    BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
+    BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+    BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
+  })
+);
 
 /** The docs URL that explains a diagnostic code, if one is mapped. */
 export const resolveDocsUrl = (code: string): string | undefined => {
-  const path = DOCS_PATHS[code];
+  const path = DOCS_PATHS.get(code);
   return path ? `${DOCS_BASE}${path}` : undefined;
 };
 
@@ -75,6 +78,10 @@ const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
 const escapeRegExp = (value: string): string =>
   value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
 
+/** A key segment scans the source text; an array index has no key to find. */
+const isKeySegment = (segment: string | number): segment is string =>
+  typeof segment === "string";
+
 /**
  * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`) in
  * the raw config / frontmatter text. Narrows key-by-key — finding each string
@@ -86,9 +93,9 @@ const stepSegment = (
   source: string,
   segment: string | number,
   cursor: number
-): { index: number; next: number; stop: boolean } => {
+) => {
   // A non-string path segment (array index) is skipped without moving on.
-  if (typeof segment !== "string") {
+  if (!isKeySegment(segment)) {
     return { index: -1, next: cursor, stop: false };
   }
   // The negative lookbehind keeps a segment like `title` from matching the
@@ -247,10 +254,11 @@ export const formatDiagnostic = (
 export const hasErrors = (diagnostics: Diagnostic[]): boolean =>
   diagnostics.some((d) => d.severity === "error");
 
-export const countBySeverity = (
-  diagnostics: Diagnostic[]
-): Record<Diagnostic["severity"], number> => {
-  const counts = { error: 0, info: 0, warning: 0 };
+export const countBySeverity = (diagnostics: Diagnostic[]) => {
+  const counts = { error: 0, info: 0, warning: 0 } satisfies Record<
+    Diagnostic["severity"],
+    number
+  >;
   for (const diagnostic of diagnostics) {
     counts[diagnostic.severity] += 1;
   }

package/src/core/frontmatter.ts

@@ -14,27 +14,97 @@ type MatterOptions = Parameters<typeof baseMatter>[1];
 type ReadArgs = Parameters<typeof baseMatter.read>;
 type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 
+/** Front matter data as gray-matter types it (`GrayMatterFile["data"]`). */
+type FrontMatterData = ReturnType<typeof baseMatter>["data"];
+
 const yamlEngine = {
+  // SAFETY: gray-matter's engine contract expects an object; a front matter
+  // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
+  // input, which gray-matter treats the same way its bundled engine's output
+  // is treated.
   parse: (input: string): object => (load(input) ?? {}) as object,
-  stringify: (data: object): string => dump(data),
+  stringify: (data: FrontMatterData): string => dump(data),
 };
 
-const withYamlEngine = <O>(options: O): O =>
+const withYamlEngine = <O extends { engines?: object } | undefined>(
+  options: O
+): O =>
+  // SAFETY: the spread keeps every field of `options`; adding a default yaml
+  // engine (overridden by any caller-supplied `engines`) stays within O's
+  // shape — TS just can't prove a spread of a generic re-satisfies O.
   ({
     ...options,
     engines: {
       yaml: yamlEngine,
-      ...(options as { engines?: object })?.engines,
+      ...options?.engines,
     },
   }) as O;
 
+/**
+ * True when a document's leading `---` line is a CommonMark thematic break,
+ * not a front matter fence. Two shapes qualify (mirroring
+ * `linesWithoutFrontMatter` in `sources/normalize.ts`):
+ *   - the next line is blank (or absent) — YAML metadata starts on the very
+ *     next line, so a gap means the body *opens* with a divider (e.g. a
+ *     Notion page whose first block is one);
+ *   - no closing `---` line follows — gray-matter would swallow the whole
+ *     document as one unclosed YAML block and hand it to js-yaml, which
+ *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ */
+const opensWithThematicBreak = (input: string): boolean => {
+  const [first = "", second] = input.split(/\r?\n/u, 2);
+  if (!/^-{3}\s*$/u.test(first)) {
+    return false;
+  }
+  if (second === undefined || second.trim() === "") {
+    return true;
+  }
+  // gray-matter closes the block at the next line-leading `---`; matching its
+  // search exactly keeps this guard from firing on any document it parses.
+  return !input.includes("\n---", 1);
+};
+
+/**
+ * gray-matter's runtime result carries `isEmpty`, which its declared
+ * GrayMatterFile type omits.
+ */
+interface MatterResult extends ReturnType<typeof baseMatter> {
+  isEmpty: boolean;
+}
+
+/**
+ * The parse result for a document with no front matter: the input passes
+ * through as content, untouched. Shaped like gray-matter's own no-matter
+ * result (every Blume call site reads only `content` and `data`).
+ */
+const passthrough = (input: string): ReturnType<typeof baseMatter> => {
+  const file: MatterResult = {
+    content: input,
+    data: {},
+    excerpt: "",
+    isEmpty: false,
+    language: "",
+    matter: "",
+    orig: input,
+    // Recomposing a file with no matter and empty data is the content itself.
+    stringify: (): string => input,
+  };
+  return file;
+};
+
+/** Narrows gray-matter's input union to the raw-string form. */
+const isStringInput = (input: MatterInput): input is string =>
+  typeof input === "string";
+
 // Every helper that parses or emits YAML (`read`, `stringify`) must be
 // re-wrapped here — Object.assign copies gray-matter's own helpers, which use
 // its default `safeLoad` engine and would reintroduce the crash. `test` only
 // checks for a delimiter, so the copied original is safe.
 const matter = Object.assign(
   (input: MatterInput, options?: MatterOptions) =>
-    baseMatter(input, withYamlEngine(options)),
+    isStringInput(input) && opensWithThematicBreak(input)
+      ? passthrough(input)
+      : baseMatter(input, withYamlEngine(options)),
   baseMatter,
   {
     read: (filepath: ReadArgs[0], options?: ReadArgs[1]) =>

package/src/core/graph.ts

@@ -7,6 +7,7 @@ import type {
   LocalizableLabel,
   ResolvedConfig,
   ResolvedI18nConfig,
+  ResolvedVersionsConfig,
 } from "./schema.ts";
 import type {
   ContentGraph,
@@ -15,6 +16,7 @@ import type {
   NavTab,
   PageRecord,
 } from "./types.ts";
+import { versionizeRoute } from "./versions.ts";
 
 interface BuildContentGraphOptions {
   /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
@@ -23,14 +25,13 @@ interface BuildContentGraphOptions {
   sharedFolderMeta?: Map<string, FolderMeta>;
   navigation: ResolvedConfig["navigation"];
   i18n?: ResolvedI18nConfig;
+  versions?: ResolvedVersionsConfig;
 }
 
 type FallbackLocale = ReturnType<typeof resolveFallbackLocale>;
 
 /** Build the route → page-id map, flagging any duplicate-route collisions. */
-const collectRoutes = (
-  pages: PageRecord[]
-): { diagnostics: Diagnostic[]; routes: Map<string, string> } => {
+const collectRoutes = (pages: PageRecord[]) => {
   const routes = new Map<string, string>();
   const diagnostics: Diagnostic[] = [];
   for (const page of pages) {
@@ -86,12 +87,16 @@ const localePagesFor = (
  * the active locale's entry, else the default locale's, else the map's first
  * entry (which is also what a single-locale site gets).
  */
+/** A label is either one string for every locale or a per-locale map. */
+const isSingleLabel = (label: LocalizableLabel): label is string =>
+  typeof label === "string";
+
 const resolveLabel = (
   label: LocalizableLabel,
   locale: string,
   defaultLocale?: string
 ): string => {
-  if (typeof label === "string") {
+  if (isSingleLabel(label)) {
     return label;
   }
   return (
@@ -117,7 +122,12 @@ const resolveTabLabels = (
     label: resolveLabel(tab.label, locale, defaultLocale),
   }));
 
-/** Build one locale's navigation tree from its own pages and folder meta. */
+/**
+ * Build one locale's navigation tree from its own pages and folder meta.
+ * `version` is the archived version id when building a snapshot's tree
+ * (`""` for the current docs): it shifts the folder-meta lookups into the
+ * snapshot's key space and roots the tree at the localized version root.
+ */
 const buildLocaleNavigation = (
   code: string,
   pages: PageRecord[],
@@ -125,7 +135,8 @@ const buildLocaleNavigation = (
   fallbackByKey: Map<string, PageRecord>,
   options: BuildContentGraphOptions,
   i18n: ResolvedI18nConfig,
-  diagnostics: Diagnostic[]
+  diagnostics: Diagnostic[],
+  version = ""
 ): Navigation => {
   // Localize internal tab paths — the tab's own and its dropdown items' — so a
   // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
@@ -137,15 +148,20 @@ const buildLocaleNavigation = (
     options.navigation.tabs,
     code,
     i18n.defaultLocale
-  ).map((tab) => ({
-    ...tab,
-    ...(tab.href ? { href: localizePath(tab.href) } : {}),
-    items: tab.items?.map((item) => ({
-      ...item,
-      path: localizePath(item.path),
-    })),
-    path: localizePath(tab.path),
-  }));
+  ).map((tab) => {
+    const localized = {
+      ...tab,
+      items: tab.items?.map((item) => ({
+        ...item,
+        path: localizePath(item.path),
+      })),
+      path: localizePath(tab.path),
+    };
+    if (localized.href) {
+      localized.href = localizePath(localized.href);
+    }
+    return localized;
+  });
   const real = pages.filter((page) => page.locale === code);
   const localePages = localePagesFor(
     code,
@@ -155,6 +171,13 @@ const buildLocaleNavigation = (
     i18n,
     options.basePath ?? ""
   );
+  // Meta files live in locale directories only under the `dir` parser
+  // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
+  // next to the originals and `guides/meta.ts` applies to every locale —
+  // prefixing would look up keys that can never exist. Inside a snapshot the
+  // version dir is hoisted in front (`v1.0/fr`), matching `discoverFolderMeta`.
+  const localeDir =
+    i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
   return buildNavigation(localePages, {
     basePath: options.basePath ?? "",
     diagnostics,
@@ -167,34 +190,37 @@ const buildLocaleNavigation = (
       href: localizePath(link.href),
     })),
     folderMeta: options.folderMeta,
-    // The localized tree root ("/" for the hidden default, "/fr" otherwise):
-    // the tab pointing here spans the whole tree and must not be treated as a
-    // tab section.
-    localizedRoot: localizeRoute("/", code, i18n),
-    // Meta files live in locale directories only under the `dir` parser
-    // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
-    // next to the originals and `guides/meta.ts` applies to every locale —
-    // prefixing would look up keys that can never exist.
-    metaPrefix:
-      i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
+    // The localized tree root ("/" for the hidden default, "/fr" otherwise;
+    // "/fr/v1.0" inside a snapshot): the tab pointing here spans the whole
+    // tree and must not be treated as a tab section.
+    localizedRoot: localizeRoute(versionizeRoute("/", version), code, i18n),
+    metaPrefix: [version, localeDir].filter(Boolean).join("/"),
     refByLogical: true,
     selectors: options.navigation.selectors,
     sharedFolderMeta: options.sharedFolderMeta,
-    sidebar: options.navigation.sidebar.items,
+    // Shared `meta.$.*` files are locale-agnostic but version-specific: a
+    // snapshot's shared meta keys under its version dir.
+    sharedMetaPrefix: version,
+    // A configured explicit sidebar describes the current docs; a frozen
+    // snapshot's structure comes from the snapshot itself, so archived trees
+    // always build from the filesystem.
+    sidebar: version ? undefined : options.navigation.sidebar.items,
     tabs,
   });
 };
 
-/** Per-locale navigation trees plus the default-locale tree for i18n sites. */
+/**
+ * Per-locale navigation trees plus the default-locale tree for i18n sites.
+ * Called once for the current docs and once per archived version (with that
+ * version's pages and its id as `version`).
+ */
 const buildI18nNavigation = (
   pages: PageRecord[],
   options: BuildContentGraphOptions,
   i18n: ResolvedI18nConfig,
-  diagnostics: Diagnostic[]
-): {
-  navigation: Navigation;
-  navigationByLocale: Record<string, Navigation>;
-} => {
+  diagnostics: Diagnostic[],
+  version = ""
+) => {
   // Pages of the fallback locale, by translation key — used to fill in a
   // locale's sidebar for pages it hasn't translated yet.
   const fallback = resolveFallbackLocale(i18n);
@@ -223,7 +249,8 @@ const buildI18nNavigation = (
       fallbackByKey,
       options,
       i18n,
-      localeDiagnostics
+      localeDiagnostics,
+      version
     );
     for (const diagnostic of localeDiagnostics) {
       const key = `${diagnostic.code}\n${diagnostic.file ?? ""}\n${diagnostic.message}`;
@@ -233,7 +260,7 @@ const buildI18nNavigation = (
       }
     }
   }
-  const navigation = navigationByLocale[i18n.defaultLocale] ?? {
+  const navigation: Navigation = navigationByLocale[i18n.defaultLocale] ?? {
     featured: [],
     selectors: [],
     sidebar: [],
@@ -242,6 +269,37 @@ const buildI18nNavigation = (
   return { navigation, navigationByLocale };
 };
 
+/** One archived version's navigation trees, keyed by locale (`""` sans i18n). */
+const buildVersionNavigation = (
+  id: string,
+  versionPages: PageRecord[],
+  options: BuildContentGraphOptions,
+  diagnostics: Diagnostic[]
+) => {
+  const { i18n } = options;
+  if (i18n) {
+    return buildI18nNavigation(versionPages, options, i18n, diagnostics, id)
+      .navigationByLocale;
+  }
+  return {
+    "": buildNavigation(versionPages, {
+      basePath: options.basePath ?? "",
+      diagnostics,
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
+      folderMeta: options.folderMeta,
+      localizedRoot: versionizeRoute("/", id),
+      metaPrefix: id,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sharedMetaPrefix: id,
+      // A configured explicit sidebar describes the current docs; a snapshot's
+      // structure comes from the snapshot itself.
+      tabs: resolveTabLabels(options.navigation.tabs, ""),
+    }),
+  };
+};
+
 /** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
 export const buildContentGraph = (
   pages: PageRecord[],
@@ -250,37 +308,63 @@ export const buildContentGraph = (
   const { diagnostics, routes } = collectRoutes(pages);
   const { i18n } = options;
 
-  const { navigation, navigationByLocale } = i18n
-    ? buildI18nNavigation(pages, options, i18n, diagnostics)
-    : {
-        navigation: buildNavigation(pages, {
-          basePath: options.basePath ?? "",
-          diagnostics,
-          display: options.navigation.sidebar.display,
-          featured: options.navigation.featured,
-          folderMeta: options.folderMeta,
-          selectors: options.navigation.selectors,
-          sharedFolderMeta: options.sharedFolderMeta,
-          sidebar: options.navigation.sidebar.items,
-          // No locale to prefer: a per-locale label map resolves to its first
-          // entry on a single-locale site.
-          tabs: resolveTabLabels(options.navigation.tabs, ""),
-        }),
-        navigationByLocale: {} as Record<string, Navigation>,
-      };
+  // Under versioning, each version gets independent trees: navPath is
+  // version-stripped, so mixing versions into one build would collide the
+  // same logical page once per version.
+  const currentPages = options.versions
+    ? pages.filter((page) => page.version === "")
+    : pages;
+
+  // A single-locale site has no per-locale trees; the empty map is its
+  // navigationByLocale.
+  let navigationByLocale: Record<string, Navigation> = {};
+  let navigation: Navigation;
+  if (i18n) {
+    ({ navigation, navigationByLocale } = buildI18nNavigation(
+      currentPages,
+      options,
+      i18n,
+      diagnostics
+    ));
+  } else {
+    navigation = buildNavigation(currentPages, {
+      basePath: options.basePath ?? "",
+      diagnostics,
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
+      folderMeta: options.folderMeta,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sidebar: options.navigation.sidebar.items,
+      // No locale to prefer: a per-locale label map resolves to its first
+      // entry on a single-locale site.
+      tabs: resolveTabLabels(options.navigation.tabs, ""),
+    });
+  }
+
+  const navigationByVersion: Record<string, Record<string, Navigation>> = {};
+  for (const { id } of options.versions?.archived ?? []) {
+    navigationByVersion[id] = buildVersionNavigation(
+      id,
+      pages.filter((page) => page.version === id),
+      options,
+      diagnostics
+    );
+  }
 
   // Icon typos, duplicate labels, and hidden-page-in-sidebar are validated on
   // the built navigation. Missing-target detection needs the full route set
   // (incl. custom + generated pages), so it runs later in generateRuntime.
   diagnostics.push(
     ...validateNavIcons(navigation),
-    ...validateNavStructure(navigation, pages)
+    ...validateNavStructure(navigation, currentPages)
   );
 
   return {
     diagnostics,
     navigation,
     navigationByLocale,
+    navigationByVersion,
     pages,
     routes,
   };

package/src/core/i18n-ui.ts

@@ -123,6 +123,7 @@ const uiStringsObject = z.object({
     .object({
       all: z.string().default("All"),
       allLanguages: z.string().default("All languages"),
+      allVersions: z.string().default("All versions"),
       askAi: z.string().default("Ask AI"),
       askAiHint: z.string().default("Get an instant answer from AI"),
       button: z.string().default("Search"),
@@ -145,6 +146,18 @@ const uiStringsObject = z.object({
       title: z.string().default("On this page"),
     })
     .prefault({}),
+  versions: z
+    .object({
+      latest: z.string().default("Go to latest"),
+      // `{version}` is replaced with the archived version's label at render time.
+      notice: z
+        .string()
+        .default(
+          "You're viewing documentation for {version}. It may be out of date."
+        ),
+      switcher: z.string().default("Version"),
+    })
+    .prefault({}),
 });
 
 export const uiStringsSchema = uiStringsObject.prefault({});
@@ -186,6 +199,8 @@ const mergeUI = (base: UIStrings, override?: UIStringsOverride): UIStrings => {
   }
   const out: UIStrings = structuredClone(base);
   for (const [group, values] of Object.entries(override)) {
+    // SAFETY: UIStrings is exactly two levels of string leaves, and the
+    // override schema mirrors its groups, so `group` indexes a string map.
     const target = (out as Record<string, Record<string, string>>)[group];
     if (target && values) {
       Object.assign(target, values);