create-zudo-doc 0.2.0-next.9 → 0.2.1

package/dist/api.js

@@ -1,8 +1,11 @@
 import path from "path";
 import { scaffold } from "./scaffold.js";
-import { installDependencies } from "./utils.js";
+import { installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
     const { install = false, ...rest } = options;
+    const nameError = validateProjectName(rest.projectName);
+    if (nameError)
+        throw new Error(`Invalid projectName: ${nameError}`);
     const choices = { ...rest, defaultLang: rest.defaultLang ?? "en" };
     await scaffold(choices);
     const targetDir = path.resolve(process.cwd(), choices.projectName);

package/dist/cli.js

@@ -1,6 +1,7 @@
 import minimist from "minimist";
 import pc from "picocolors";
 import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+import { validateProjectName } from "./utils.js";
 export function parseArgs(argv = process.argv.slice(2)) {
     const raw = minimist(argv, {
         string: [
@@ -146,12 +147,9 @@ export function validateArgs(args) {
         return `--scheme is only valid with --color-scheme-mode single`;
     }
     if (args.name) {
-        if (/^[./]|\.\./.test(args.name)) {
-            return "Project name must not contain path traversal characters";
-        }
-        if (/[<>:"|?*\\]/.test(args.name)) {
-            return "Project name contains invalid characters";
-        }
+        const nameError = validateProjectName(args.name);
+        if (nameError)
+            return nameError;
     }
     return null;
 }

package/dist/preset.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+import { validateProjectName } from "./utils.js";
 const VALID_HEADER_RIGHT_COMPONENTS = new Set([
     "theme-toggle",
     "language-switcher",
@@ -34,6 +35,16 @@ export function validatePreset(json) {
         return "Preset must be a JSON object";
     }
     const p = json;
+    if (p.projectName !== undefined) {
+        // Untyped JSON — guard the type before the string validator, otherwise
+        // RegExp.test would coerce numbers/booleans and could accept them.
+        if (typeof p.projectName !== "string") {
+            return "Invalid projectName: must be a string";
+        }
+        const nameError = validateProjectName(p.projectName);
+        if (nameError)
+            return `Invalid projectName: ${nameError}`;
+    }
     if (p.features !== undefined && !Array.isArray(p.features)) {
         return `"features" must be an array in preset`;
     }

package/dist/prompts.js

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { LIGHT_DARK_PAIRINGS, SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS } from "./constants.js";
+import { validateProjectName } from "./utils.js";
 export async function runPrompts(prefilled = {}) {
     // 1. Project name
     let projectName;
@@ -12,12 +13,7 @@ export async function runPrompts(prefilled = {}) {
             placeholder: "my-docs",
             defaultValue: "my-docs",
             validate(value) {
-                if (!value.trim())
-                    return "Project name is required";
-                if (/^[./]|\.\./.test(value))
-                    return "Project name must not contain path traversal characters";
-                if (/[<>:"|?*\\]/.test(value))
-                    return "Project name contains invalid characters";
+                return validateProjectName(value) ?? undefined;
             },
         });
         if (p.isCancel(result))

package/dist/scaffold.js

@@ -264,16 +264,21 @@ function generatePackageJson(choices) {
         // next.35 fixes resolve_links rewriting bare same-page `[text](#anchor)` /
         // `[text](?query)` links to `/<parent-dir>/#anchor` (zudolab/zudo-doc#1948,
         // upstream Takazudo/zudo-front-builder#875).
-        "@takazudo/zfb": "0.1.0-next.35",
-        "@takazudo/zfb-runtime": "0.1.0-next.35",
+        // next.38 adds client scripts (`.client.*` + `clientScript()`), the
+        // `when="media"` island strategy, exported VNode types, and stricter
+        // cross-file anchor validation. BREAKING upstream: the no-op
+        // `linkValidation.allowExternal` knob was removed — neither the host nor
+        // the generated config ever emitted it, so no migration is needed here.
+        "@takazudo/zfb": "0.1.0-next.38",
+        "@takazudo/zfb-runtime": "0.1.0-next.38",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.35",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.38",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
         // version moves, so a fresh scaffold pulls the version we just published.
-        "@takazudo/zudo-doc": "^0.2.0-next.9",
+        "@takazudo/zudo-doc": "^0.2.1",
         // zod — used by the generated zfb.config.ts. zfb-config-gen emits
         // `import { z } from "zod"` for the content-collection schema +
         // `z.toJSONSchema(...)` conversion. Without this dep, the consumer
@@ -297,11 +302,9 @@ function generatePackageJson(choices) {
         "@shikijs/transformers": "^4.0.0",
         clsx: "^2.1.0",
         "gray-matter": "^4.0.0",
-        "github-slugger": "^2.0.0",
         mermaid: "^11.12.3",
         "remark-cjk-friendly": "^2.0.1",
         "remark-directive": "^3.0.0",
-        "unist-util-visit": "^5.1.0",
         // katex — server-side LaTeX renderer used by the always-on
         // pages/lib/_math-block.tsx (called from pages/_mdx-components.ts
         // for `$…$` and `$$…$$` math nodes). Caught by W6B (#1735)
@@ -313,8 +316,6 @@ function generatePackageJson(choices) {
         "@tailwindcss/vite": "^4.2.0",
         tailwindcss: "^4.2.0",
         typescript: "^5.9.0",
-        "@types/hast": "^3.0.4",
-        "@types/mdast": "^4.0.4",
         "@types/node": "^22.0.0",
         "@types/react": "^19.2.0", // needed for preact/compat type resolution
         "html-validate": "^10.0.0",
@@ -331,7 +332,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.9";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.1";
         // W7A (#1736): doc-history-plugin.mjs spawns `tsx -e <inline-script>` to
         // run the v2 runtime in a TS-aware Node subprocess; without tsx the
         // plugin's preBuild step exits with ENOENT before zfb finishes config
@@ -363,6 +364,11 @@ function generatePackageJson(choices) {
         build: "zfb build",
         preview: "zfb preview",
         check: "zfb check",
+        // NOTE: no `check:pages` here — the host repo's pages/ typecheck
+        // (tsconfig.pages.json, #2018) is host-only for now. The base template's
+        // no-op feature stubs (e.g. doc-history.tsx) are not type-clean against
+        // the pages/lib call sites, so emitting the script would fail on a fresh
+        // scaffold. Revisit once the template stubs carry typed props.
         "check:html": "html-validate \"dist/**/*.html\"",
     };
     if (choices.features.includes("tagGovernance")) {

package/dist/settings-gen.js

@@ -43,7 +43,7 @@ export function generateSettingsFile(choices) {
         lines.push(`    lightScheme: ${JSON.stringify(choices.lightScheme ?? "GitHub Light")},`);
         lines.push(`    darkScheme: ${JSON.stringify(choices.darkScheme ?? "GitHub Dark")},`);
         lines.push(`    respectPrefersColorScheme: ${choices.respectPrefersColorScheme ?? true},`);
-        lines.push(`  } satisfies ColorModeConfig,`);
+        lines.push(`  } satisfies ColorModeConfig as ColorModeConfig | false,`);
     }
     lines.push(`  siteName: ${JSON.stringify(capitalize(choices.projectName.replace(/-/g, " ")))},`);
     lines.push(`  siteDescription: "" as string,`);
@@ -60,16 +60,16 @@ export function generateSettingsFile(choices) {
     }
     lines.push(`  siteUrl: "" as string,`);
     lines.push(`  docsDir: "src/content/docs",`);
-    lines.push(`  defaultLocale: ${JSON.stringify(choices.defaultLang ?? "en")} as string,`);
+    lines.push(`  defaultLocale: ${JSON.stringify(choices.defaultLang ?? "en")} as const,`);
     if (choices.features.includes("i18n")) {
         const secondaryLang = getSecondaryLang(choices.defaultLang);
         const secondaryLabel = getLangLabel(secondaryLang);
         lines.push(`  locales: {`);
         lines.push(`    ${secondaryLang}: { label: ${JSON.stringify(secondaryLabel)}, dir: "src/content/docs-${secondaryLang}" },`);
-        lines.push(`  } as Record<string, LocaleConfig>,`);
+        lines.push(`  } satisfies Record<string, LocaleConfig>,`);
     }
     else {
-        lines.push(`  locales: {} as Record<string, LocaleConfig>,`);
+        lines.push(`  locales: {} satisfies Record<string, LocaleConfig>,`);
     }
     // mermaid is controlled by the markdown.features block in zfb.config.ts
     // (zfb next.12+). This field is retained for compatibility with framework
@@ -159,7 +159,7 @@ export function generateSettingsFile(choices) {
     }
     lines.push(`  htmlPreview: undefined as HtmlPreviewConfig | undefined,`);
     if (choices.features.includes("versioning")) {
-        lines.push(`  versions: [] as VersionConfig[],`);
+        lines.push(`  versions: [] satisfies VersionConfig[] as VersionConfig[] | false,`);
     }
     else {
         lines.push(`  versions: false as VersionConfig[] | false,`);
@@ -219,7 +219,7 @@ export function generateSettingsFile(choices) {
     if (choices.features.includes("changelog")) {
         lines.push(`    { label: "Changelog", path: "/docs/changelog", categoryMatch: "changelog" },`);
     }
-    lines.push(`  ] as HeaderNavItem[],`);
+    lines.push(`  ] satisfies HeaderNavItem[] as HeaderNavItem[],`);
     lines.push(`  headerRightItems: [`);
     if (choices.headerRightItems !== undefined) {
         // User-supplied override (including empty array): emit each entry verbatim,
@@ -250,7 +250,7 @@ export function generateSettingsFile(choices) {
             lines.push(`    { type: "component", component: "language-switcher" },`);
         }
     }
-    lines.push(`  ] as HeaderRightItem[],`);
+    lines.push(`  ] satisfies HeaderRightItem[] as HeaderRightItem[],`);
     lines.push(`};`);
     return lines.join("\n") + "\n";
 }

package/dist/utils.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Validate a project name against the locked grammar.
+ *
+ * Returns `null` when valid; a human-readable error string when invalid.
+ * Apply on every input path: CLI arg, interactive prompt, preset, and
+ * programmatic API.
+ */
+export declare function validateProjectName(name: string): string | null;
 export declare function installDependencies(dir: string, pm: string): void;
 export declare function capitalize(str: string): string;
 /** Get a short uppercase label for a language code (e.g. "en" → "EN", "zh-cn" → "ZH-CN"). */

package/dist/utils.js

@@ -1,5 +1,30 @@
 import { execSync } from "child_process";
 import fs from "fs-extra";
+// Project-name grammar (locked by F4 — S4 #2013):
+// /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped, used as both directory
+// name and package name. Mirrors npm's unscoped-name rules + max path safety.
+const PROJECT_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const PROJECT_NAME_MAX = 214;
+/**
+ * Validate a project name against the locked grammar.
+ *
+ * Returns `null` when valid; a human-readable error string when invalid.
+ * Apply on every input path: CLI arg, interactive prompt, preset, and
+ * programmatic API.
+ */
+export function validateProjectName(name) {
+    if (!name || name.length === 0) {
+        return "Project name is required";
+    }
+    if (name.length > PROJECT_NAME_MAX) {
+        return `Project name must be ${PROJECT_NAME_MAX} characters or fewer`;
+    }
+    if (!PROJECT_NAME_RE.test(name)) {
+        return ("Project name must start with a lowercase letter or digit and contain " +
+            "only lowercase letters, digits, dots, underscores, and hyphens");
+    }
+    return null;
+}
 export function installDependencies(dir, pm) {
     const commands = {
         pnpm: "pnpm install",

package/dist/zfb-config-gen.js

@@ -19,62 +19,20 @@ export function generateZfbConfig(choices) {
     const hasDocHistory = choices.features.includes("docHistory");
     const hasLlmsTxt = choices.features.includes("llmsTxt");
     const hasClaudeResources = choices.features.includes("claudeResources");
-    const hasTagGovernance = choices.features.includes("tagGovernance");
     const lines = [];
     // --- Imports ---
     lines.push(`import { z } from "zod";`);
     lines.push(`import { defineConfig } from "zfb/config";`);
     lines.push(`import { settings } from "./src/config/settings";`);
-    if (hasTagGovernance) {
-        lines.push(`import { tagVocabulary } from "./src/config/tag-vocabulary";`);
-    }
+    lines.push(`import { buildDocsSchema } from "./src/config/docs-schema";`);
     lines.push(``);
-    // --- Tags schema builder (only when tagGovernance is selected) ---
-    if (hasTagGovernance) {
-        lines.push(`function buildTagsSchema() {`);
-        lines.push(`  const vocabularyActive = settings.tagVocabulary && settings.tagGovernance === "strict";`);
-        lines.push(`  if (!vocabularyActive) return z.array(z.string()).optional();`);
-        lines.push(`  const allowed = new Set<string>();`);
-        lines.push(`  for (const entry of tagVocabulary) {`);
-        lines.push(`    allowed.add(entry.id);`);
-        lines.push(`    for (const alias of entry.aliases ?? []) allowed.add(alias);`);
-        lines.push(`  }`);
-        lines.push(`  const allowedList = [...allowed];`);
-        lines.push(`  if (allowedList.length === 0) return z.array(z.string()).optional();`);
-        lines.push(`  const [first, ...rest] = allowedList;`);
-        lines.push(`  return z.array(z.enum([first, ...rest] as [string, ...string[]])).optional();`);
-        lines.push(`}`);
-        lines.push(``);
-    }
-    // --- Schema definition ---
-    lines.push(`const docsSchema = z`);
-    lines.push(`  .object({`);
-    lines.push(`    title: z.string(),`);
-    lines.push(`    description: z.string().optional(),`);
-    lines.push(`    category: z.string().optional(),`);
-    lines.push(`    sidebar_position: z.number().optional(),`);
-    lines.push(`    sidebar_label: z.string().optional(),`);
-    if (hasTagGovernance) {
-        lines.push(`    tags: buildTagsSchema(),`);
-    }
-    else {
-        lines.push(`    tags: z.array(z.string()).optional(),`);
-    }
-    lines.push(`    search_exclude: z.boolean().optional(),`);
-    lines.push(`    pagination_next: z.string().nullable().optional(),`);
-    lines.push(`    pagination_prev: z.string().nullable().optional(),`);
-    lines.push(`    draft: z.boolean().optional(),`);
-    lines.push(`    unlisted: z.boolean().optional(),`);
-    lines.push(`    hide_sidebar: z.boolean().optional(),`);
-    lines.push(`    hide_toc: z.boolean().optional(),`);
-    lines.push(`    doc_history: z.boolean().optional(),`);
-    lines.push(`    standalone: z.boolean().optional(),`);
-    lines.push(`    slug: z.string().optional(),`);
-    lines.push(`    generated: z.boolean().optional(),`);
-    lines.push(`    category_no_page: z.boolean().optional(),`);
-    lines.push(`    category_sort_order: z.enum(["asc", "desc"]).optional(),`);
-    lines.push(`  })`);
-    lines.push(`  .passthrough();`);
+    // --- Schema definition — delegated to the single source of truth ---
+    // buildDocsSchema() lives in src/config/docs-schema.ts and is shared by
+    // pages/_data.ts (ZfbDocsData alias) and src/types/docs-entry.ts (DocsData).
+    // tagGovernance projects: docs-schema.ts reads settings + tagVocabulary
+    // internally, so the generated zfb.config.ts needs no extra import or
+    // inline buildTagsSchema — the schema builder encapsulates all of that.
+    lines.push(`const docsSchema = buildDocsSchema();`);
     lines.push(``);
     lines.push(`const docsSchemaJson = z.toJSONSchema(docsSchema) as Record<string, unknown>;`);
     lines.push(``);
@@ -203,6 +161,9 @@ export function generateZfbConfig(choices) {
     // --- Export ---
     lines.push(`export default defineConfig({`);
     lines.push(`  framework: "preact",`);
+    lines.push(`  // Pin the dev/preview port — zfb defaults to 3000, but the generated`);
+    lines.push(`  // CLAUDE.md and the Tauri dev wrappers assume 4321.`);
+    lines.push(`  port: 4321,`);
     lines.push(`  tailwind: { enabled: true },`);
     lines.push(`  collections,`);
     lines.push(`  stripMdExt: true,`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.0-next.9",
+  "version": "0.2.1",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/_data.ts

@@ -12,6 +12,7 @@
 
 import { getCollection } from "zfb/content";
 import type { CollectionEntry } from "zfb/content";
+import type { DocsData } from "@/config/docs-schema";
 import type { DocsEntry } from "@/types/docs-entry";
 import type { DocPageEntry } from "./lib/doc-page-props";
 import { toRouteSlug } from "@/utils/slug";
@@ -22,30 +23,16 @@ import { toRouteSlug } from "@/utils/slug";
 
 /**
  * Frontmatter shape shared by all docs collections (EN, locale, versioned).
- * Matches the zod schema in zfb.config.ts field-for-field.
- * `.passthrough()` equivalent: the index signature [key: string]: unknown
- * keeps custom frontmatter keys available (e.g. for frontmatter-preview).
+ *
+ * Re-exported alias for `DocsData` (the `z.infer`-derived type from
+ * `src/config/docs-schema.ts`) so call sites that import `ZfbDocsData` from
+ * `pages/_data` continue to work without changes.
+ *
+ * The `[key: string]: unknown` index signature comes from `.passthrough()` on
+ * the zod schema — custom frontmatter keys remain accessible downstream (e.g.
+ * for frontmatter-preview) without extra casting.
  */
-export type ZfbDocsData = {
-  title: string;
-  description?: string;
-  category?: string;
-  sidebar_position?: number;
-  sidebar_label?: string;
-  tags?: string[];
-  search_exclude?: boolean;
-  pagination_next?: string | null;
-  pagination_prev?: string | null;
-  draft?: boolean;
-  unlisted?: boolean;
-  hide_sidebar?: boolean;
-  hide_toc?: boolean;
-  doc_history?: boolean;
-  standalone?: boolean;
-  slug?: string;
-  generated?: boolean;
-  [key: string]: unknown;
-};
+export type ZfbDocsData = DocsData;
 
 /**
  * zfb collection entry augmented with the `id` and `collection` fields that

package/templates/base/pages/docs/[[...slug]].tsx

@@ -21,33 +21,19 @@
 //
 // Locale: defaultLocale (EN). Non-default locales are handled by
 // pages/[locale]/docs/[[...slug]].tsx.
+//
+// Enumeration + per-entry derived data (breadcrumbs, prev/next, headings) are
+// built by the shared, memoized buildDocRouteEntries (#2010); rendering by the
+// shared renderDocPage. This file owns only the route's nav source and the
+// param/prop shapes.
 
 import { settings } from "@/config/settings";
 import { defaultLocale } from "@/config/i18n";
-import { docsUrl, absoluteUrl } from "@/utils/base";
-import {
-  buildNavTree,
-  buildBreadcrumbs,
-  collectAutoIndexNodes,
-  type NavNode,
-} from "@/utils/docs";
-import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
-import { toRouteSlug, toSlugParams } from "@/utils/slug";
-// Shared MDX-tag → Preact-component bag. Includes htmlOverrides
-// (native typography), HtmlPreviewWrapper (Island), and stub bindings
-// for every other custom tag the MDX corpus references — see
-// `pages/_mdx-components.ts` for the full list and rationale.
-import { createMdxComponents } from "../_mdx-components";
-import { DocHistoryArea } from "../lib/_doc-history-area";
-import { DocMetainfoArea } from "../lib/_doc-metainfo-area";
-import { buildInlineVersionSwitcher } from "../lib/_inline-version-switcher";
 import type { JSX } from "preact";
 import { resolveNavSource } from "../lib/_nav-source-docs";
-import { extractHeadings } from "../lib/_extract-headings";
-import type { DocPageEntry, AutoIndexNode, DocPageEntryProps, DocPageAutoIndexProps } from "../lib/doc-page-props";
-import { DocContentHeader } from "../lib/_doc-content-header";
-import { DocPageShell } from "../lib/_doc-page-shell";
-import { resolveDocPrevNext, flattenSubtree } from "../lib/_doc-route-paths";
+import type { DocPageEntryProps, DocPageAutoIndexProps } from "../lib/doc-page-props";
+import { buildDocRouteEntries } from "../lib/_doc-route-entries";
+import { renderDocPage } from "../lib/_doc-page-renderer";
 
 export const frontmatter = { title: "Docs" };
 
@@ -55,8 +41,6 @@ export const frontmatter = { title: "Docs" };
 // Props contract
 // ---------------------------------------------------------------------------
 
-// DocPageEntry, AutoIndexNode imported from pages/lib/doc-page-props.ts
-
 type DocPageProps = DocPageEntryProps | DocPageAutoIndexProps;
 
 // ---------------------------------------------------------------------------
@@ -67,8 +51,8 @@ type DocPageProps = DocPageEntryProps | DocPageAutoIndexProps;
  * Enumerate all doc routes for the default locale (EN).
  *
  * Synchronous per ADR-004: getCollection() resolves from the pre-loaded
- * ContentSnapshot. All nav-tree and breadcrumb computation is done here
- * so the component is a pure renderer.
+ * ContentSnapshot. All nav-tree and breadcrumb computation is done in the
+ * shared builder so the component is a pure renderer.
  */
 export function paths(): Array<{
   params: { slug: string[] };
@@ -77,66 +61,19 @@ export function paths(): Array<{
   const locale = defaultLocale;
   // Identity-stable nav source (draft-filtered, unlisted retained). The same
   // instances are returned across this route's many per-page paths()
-  // invocations, so buildNavTree's identity fast-path skips the key
-  // recomputation — see pages/lib/_nav-source-docs.ts (#1902).
-  const { docs, navDocs, categoryMeta } = resolveNavSource(locale, undefined);
-
-  // Nav docs: exclude unlisted (for sidebar/prev-next) but keep for breadcrumbs
-  const tree = buildNavTree(navDocs, locale, categoryMeta);
-  // Full tree (including unlisted) for accurate breadcrumbs
-  const fullTree = buildNavTree(docs, locale, categoryMeta);
-
-  const result: Array<{ params: { slug: string[] }; props: DocPageProps }> = [];
-
-  // Regular doc pages
-  for (const entry of docs) {
-    // A `category_no_page` index.mdx carries category metadata only — keep it
-    // in the nav tree (built above, used for breadcrumbs) but emit NO route for
-    // it. zfb's walker retains every .mdx as a collection entry, so without
-    // this explicit skip the metadata file would silently add a route.
-    if (entry.data.category_no_page === true) continue;
-    const slug = entry.data.slug ?? toRouteSlug(entry.slug);
-    const navSection = getNavSectionForSlug(slug);
-    const subtree = getNavSubtree(tree, navSection);
-
-    // Prev/next + frontmatter pagination overrides resolved against THIS
-    // route's own `tree`. Latest route — hrefs stay unversioned (no rewrite).
-    const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
-      tree,
-      flattenSubtree(subtree),
-      slug,
-      entry.data,
-    );
-
-    result.push({
-      params: { slug: toSlugParams(slug) },
-      props: {
-        kind: "entry",
-        entry,
-        breadcrumbs: buildBreadcrumbs(fullTree, slug, locale),
-        prev: prevNode,
-        next: nextNode,
-        headings: extractHeadings(entry.body ?? ""),
-      },
-    });
-  }
-
-  // Auto-generated index pages for categories without index.mdx
-  for (const node of collectAutoIndexNodes(tree)) {
-    result.push({
-      params: { slug: toSlugParams(node.slug) },
-      props: {
-        kind: "autoIndex",
-        autoIndex: node as AutoIndexNode,
-        breadcrumbs: buildBreadcrumbs(fullTree, node.slug, locale),
-        prev: null,
-        next: null,
-        headings: [],
-      },
-    });
-  }
-
-  return result;
+  // invocations, so both buildNavTree's identity fast-path and the
+  // buildDocRouteEntries memo key on them — see pages/lib/_nav-source-docs.ts
+  // (#1902).
+  const source = resolveNavSource(locale, undefined);
+
+  return buildDocRouteEntries({
+    source,
+    locale,
+    routeSig: `docs;${locale}`,
+  }).map((item) => ({
+    params: { slug: item.slugParams },
+    props: item.props,
+  }));
 }
 
 // ---------------------------------------------------------------------------
@@ -146,86 +83,8 @@ export function paths(): Array<{
 type PageArgs = DocPageProps & { params: { slug: string[] } };
 
 export default function DocsPage(props: PageArgs): JSX.Element {
-  const { breadcrumbs, prev, next, headings } = props;
-  const locale = defaultLocale;
-
-  const slug = props.kind === "autoIndex"
-    ? props.autoIndex.slug
-    : (props.entry.data.slug ?? toRouteSlug(props.entry.slug));
-
-  const title = props.kind === "autoIndex" ? props.autoIndex.label : props.entry.data.title;
-  const description = props.kind === "autoIndex" ? props.autoIndex.description : props.entry.data.description;
-
-  // Locale-aware components bag — creates nav wrappers bound to the active
-  // locale so CategoryNav/CategoryTreeNav/SiteTreeNav query the right collection.
-  const components = createMdxComponents(locale);
-
-  // Resolve child hrefs for auto-index pages — latest route keeps the nav
-  // node's own docsUrl href (fallback for a noPage parent without an href).
-  const autoIndexChildren = props.kind === "autoIndex"
-    ? props.autoIndex.children
-        .filter((c: NavNode) => c.hasPage || c.children.length > 0)
-        .map((c: NavNode) => ({
-          ...c,
-          href: c.href ?? docsUrl(c.slug, locale),
-        }))
-    : [];
-
-  // Canonical URL — base-prefixed page path, absolutized against siteUrl.
-  const currentPath = docsUrl(slug, locale);
-  const canonical = absoluteUrl(currentPath);
-
-  // Persist key: locale + nav-section so the sidebar DOM node is reused
-  // across same-locale + same-section navigations only. No sanitizer needed —
-  // both lang (BCP-47 locale string) and navSection (filesystem-derived
-  // kebab-case slug) come from controlled, trusted sources.
-  const navSection = getNavSectionForSlug(slug);
-  const hideSidebar = props.kind === "entry" ? props.entry.data.hide_sidebar : undefined;
-  const sidebarPersistKey = hideSidebar
-    ? undefined
-    : `sidebar-${locale}-${navSection ?? "default"}`;
-
-  return (
-    <DocPageShell
-      kind={props.kind}
-      locale={locale}
-      slug={slug}
-      title={title}
-      description={description}
-      canonical={canonical}
-      breadcrumbs={breadcrumbs}
-      prev={prev}
-      next={next}
-      headings={headings}
-      navSection={navSection}
-      sidebarPersistKey={sidebarPersistKey}
-      hideSidebar={hideSidebar}
-      hideToc={props.kind === "entry" ? props.entry.data.hide_toc : undefined}
-      currentPath={currentPath}
-      versionSwitcher={buildInlineVersionSwitcher(slug, locale)}
-      autoIndexLabel={props.kind === "autoIndex" ? props.autoIndex.label : undefined}
-      autoIndexChildren={autoIndexChildren}
-      metainfoSlot={
-        props.kind === "autoIndex" ? <DocMetainfoArea slug={slug} locale={locale} /> : null
-      }
-      contentHeaderSlot={
-        props.kind === "entry" ? (
-          <DocContentHeader entry={props.entry} slug={slug} locale={locale} />
-        ) : undefined
-      }
-      contentSlot={
-        props.kind === "entry" ? <props.entry.Content components={components} /> : undefined
-      }
-      docHistorySlot={
-        props.kind === "entry" && !props.entry.data.unlisted ? (
-          <DocHistoryArea
-            slug={slug}
-            locale={locale}
-            entrySlug={props.entry.slug}
-            contentDir={settings.docsDir}
-          />
-        ) : null
-      }
-    />
-  );
+  return renderDocPage(props, {
+    locale: defaultLocale,
+    docHistoryContentDir: settings.docsDir,
+  });
 }