create-zudo-doc 0.2.0 → 0.2.2

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,
+  });
 }

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -37,6 +37,7 @@ import ClientRouterBootstrap from "@/components/client-router-bootstrap";
 import DesignTokenPanelBootstrap from "@/components/design-token-panel-bootstrap";
 import ImageEnlarge, { ImageEnlargeSsrFallback } from "@/components/image-enlarge";
 import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
+// @slot:body-end-islands:imports
 
 // Set explicit `displayName` on each default-exported island so zfb's
 // `captureComponentName` produces a stable marker even after the SSR
@@ -51,6 +52,7 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
 (DesignTokenPanelBootstrap as { displayName?: string }).displayName =
   "DesignTokenPanelBootstrap";
 (ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
+// @slot:body-end-islands:display-names
 
 /**
  * Default sr-only label rendered as the AiChatModal SSR fallback. This
@@ -196,6 +198,7 @@ export function BodyEndIslands({
       <h2 class="sr-only">AI Assistant</h2>
       {aiChat}
       {imageEnlarge}
+      {/* @slot:body-end-islands:extra-islands */}
     </>
   );
 }

package/templates/base/pages/lib/_doc-content-header.tsx

@@ -33,6 +33,17 @@ interface DocContentHeaderProps {
    * Only relevant for locale-prefixed and versioned-locale routes.
    */
   isFallback?: boolean;
+  /**
+   * Version slug when rendering a versioned route (e.g. "1.0"); undefined =
+   * latest. On versioned pages the date block and tag chips are hidden —
+   * the doc-history-meta manifest is built only from the LATEST content
+   * dirs, so a bare versioned slug would resolve to the latest file's
+   * Created/Updated/Author (wrong data), and tag chips would link to latest
+   * tag routes that may not exist for version-only tags (404). Mirrors the
+   * #1916 reduced-chrome stance that already hides doc history on
+   * versioned pages.
+   */
+  version?: string;
 }
 
 /**
@@ -50,6 +61,7 @@ export function DocContentHeader({
   slug,
   locale,
   isFallback = false,
+  version,
 }: DocContentHeaderProps): JSX.Element {
   return (
     <>
@@ -57,11 +69,19 @@ export function DocContentHeader({
 
       {/* Build-time date block (Created / Updated / Author).
           doc-metainfo placement — between <h1> and description.
-          Data from `.zfb/doc-history-meta.json` (esbuild-inlined, no fs). */}
-      <DocMetainfoArea slug={slug} locale={locale} />
+          Data from `.zfb/doc-history-meta.json` (esbuild-inlined, no fs).
+          Hidden on versioned pages — the manifest only covers latest
+          content dirs, so a versioned slug would show the LATEST file's
+          dates (see the `version` prop doc above). */}
+      {!version && (
+        <DocMetainfoArea slug={slug} locale={locale} isFallback={isFallback} />
+      )}
 
-      {/* Page-level tag chips — matching doc-tags placement (#1658). */}
-      <DocTagsArea slug={slug} locale={locale} tags={entry.data.tags} />
+      {/* Page-level tag chips — matching doc-tags placement (#1658).
+          Hidden on versioned pages: tag routes are built from latest
+          frontmatter only, so a version-only tag chip would 404 (see the
+          `version` prop doc above). */}
+      {!version && <DocTagsArea slug={slug} locale={locale} tags={entry.data.tags} />}
 
       {/* Fallback notice for non-translated pages */}
       {isFallback && !entry.data.generated && (

package/templates/base/pages/lib/_doc-history-area.tsx

@@ -56,7 +56,8 @@ interface DocHistoryAreaProps {
   /**
    * Raw zfb entry slug (relative path without extension), e.g.
    * "getting-started/intro" or "getting-started/index". Appended with
-   * ".mdx" to form the file path passed to buildGitHubSourceUrl.
+   * the source extension from the build-time manifest (".mdx" fallback)
+   * to form the file path passed to buildGitHubSourceUrl.
    * Omit for auto-index pages (no underlying MDX file) — sourceUrl
    * will be suppressed automatically.
    */
@@ -130,7 +131,13 @@ export function DocHistoryArea({
   // locale, "<localeKey>/<slug>" for non-default locales.
   const composedSlug =
     effectiveHistoryLocale === defaultLocale ? historySlug : `${effectiveHistoryLocale}/${historySlug}`;
-  type MetaEntry = { author: string; createdDate: string; updatedDate: string };
+  type MetaEntry = {
+    author: string;
+    createdDate: string;
+    updatedDate: string;
+    /** Source file extension (".mdx" | ".md") — optional in older manifests. */
+    ext?: string;
+  };
   const meta = (docHistoryMeta as Record<string, MetaEntry>)[composedSlug];
 
   // Locale-aware labels for the SSR fallback.
@@ -156,7 +163,11 @@ export function DocHistoryArea({
   const createdDate = meta?.createdDate;
   const updatedDate = meta?.updatedDate;
 
-  const fallback: VNode = (
+  // Explicit type annotation omitted: inferred JSX return is structurally
+  // compatible with zfb's VNode (the ssrFallback prop target). Preact's
+  // VNode<{}> generic form is not directly assignable to zfb's VNode at the
+  // type level even though the runtime shapes are identical.
+  const fallback = (
     <div class="sr-only">
       {author && <span>{author}</span>}
       <span>
@@ -188,11 +199,16 @@ export function DocHistoryArea({
   // Compute the view-source GitHub URL host-side so the v2 BodyFootUtilArea
   // component stays oblivious to project settings. Gate on
   // bodyFootUtilArea.viewSourceLink, and require both entrySlug and contentDir
-  // (auto-index pages pass neither).
+  // (auto-index pages pass neither). The real source extension comes from the
+  // build-time manifest (`ext`, written by pre-build.ts) — the content walkers
+  // accept both .mdx and .md, so hardcoding ".mdx" produced broken view-source
+  // URLs for .md pages. ".mdx" remains the fallback for entries without a
+  // manifest record (untracked files, SKIP_DOC_HISTORY=1, stale manifests).
   const utilSettings = settings.bodyFootUtilArea;
+  const sourceExt = meta?.ext ?? ".mdx";
   const sourceUrl =
     utilSettings && utilSettings.viewSourceLink && entrySlug && contentDir
-      ? buildGitHubSourceUrl(contentDir, entrySlug + ".mdx")
+      ? buildGitHubSourceUrl(contentDir, entrySlug + sourceExt)
       : null;
 
   // Resolve the i18n label host-side; pass the result so the v2 component

package/templates/base/pages/lib/_doc-metainfo-area.tsx

@@ -61,6 +61,16 @@ interface DocMetainfoAreaProps {
   slug: string;
   /** Active locale string, e.g. "en", "ja". */
   locale: string;
+  /**
+   * True when this locale page falls back to the base EN collection
+   * (i.e. the slug has no translation for the active locale). When true,
+   * the manifest lookup uses defaultLocale so the visible block resolves
+   * the bare-slug key — the only key that exists for EN-origin files —
+   * matching the dropdown's `effectiveHistoryLocale` derivation in
+   * _doc-history-area.tsx. Display formatting (dates + labels) still uses
+   * the active locale so JA users see JA formatting on fallback pages.
+   */
+  isFallback?: boolean;
 }
 
 /**
@@ -76,7 +86,7 @@ interface DocMetainfoAreaProps {
  * HTML from build-time data and has no client JS footprint. It sits
  * between `<h1>` and the description `<p>` (doc-metainfo placement).
  */
-export function DocMetainfoArea({ slug, locale }: DocMetainfoAreaProps): VNode | null {
+export function DocMetainfoArea({ slug, locale, isFallback }: DocMetainfoAreaProps): VNode | null {
   if (!settings.docMetainfo) return null;
 
   // Doc-history storage sentinel ("" -> "index"): a root index page has the
@@ -87,10 +97,20 @@ export function DocMetainfoArea({ slug, locale }: DocMetainfoAreaProps): VNode |
   // @/utils/slug `toHistorySlug` and _doc-history-area.tsx. (#1891)
   const historySlug = toHistorySlug(slug);
 
+  // On EN-fallback locale pages the manifest only has the bare
+  // (non-locale-prefixed) key — the prebuild writes locale-prefixed keys
+  // only for files physically present in the locale collection. Use
+  // defaultLocale for the data lookup when isFallback is true, mirroring
+  // `effectiveHistoryLocale` in _doc-history-area.tsx so the visible block
+  // and the dropdown agree. Display formatting keeps the active locale.
+  const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
+
   // Key format: bare slug for default locale, "<locale>/<slug>" for others.
   // Matches the prebuild step's composedSlug logic (pre-build.ts).
   const composedSlug =
-    locale === defaultLocale ? historySlug : `${locale}/${historySlug}`;
+    effectiveHistoryLocale === defaultLocale
+      ? historySlug
+      : `${effectiveHistoryLocale}/${historySlug}`;
 
   type MetaEntry = { author: string; createdDate: string; updatedDate: string };
   const meta = (docHistoryMeta as Record<string, MetaEntry>)[composedSlug];

package/templates/base/pages/lib/_doc-page-renderer.tsx

@@ -0,0 +1,192 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Shared page renderer for the 4 doc catch-all routes.
+//
+// Extracted (#2010) from the near-identical default components of:
+//   pages/docs/[[...slug]].tsx
+//   pages/[locale]/docs/[[...slug]].tsx
+//   pages/v/[version]/docs/[[...slug]].tsx
+//   pages/v/[version]/[locale]/docs/[[...slug]].tsx
+//
+// Each route's default export stays a thin adapter that reads its params /
+// route-specific props (locale, version, contentDir, isFallback) and
+// delegates here. Route-specific behavior is parameterized:
+//   - `version` present → versioned chrome: versioned canonical URL, version
+//     banner, version-aware switcher, auto-index child hrefs kept as the
+//     pre-remapped versioned hrefs from paths() (#1916 #2), and doc history
+//     hidden until versioned history is supported (#1916 #5).
+//   - `version` absent → latest chrome: docsUrl canonical, child hrefs fall
+//     back to the nav node's own docsUrl, doc history rendered for listed
+//     entries via `docHistoryContentDir`.
+
+import { settings } from "@/config/settings";
+import type { VersionConfig } from "@/config/settings";
+import { t, type Locale } from "@/config/i18n";
+import { docsUrl, versionedDocsUrl, absoluteUrl } from "@/utils/base";
+import type { NavNode } from "@/utils/docs";
+import { getNavSectionForSlug } from "@/utils/nav-scope";
+import { toRouteSlug } from "@/utils/slug";
+import type { JSX } from "preact";
+// 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 type { DocPageBaseProps } from "./doc-page-props";
+import { DocHistoryArea } from "./_doc-history-area";
+import { DocMetainfoArea } from "./_doc-metainfo-area";
+import { buildInlineVersionSwitcher } from "./_inline-version-switcher";
+import { DocContentHeader } from "./_doc-content-header";
+import { DocPageShell } from "./_doc-page-shell";
+
+export interface RenderDocPageOptions {
+  /** Active locale — drives nav wrappers, labels, and URL building. */
+  locale: Locale;
+  /** Version config when rendering a versioned route; undefined = latest. */
+  version?: VersionConfig;
+  /** True when this page falls back to the base EN collection (locale
+   *  routes). Drives the fallback notice + history-area hint. */
+  isFallback?: boolean;
+  /**
+   * Content directory for the doc-history view-source link (e.g. the active
+   * locale's dir, or the base docsDir for EN/fallback pages). Latest routes
+   * pass it; versioned routes omit it — doc history is hidden on versioned
+   * pages regardless (#1916 #5).
+   */
+  docHistoryContentDir?: string;
+}
+
+export function renderDocPage(
+  props: DocPageBaseProps,
+  opts: RenderDocPageOptions,
+): JSX.Element {
+  const { breadcrumbs, prev, next, headings } = props;
+  const { locale, version, isFallback } = opts;
+
+  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. Versioned routes: child cards
+  // already carry versioned hrefs from paths() (#1916 #2) — just filter to
+  // renderable nodes. Latest routes: keep the nav node's own docsUrl href
+  // (fallback for a noPage parent without an href).
+  const autoIndexChildren = props.kind === "autoIndex"
+    ? version
+      ? props.autoIndex.children.filter((c: NavNode) => c.hasPage || c.children.length > 0)
+      : props.autoIndex.children
+          .filter((c: NavNode) => c.hasPage || c.children.length > 0)
+          .map((c: NavNode) => ({
+            ...c,
+            href: c.href ?? docsUrl(c.slug, locale),
+          }))
+    : [];
+
+  // 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 — base-prefixed page path, absolutized against siteUrl.
+  // Versioned pages use the versioned URL as canonical.
+  const currentPath = version
+    ? versionedDocsUrl(slug, version.slug, locale)
+    : 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}
+      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}
+      metainfoSlot={
+        // Versioned gate mirrors DocContentHeader: the doc-history-meta
+        // manifest is built from latest dirs only, so a bare versioned slug
+        // would surface the LATEST page's Created/Updated/Author.
+        !version && props.kind === "autoIndex" ? (
+          <DocMetainfoArea slug={slug} locale={locale} isFallback={isFallback} />
+        ) : null
+      }
+      contentHeaderSlot={
+        props.kind === "entry" ? (
+          <DocContentHeader
+            entry={props.entry}
+            slug={slug}
+            locale={locale}
+            isFallback={isFallback}
+            version={version?.slug}
+          />
+        ) : undefined
+      }
+      contentSlot={
+        props.kind === "entry" ? <props.entry.Content components={components} /> : undefined
+      }
+      docHistorySlot={
+        // #1916 #5: doc-history hidden on versioned pages until versioned
+        // history is supported.
+        !version &&
+        opts.docHistoryContentDir !== undefined &&
+        props.kind === "entry" &&
+        !props.entry.data.unlisted ? (
+          <DocHistoryArea
+            slug={slug}
+            locale={locale}
+            entrySlug={props.entry.slug}
+            contentDir={opts.docHistoryContentDir}
+            isFallback={isFallback}
+          />
+        ) : null
+      }
+    />
+  );
+}

package/templates/base/pages/lib/_doc-page-shell.tsx

@@ -32,6 +32,7 @@ import { DocBodyEnd } from "./_doc-body-end";
 import { DocPager } from "./_doc-pager";
 import type { BreadcrumbItem } from "@/utils/docs";
 import type { VersionBannerLabels } from "@takazudo/zudo-doc/i18n-version";
+import type { Locale } from "@/config/i18n";
 import type { extractHeadings } from "./_extract-headings";
 
 /** Slots and parameters that vary between the 4 doc routes. */
@@ -161,7 +162,7 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
       versionBannerLabels={versionBannerLabels}
       headerOverride={
         <HeaderWithDefaults
-          lang={locale}
+          lang={locale as Locale}
           currentSlug={props.slug}
           navSection={navSection}
           currentVersion={currentVersion}
@@ -176,7 +177,7 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
       sidebarOverride={
         <SidebarWithDefaults
           currentSlug={props.slug}
-          lang={locale}
+          lang={locale as Locale}
           navSection={navSection}
           currentVersion={currentVersion}
           currentPath={currentPath}