create-zudo-doc 0.2.0 → 0.2.1

package/templates/features/i18n/files/pages/[locale]/index.tsx

@@ -16,7 +16,7 @@
 //   → collectTags()    → tag section
 
 import { settings } from "@/config/settings";
-import { t } from "@/config/i18n";
+import { t, getLocaleConfig, type Locale } from "@/config/i18n";
 import { withBase } from "@/utils/base";
 import {
   buildNavTree,
@@ -71,16 +71,16 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
   // instance). categoryMeta is intentionally locale-dir-only here — this page
   // historically did NOT merge in base meta (unlike the locale doc route), so
   // we keep that exact behavior to preserve output.
-  const { navDocs } = resolveNavSource(locale, undefined, {
+  const { navDocs } = resolveNavSource(locale as Locale, undefined, {
     applyDefaultLocaleOnlyFilter: true,
     keepUnlisted: true,
   });
-  const localeConfig = settings.locales[locale];
+  const localeConfig = getLocaleConfig(locale);
   const categoryMeta = localeConfig
     ? loadCategoryMeta(localeConfig.dir)
     : loadCategoryMeta(settings.docsDir);
 
-  const tree = buildNavTree(navDocs, locale, categoryMeta);
+  const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
   const categoryOrder = getCategoryOrder();
   const groupedTree = groupSatelliteNodes(tree, categoryOrder);
 
@@ -103,7 +103,7 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
-      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/`)} />}
+      headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`/${locale}/`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
     >

package/templates/features/llmsTxt/files/plugins/llms-txt-plugin.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // zfb plugin module: llms-txt.
 //
 // Wires two lifecycle hooks for the llms-txt integration:
@@ -20,35 +21,35 @@
 // Inline functions are not supported by zfb's plugin runtime; see the
 // sibling `doc-history-plugin.mjs` for the rationale.
 
+/** @import { ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
+/** @import { LlmsTxtEmitOptions, LlmsTxtDevMiddlewareOptions } from "@takazudo/zudo-doc/integrations/llms-txt" */
+
 import { emitLlmsTxt, createLlmsTxtDevMiddleware } from "@takazudo/zudo-doc/integrations/llms-txt";
 import { connectToZfbHandler } from "./connect-adapter.mjs";
 
+/** @type {ZfbPlugin} */
 export default {
   name: "llms-txt",
 
+  /** @param {ZfbBuildHookContext} ctx */
   postBuild(ctx) {
-    const {
-      siteName,
-      siteDescription,
-      base,
-      siteUrl,
-      defaultLocaleDir,
-      locales,
-    } = ctx.options;
-    emitLlmsTxt({
+    emitLlmsTxt(/** @type {LlmsTxtEmitOptions} */ (/** @type {unknown} */ ({
+      ...ctx.options,
       outDir: ctx.outDir,
-      siteName,
-      siteDescription,
-      base,
-      siteUrl: siteUrl || undefined,
-      defaultLocaleDir,
-      locales,
+      // siteUrl is normalised to undefined when falsy because the runner
+      // switches between absolute and root-relative URLs based on its
+      // presence (matches legacy Astro behaviour).
+      siteUrl: ctx.options["siteUrl"] || undefined,
       logger: ctx.logger,
-    });
+    })));
   },
 
+  /** @param {ZfbDevMiddlewareContext} ctx */
   devMiddleware(ctx) {
-    const middleware = createLlmsTxtDevMiddleware(ctx.options, ctx.logger);
+    const middleware = createLlmsTxtDevMiddleware(
+      /** @type {LlmsTxtDevMiddlewareOptions} */ (/** @type {unknown} */ (ctx.options)),
+      ctx.logger,
+    );
     const handler = connectToZfbHandler(middleware);
 
     // zfb's `register(path, handler)` matches against the FULL request
@@ -58,16 +59,27 @@ export default {
     // empty and routes are `/llms.txt` etc. as expected. The middleware
     // accepts base-prefixed URLs via the matcher (see `matchLlmsRoute`
     // in `dev-middleware.ts`).
-    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    const basePrefix = stripTrailingSlash(
+      typeof ctx.options["base"] === "string" ? ctx.options["base"] : "",
+    );
     ctx.register(`${basePrefix}/llms.txt`, handler);
     ctx.register(`${basePrefix}/llms-full.txt`, handler);
-    for (const locale of ctx.options.locales ?? []) {
-      ctx.register(`${basePrefix}/${locale.code}/llms.txt`, handler);
-      ctx.register(`${basePrefix}/${locale.code}/llms-full.txt`, handler);
+    const locales = ctx.options["locales"];
+    if (Array.isArray(locales)) {
+      for (const locale of locales) {
+        if (locale && typeof locale === "object" && typeof locale.code === "string") {
+          ctx.register(`${basePrefix}/${locale.code}/llms.txt`, handler);
+          ctx.register(`${basePrefix}/${locale.code}/llms-full.txt`, handler);
+        }
+      }
     }
   },
 };
 
+/**
+ * @param {string} s
+ * @returns {string}
+ */
 function stripTrailingSlash(s) {
   if (typeof s !== "string" || s.length === 0) return "";
   return s.endsWith("/") ? s.slice(0, -1) : s;

package/templates/features/sidebarToggle/files/src/components/desktop-sidebar-toggle.tsx

@@ -29,7 +29,7 @@ export default function DesktopSidebarToggle() {
   // to <html> from localStorage *before* this island mounts, so the
   // visual state stays correct; we only need to sync this island's
   // React state to the persisted preference after hydration. Same
-  // pattern as src/components/theme-toggle.tsx (commit 9aebd8e).
+  // pattern as packages/zudo-doc/src/theme-toggle/index.tsx (commit 9aebd8e).
   const [visible, setVisible] = useState<boolean>(true);
   // Tracks whether the hydration sync (below) has run. The persistence
   // effect below skips the very first mount so we don't overwrite the

package/templates/features/versioning/files/pages/[locale]/docs/versions.tsx

@@ -6,22 +6,16 @@
 // settings.locales. Locale string is passed as a prop to drive label
 // translation in the component.
 //
+// Rendering is shared with the default-locale route via
+// pages/lib/_versions-page.tsx (#2010).
+//
 // paths() contract (zfb ADR-004 — synchronous):
 //   params: { locale: string }
 //   props:  { locale }
 
 import { settings } from "@/config/settings";
-import { t } from "@/config/i18n";
-import { withBase } from "@/utils/base";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { VersionsPageContent } from "@takazudo/zudo-doc/nav-indexing";
-import type { VersionPageEntry, VersionsPageLabels } from "@takazudo/zudo-doc/nav-indexing";
 import type { JSX } from "preact";
-import { FooterWithDefaults } from "../../lib/_footer-with-defaults";
-import { HeaderWithDefaults } from "../../lib/_header-with-defaults";
-import { HeadWithDefaults } from "../../lib/_head-with-defaults";
-import { composeMetaTitle } from "../../lib/_compose-meta-title";
-import { BodyEndIslands } from "../../lib/_body-end-islands";
+import { VersionsPageView } from "../../lib/_versions-page";
 
 export const frontmatter = { title: "Versions" };
 
@@ -50,53 +44,5 @@ interface PageArgs {
 }
 
 export default function LocaleVersionsPage({ params }: PageArgs): JSX.Element {
-  const locale = params.locale;
-  const pageTitle = t("version.page.title", locale);
-
-  const labels: VersionsPageLabels = {
-    pageTitle,
-    latestTitle: t("version.page.latest.title", locale),
-    latestDescription: t("version.page.latest.description", locale),
-    latestLink: t("version.page.latest.link", locale),
-    pastTitle: t("version.page.past.title", locale),
-    pastDescription: t("version.page.past.description", locale),
-    unmaintained: t("version.page.unmaintained", locale),
-    unreleased: t("version.page.unreleased", locale),
-    versionCol: t("version.switcher.label", locale),
-    statusCol: t("version.page.status", locale),
-    docsCol: t("version.page.docs", locale),
-  };
-
-  const latestHref = withBase(`/${locale}/docs/getting-started`);
-
-  const versions: VersionPageEntry[] = settings.versions
-    ? settings.versions.map((v) => ({
-        slug: v.slug,
-        label: v.label ?? v.slug,
-        // Version prefix comes BEFORE the locale — the only routed shape is
-        // pages/v/[version]/{locale}/docs/...; /{locale}/v/... has no route.
-        docsHref: withBase(`/v/${v.slug}/${locale}/docs/getting-started/`),
-        banner: v.banner as "unmaintained" | "unreleased" | undefined,
-      }))
-    : [];
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(pageTitle)}
-      head={<HeadWithDefaults title={pageTitle} />}
-      lang={locale}
-      noindex={settings.noindex}
-      hideSidebar={true}
-      hideToc={true}
-      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/docs/versions`)} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-    >
-      <VersionsPageContent
-        latestHref={latestHref}
-        versions={versions}
-        labels={labels}
-      />
-    </DocLayoutWithDefaults>
-  );
+  return <VersionsPageView locale={params.locale} />;
 }

package/templates/features/versioning/files/pages/docs/versions.tsx

@@ -2,77 +2,19 @@
 /** @jsxImportSource preact */
 // Page module for the default-locale versions index route.
 //
-// Default-locale (EN) documentation versions page. Static route — no
-// paths() export needed. Lists the latest version and any past versions
-// configured in settings.versions.
+// Default-locale documentation versions page. Static route — no paths()
+// export needed. Lists the latest version and any past versions configured
+// in settings.versions.
 //
-// Data flow:
-//   settings.versions          → build version entry list
-//   t() for locale strings     → labels bag passed to VersionsPageContent
+// Rendering is shared with the locale-prefixed route via
+// pages/lib/_versions-page.tsx (#2010).
 
-import { settings } from "@/config/settings";
-import { defaultLocale, t } from "@/config/i18n";
-import { withBase } from "@/utils/base";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { VersionsPageContent } from "@takazudo/zudo-doc/nav-indexing";
-import type { VersionPageEntry, VersionsPageLabels } from "@takazudo/zudo-doc/nav-indexing";
+import { defaultLocale } from "@/config/i18n";
 import type { JSX } from "preact";
-import { FooterWithDefaults } from "../lib/_footer-with-defaults";
-import { HeaderWithDefaults } from "../lib/_header-with-defaults";
-import { HeadWithDefaults } from "../lib/_head-with-defaults";
-import { composeMetaTitle } from "../lib/_compose-meta-title";
-import { BodyEndIslands } from "../lib/_body-end-islands";
+import { VersionsPageView } from "../lib/_versions-page";
 
 export const frontmatter = { title: "Versions" };
 
 export default function VersionsPage(): JSX.Element {
-  const locale = defaultLocale;
-  const pageTitle = t("version.page.title", locale);
-
-  const labels: VersionsPageLabels = {
-    pageTitle,
-    latestTitle: t("version.page.latest.title", locale),
-    latestDescription: t("version.page.latest.description", locale),
-    latestLink: t("version.page.latest.link", locale),
-    pastTitle: t("version.page.past.title", locale),
-    pastDescription: t("version.page.past.description", locale),
-    unmaintained: t("version.page.unmaintained", locale),
-    unreleased: t("version.page.unreleased", locale),
-    versionCol: t("version.switcher.label", locale),
-    statusCol: t("version.page.status", locale),
-    docsCol: t("version.page.docs", locale),
-  };
-
-  // Latest docs href — points to the default docs entry point
-  const latestHref = withBase("/docs/getting-started");
-
-  // Past version entries from settings
-  const versions: VersionPageEntry[] = settings.versions
-    ? settings.versions.map((v) => ({
-        slug: v.slug,
-        label: v.label ?? v.slug,
-        docsHref: withBase(`/v/${v.slug}/docs/getting-started/`),
-        banner: v.banner as "unmaintained" | "unreleased" | undefined,
-      }))
-    : [];
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(pageTitle)}
-      head={<HeadWithDefaults title={pageTitle} />}
-      lang={locale}
-      noindex={settings.noindex}
-      hideSidebar={true}
-      hideToc={true}
-      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/docs/versions")} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-    >
-      <VersionsPageContent
-        latestHref={latestHref}
-        versions={versions}
-        labels={labels}
-      />
-    </DocLayoutWithDefaults>
-  );
+  return <VersionsPageView locale={defaultLocale} />;
 }

package/templates/features/versioning/files/pages/lib/_versions-page.tsx

@@ -0,0 +1,79 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Shared renderer for the documentation-versions pages (#2010).
+//
+// Collapses the per-locale page pair:
+//   pages/docs/versions.tsx + pages/[locale]/docs/versions.tsx
+// into one locale-parameterized renderer. The page files stay thin shells
+// that own only their paths() param shapes; URL prefixes and the
+// default-vs-locale href shapes live here.
+
+import { settings } from "@/config/settings";
+import { defaultLocale, t, type Locale } from "@/config/i18n";
+import { withBase } from "@/utils/base";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { VersionsPageContent } from "@takazudo/zudo-doc/nav-indexing";
+import type { VersionPageEntry, VersionsPageLabels } from "@takazudo/zudo-doc/nav-indexing";
+import type { JSX } from "preact";
+import { FooterWithDefaults } from "./_footer-with-defaults";
+import { HeaderWithDefaults } from "./_header-with-defaults";
+import { HeadWithDefaults } from "./_head-with-defaults";
+import { composeMetaTitle } from "./_compose-meta-title";
+import { BodyEndIslands } from "./_body-end-islands";
+
+/** Versions index page for one locale. Lists the latest version and any past
+ *  versions configured in settings.versions. */
+export function VersionsPageView({ locale }: { locale: string }): JSX.Element {
+  const isDefault = locale === defaultLocale;
+  const prefix = isDefault ? "" : `/${locale}`;
+  const pageTitle = t("version.page.title", locale);
+
+  const labels: VersionsPageLabels = {
+    pageTitle,
+    latestTitle: t("version.page.latest.title", locale),
+    latestDescription: t("version.page.latest.description", locale),
+    latestLink: t("version.page.latest.link", locale),
+    pastTitle: t("version.page.past.title", locale),
+    pastDescription: t("version.page.past.description", locale),
+    unmaintained: t("version.page.unmaintained", locale),
+    unreleased: t("version.page.unreleased", locale),
+    versionCol: t("version.switcher.label", locale),
+    statusCol: t("version.page.status", locale),
+    docsCol: t("version.page.docs", locale),
+  };
+
+  // Latest docs href — points to the default docs entry point
+  const latestHref = withBase(`${prefix}/docs/getting-started`);
+
+  // Past version entries from settings
+  const versions: VersionPageEntry[] = settings.versions
+    ? settings.versions.map((v) => ({
+        slug: v.slug,
+        label: v.label ?? v.slug,
+        // Version prefix comes BEFORE the locale — the only routed shape is
+        // pages/v/[version]/{locale}/docs/...; /{locale}/v/... has no route.
+        docsHref: withBase(`/v/${v.slug}${prefix}/docs/getting-started/`),
+        banner: v.banner as "unmaintained" | "unreleased" | undefined,
+      }))
+    : [];
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`${prefix}/docs/versions`)} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <VersionsPageContent
+        latestHref={latestHref}
+        versions={versions}
+        labels={labels}
+      />
+    </DocLayoutWithDefaults>
+  );
+}

package/templates/features/versioning/files/pages/v/[version]/[locale]/docs/[[...slug]].tsx

@@ -19,30 +19,21 @@
 //
 // Prev/next hrefs are pre-resolved to the versioned locale URL form
 // (e.g. /v/1.0/ja/docs/…) so the component needs no URL computation.
+//
+// Enumeration + per-entry derived data are built by the shared, memoized
+// buildDocRouteEntries (#2010); rendering by the shared renderDocPage. This
+// file owns only the route's nav source, its versioned-locale URL closure,
+// and the param/prop shapes.
 
 import { settings } from "@/config/settings";
 import type { VersionConfig } from "@/config/settings";
-import { t } from "@/config/i18n";
-import { docsUrl, versionedDocsUrl, 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";
-// Locale-aware MDX components factory — see `pages/_mdx-components.ts`.
-import { createMdxComponents } from "../../../../_mdx-components";
+import { type Locale } from "@/config/i18n";
+import { versionedDocsUrl } from "@/utils/base";
 import type { JSX } from "preact";
 import { resolveVersionedLocaleSource } from "../../../../lib/_nav-source-docs";
-import { extractHeadings } from "../../../../lib/_extract-headings";
-import type { DocPageEntry, AutoIndexNode, DocPageEntryProps, DocPageAutoIndexProps } from "../../../../lib/doc-page-props";
-import { DocMetainfoArea } from "../../../../lib/_doc-metainfo-area";
-import { buildInlineVersionSwitcher } from "../../../../lib/_inline-version-switcher";
-import { DocContentHeader } from "../../../../lib/_doc-content-header";
-import { DocPageShell } from "../../../../lib/_doc-page-shell";
-import { resolveDocPrevNext, flattenSubtree, rewriteNavHref, remapNavChildHrefs } 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" };
 
@@ -50,8 +41,6 @@ export const frontmatter = { title: "Docs" };
 // Types
 // ---------------------------------------------------------------------------
 
-// DocPageEntry, AutoIndexNode imported from pages/lib/doc-page-props.ts
-
 /** Route-specific extra fields — present on both branches of the union. */
 interface VersionedLocaleDocPageExtra {
   /** The version config for the active version. */
@@ -102,87 +91,43 @@ export function paths(): Array<{
 
       // Identity-stable, locale-first merge over the version's EN base. Reused
       // across the route's per-page paths() invocations so buildNavTree's
-      // identity fast-path applies — see pages/lib/_nav-source-docs.ts (#1902).
-      const { docs: allDocs, navDocs, categoryMeta, localeSlugSet } =
-        resolveVersionedLocaleSource(version.slug, version.docsDir, locale, localeDir, {
-          applyDefaultLocaleOnlyFilter: true,
-          keepUnlisted: true,
-        });
-      // isFallback: page came from base docs, not the locale collection.
-      // toRouteSlug keeps Set keys and lookup keys in lockstep — a versioned
-      // root index has entry.slug="index" (storage form) but route slug="" so
-      // d.id would diverge from the lookup key after the #1891 toRouteSlug flip.
-      const fallbackSlugs = new Set(
-        allDocs
-          .filter((d) => !localeSlugSet.has(d.data.slug ?? toRouteSlug(d.slug)))
-          .map((d) => d.data.slug ?? toRouteSlug(d.slug)),
+      // identity fast-path and the buildDocRouteEntries memo apply — see
+      // pages/lib/_nav-source-docs.ts (#1902).
+      const source = resolveVersionedLocaleSource(
+        version.slug,
+        version.docsDir,
+        locale as Locale,
+        localeDir,
+        { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true },
       );
 
-      const tree = buildNavTree(navDocs, locale, categoryMeta);
-
       // URL closure for THIS (version, locale) — every versioned-locale href
       // (prev/next, breadcrumb crumbs, auto-index cards) is produced by this
       // single function bound to the version slug + locale, resolved against
-      // this route's own `tree` (#1916).
-      const urlFor = (s: string): string => versionedDocsUrl(s, version.slug, locale);
-
-      // Regular doc pages
-      for (const entry of allDocs) {
-        // A `category_no_page` index.mdx is metadata-only — kept in the nav
-        // tree for breadcrumbs but emits no route (zfb retains every .mdx as a
-        // collection entry, so the skip must be explicit).
-        if (entry.data.category_no_page === true) continue;
-        const slug = entry.data.slug ?? toRouteSlug(entry.slug);
-        const isFallback = fallbackSlugs.has(slug);
-        const entryContentDir = isFallback ? version.docsDir : (localeDir ?? version.docsDir);
-
-        const navSection = getNavSectionForSlug(slug);
-        const subtree = getNavSubtree(tree, navSection);
-
-        const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
-          tree,
-          flattenSubtree(subtree),
-          slug,
-          entry.data,
-        );
-
-        result.push({
-          params: { version: version.slug, locale, slug: toSlugParams(slug) },
-          props: {
-            kind: "entry",
-            entry,
-            version,
-            contentDir: entryContentDir,
-            isFallback,
-            // #1916 #1: breadcrumb crumbs remapped to the versioned locale URL.
-            breadcrumbs: buildBreadcrumbs(tree, slug, locale, urlFor),
-            prev: rewriteNavHref(prevNode, urlFor),
-            next: rewriteNavHref(nextNode, urlFor),
-            headings: extractHeadings(entry.body ?? ""),
-          },
-        });
-      }
-
-      // Auto-generated index pages for categories without index.mdx
-      for (const node of collectAutoIndexNodes(tree)) {
+      // this route's own tree (#1916).
+      const urlFor = (s: string): string => versionedDocsUrl(s, version.slug, locale as Locale);
+
+      for (const item of buildDocRouteEntries({
+        source,
+        locale: locale as Locale,
+        routeSig: `v-locale-docs;${version.slug};${locale}`,
+        urlFor,
+      })) {
+        // isFallback: page came from the version's base EN docs, not the
+        // locale collection. Always false for autoIndex items.
+        const extra: VersionedLocaleDocPageExtra = {
+          version,
+          contentDir: item.isFallback
+            ? version.docsDir
+            : (localeDir ?? version.docsDir),
+          isFallback: item.isFallback,
+        };
         result.push({
-          params: { version: version.slug, locale, slug: toSlugParams(node.slug) },
-          props: {
-            kind: "autoIndex",
-            autoIndex: {
-              ...node,
-              // #1916 #2: child-card hrefs ALWAYS resolve to the versioned URL.
-              children: remapNavChildHrefs(node.children, urlFor) as NavNode[],
-            } as AutoIndexNode,
-            version,
-            contentDir: localeDir ?? version.docsDir,
-            isFallback: false,
-            // #1916 #1: breadcrumb crumbs remapped to the versioned locale URL.
-            breadcrumbs: buildBreadcrumbs(tree, node.slug, locale, urlFor),
-            prev: null,
-            next: null,
-            headings: [],
-          },
+          params: { version: version.slug, locale, slug: item.slugParams },
+          props:
+            item.props.kind === "entry"
+              ? { ...item.props, ...extra }
+              : { ...item.props, ...extra },
         });
       }
     }
@@ -198,99 +143,9 @@ export function paths(): Array<{
 type PageArgs = DocPageProps & { params: { version: string; locale: string; slug: string[] } };
 
 export default function VersionedLocaleDocsPage(props: PageArgs): JSX.Element {
-  const { breadcrumbs, prev, next, headings, version, isFallback } = props;
-  const locale = props.params.locale;
-
-  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);
-
-  // #1916 #2: child cards already carry versioned hrefs from paths(); just
-  // filter to renderable nodes here.
-  const autoIndexChildren = props.kind === "autoIndex"
-    ? props.autoIndex.children.filter((c: NavNode) => c.hasPage || c.children.length > 0)
-    : [];
-
-  // Version banner: drives the `<VersionBanner>` element inside
-  // DocLayoutWithDefaults when `version.banner` is "unmaintained" or
-  // "unreleased". The banner links out to the latest version of the
-  // current page (slug-preserving — strips the /v/{version}/ prefix,
-  // keeps the /{locale}/ locale prefix).
-  const versionBannerType = version.banner ? version.banner : undefined;
-  const versionBannerLatestUrl = versionBannerType
-    ? docsUrl(slug, locale)
-    : undefined;
-  const versionBannerLabels = versionBannerType
-    ? {
-        message:
-          versionBannerType === "unmaintained"
-            ? t("version.banner.unmaintained", locale)
-            : t("version.banner.unreleased", locale),
-        latestLink: t("version.banner.latestLink", locale),
-      }
-    : undefined;
-
-  // Canonical URL — versioned locale pages use the versioned locale URL as canonical.
-  const currentPath = versionedDocsUrl(slug, version.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}
-      currentVersion={version.slug}
-      versionSwitcher={buildInlineVersionSwitcher(slug, locale, version.slug)}
-      versionBanner={versionBannerType}
-      versionBannerLatestUrl={versionBannerLatestUrl}
-      versionBannerLabels={versionBannerLabels}
-      autoIndexLabel={props.kind === "autoIndex" ? props.autoIndex.label : undefined}
-      autoIndexChildren={autoIndexChildren}
-      // #1916 #6: add DocMetainfoArea for chrome parity with the other 3
-      // doc routes (its absence here was accidental drift, not intentional).
-      metainfoSlot={
-        props.kind === "autoIndex" ? <DocMetainfoArea slug={slug} locale={locale} /> : null
-      }
-      contentHeaderSlot={
-        props.kind === "entry" ? (
-          <DocContentHeader entry={props.entry} slug={slug} locale={locale} isFallback={isFallback} />
-        ) : undefined
-      }
-      contentSlot={
-        props.kind === "entry" ? <props.entry.Content components={components} /> : undefined
-      }
-      // #1916 #5: doc-history hidden on versioned pages until versioned
-      // history is supported.
-      docHistorySlot={null}
-    />
-  );
+  return renderDocPage(props, {
+    locale: props.params.locale as Locale,
+    version: props.version,
+    isFallback: props.isFallback,
+  });
 }