create-zudo-doc 0.2.0-next.3 → 0.2.0-next.5

package/dist/features/versioning.d.ts

@@ -13,15 +13,11 @@ import type { FeatureModule } from "../compose.js";
  *
  *   docs/versions.tsx                       (always — versioning gate only)
  *   v/[version]/docs/[...slug].tsx          (always — versioning gate only)
- *   v/[version]/ja/docs/[...slug].tsx       (i18n + versioning — see below)
+ *   v/[version]/[locale]/docs/[...slug].tsx (i18n + versioning — see below)
  *   [locale]/docs/versions.tsx              (i18n + versioning)
  *
  * `copyFeatureFiles` (compose.ts) auto-copies everything under `files/`.
  * postProcess removes the i18n-gated subset when i18n is OFF so single-
  * locale projects don't ship orphan routes.
- *
- * Note: `v/[version]/ja/docs/[...slug].tsx` hardcodes `ja` per W2 spec-lock
- * Decision 9 / §6.4 — matches main verbatim. Future generalization to
- * `[locale]` is deferred (maintainer-question follow-up).
  */
 export declare const versioningFeature: FeatureModule;

package/dist/features/versioning.js

@@ -14,16 +14,12 @@ import path from "path";
  *
  *   docs/versions.tsx                       (always — versioning gate only)
  *   v/[version]/docs/[...slug].tsx          (always — versioning gate only)
- *   v/[version]/ja/docs/[...slug].tsx       (i18n + versioning — see below)
+ *   v/[version]/[locale]/docs/[...slug].tsx (i18n + versioning — see below)
  *   [locale]/docs/versions.tsx              (i18n + versioning)
  *
  * `copyFeatureFiles` (compose.ts) auto-copies everything under `files/`.
  * postProcess removes the i18n-gated subset when i18n is OFF so single-
  * locale projects don't ship orphan routes.
- *
- * Note: `v/[version]/ja/docs/[...slug].tsx` hardcodes `ja` per W2 spec-lock
- * Decision 9 / §6.4 — matches main verbatim. Future generalization to
- * `[locale]` is deferred (maintainer-question follow-up).
  */
 export const versioningFeature = (choices) => ({
     name: "versioning",
@@ -33,9 +29,9 @@ export const versioningFeature = (choices) => ({
             if (await fs.pathExists(localeVersions)) {
                 await fs.remove(localeVersions);
             }
-            const jaVersionedDocs = path.join(targetDir, "pages", "v", "[version]", "ja");
-            if (await fs.pathExists(jaVersionedDocs)) {
-                await fs.remove(jaVersionedDocs);
+            const localeVersionedDocs = path.join(targetDir, "pages", "v", "[version]", "[locale]");
+            if (await fs.pathExists(localeVersionedDocs)) {
+                await fs.remove(localeVersionedDocs);
             }
         }
     },

package/dist/scaffold.js

@@ -248,16 +248,26 @@ function generatePackageJson(choices) {
         // so render failures surface `console.*` output. next.27 is unusable
         // for adapter consumers — its tarball omitted emit-worker.mjs
         // (Takazudo/zudo-front-builder#794, fixed in next.28) — so never pin 27.
-        "@takazudo/zfb": "0.1.0-next.28",
-        "@takazudo/zfb-runtime": "0.1.0-next.28",
+        // Bumped to next.30 — adds Next.js-style `[[...slug]]` optional-catchall
+        // route syntax (Takazudo/zudo-front-builder#812) and raises the zfb-runtime
+        // hono floor to ^4.12.23, clearing 9 advisories (#813); also two router
+        // hardening fixes (overlapping-sibling rejection #816, per-segment rank
+        // sort for dev/prod parity). No consumer-facing breaking change.
+        // Bumped to next.31 — CSS-pipeline and islands-scanner fixes (no
+        // consumer-facing breaking change): authored-CSS path when Tailwind is
+        // disabled, reproducible CSS-Modules scoped names (project-relative paths),
+        // dev-mode git-restore detection, Tailwind temp-file cleanup, and a
+        // near-miss `"use client"` directive scanner.
+        "@takazudo/zfb": "0.1.0-next.31",
+        "@takazudo/zfb-runtime": "0.1.0-next.31",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.28",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.31",
         // @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.3",
+        "@takazudo/zudo-doc": "^0.2.0-next.5",
         // 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
@@ -315,7 +325,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.3";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.5";
         // 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

package/dist/settings-gen.js

@@ -107,6 +107,8 @@ export function generateSettingsFile(choices) {
     // the chat once they're wiring up a real `ANTHROPIC_API_KEY`. Defaulting
     // demo mode off avoids silently disabling chat for them.
     lines.push(`  aiChatDemoMode: false as boolean,`);
+    lines.push(`  aiChatAllowedOrigins: [] as string[],`);
+    lines.push(`  aiChatGlobalDailyLimit: false as number | false,`);
     if (choices.features.includes("docHistory")) {
         lines.push(`  docHistory: true,`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.0-next.3",
+  "version": "0.2.0-next.5",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",
@@ -46,6 +46,7 @@
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm clean && tsc",
     "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:slow": "vitest run --config vitest.slow.config.ts",
     "prepublishOnly": "pnpm build && pnpm test"

package/templates/base/pages/_data.ts

@@ -13,6 +13,7 @@
 import { getCollection } from "zfb/content";
 import type { CollectionEntry } from "zfb/content";
 import type { DocsEntry } from "@/types/docs-entry";
+import { toRouteSlug } from "@/utils/slug";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -92,9 +93,14 @@ export function getDocs(collectionName: string): ZfbDocsEntry[] {
   }));
 }
 
+// The `id` field bridged onto every entry is the canonical route slug, so it
+// routes through the one shared rule (`toRouteSlug` in @/utils/slug) — bare
+// root `index` → "" (URL /docs/), nested `x/index` → "x". Previously this was
+// a standalone copy of the strip logic (the lone "" dissenter of the five
+// index-stripping sites); consolidating it here means there is one source of
+// truth. See @/utils/slug for the canonical-root rationale (#1891 / #1873).
 function stripIndexSuffix(slug: string): string {
-  if (slug === "index") return "";
-  return slug.endsWith("/index") ? slug.slice(0, -"/index".length) : slug;
+  return toRouteSlug(slug);
 }
 
 /**
@@ -148,32 +154,3 @@ export function filterDrafts(entries: ZfbDocsEntry[]): ZfbDocsEntry[] {
   return entries.filter((e) => !e.data.draft);
 }
 
-/**
- * Merge locale docs with base (EN) fallbacks.
- *
- * Strategy (mirrors src/utils/locale-docs.ts):
- *   1. Load locale docs (e.g. "docs-ja")
- *   2. Load base docs ("docs")
- *   3. Locale docs take priority; base docs fill in missing slugs.
- *   4. Track which slugs came from base (fallbackSlugs).
- *
- * Returns { allDocs, fallbackSlugs }.
- * categoryMeta is not merged here — callers use loadCategoryMeta() directly.
- */
-export function mergeLocaleDocs(
-  locale: string,
-): { allDocs: ZfbDocsEntry[]; fallbackSlugs: Set<string> } {
-  const localeDocs = filterDrafts(getDocs(`docs-${locale}`));
-  const baseDocs = filterDrafts(getDocs("docs"));
-
-  const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? d.id));
-
-  const fallbackDocs = baseDocs.filter(
-    (d) => !localeSlugSet.has(d.data.slug ?? d.id),
-  );
-
-  return {
-    allDocs: [...localeDocs, ...fallbackDocs],
-    fallbackSlugs: new Set(fallbackDocs.map((d) => d.data.slug ?? d.id)),
-  };
-}

package/templates/base/pages/docs/{[...slug].tsx → [[...slug]].tsx}

@@ -11,36 +11,34 @@
 //   params: { slug: string[] }   — e.g. ["getting-started", "intro"]
 //   props:  { entry, autoIndex, breadcrumbs, prev, next }
 //
+// Route is the OPTIONAL catchall `[[...slug]]` so a bare root index.mdx can
+// build at `/docs/` (canonical root URL — #1891). The root entry emits
+// `params.slug = []` (zero segments) via `toSlugParams`; a required `[...slug]`
+// catchall rejects an empty array and would drop the whole route.
+//
 // The catchall slug is an array per zfb spec — the component joins it when
 // deriving the string form (e.g. for Content lookups, breadcrumbs, etc.).
 //
 // Locale: defaultLocale (EN). Non-default locales are handled by
-// pages/[locale]/docs/[...slug].tsx.
+// pages/[locale]/docs/[[...slug]].tsx.
 
-import { getCollection } from "zfb/content";
-import type { CollectionEntry } from "zfb/content";
 import type { DocsEntry } from "@/types/docs-entry";
 import { settings } from "@/config/settings";
-import { defaultLocale, t } from "@/config/i18n";
+import { defaultLocale } from "@/config/i18n";
 import { docsUrl } from "@/utils/base";
 import {
   buildNavTree,
   buildBreadcrumbs,
   flattenTree,
   findNode,
-  loadCategoryMeta,
   collectAutoIndexNodes,
-  isNavVisible,
   type NavNode,
-  type BreadcrumbItem,
 } from "@/utils/docs";
 import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
-import { toRouteSlug } from "@/utils/slug";
+import { toRouteSlug, toSlugParams } from "@/utils/slug";
 import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
 import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
 import { NavCardGrid } from "@takazudo/zudo-doc/nav-indexing";
-import { FrontmatterPreview } from "@takazudo/zudo-doc/metainfo";
-import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
 // 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
@@ -49,21 +47,19 @@ import { createMdxComponents } from "../_mdx-components";
 import { FooterWithDefaults } from "../lib/_footer-with-defaults";
 import { DocHistoryArea } from "../lib/_doc-history-area";
 import { DocMetainfoArea } from "../lib/_doc-metainfo-area";
-import { DocTagsArea } from "../lib/_doc-tags-area";
-import { BodyEndIslands } from "../lib/_body-end-islands";
 import { SidebarWithDefaults } from "../lib/_sidebar-with-defaults";
 import { HeaderWithDefaults } from "../lib/_header-with-defaults";
 import { HeadWithDefaults } from "../lib/_head-with-defaults";
-import { buildFrontmatterPreviewEntries } from "../lib/_frontmatter-preview-data";
 import { composeMetaTitle } from "../lib/_compose-meta-title";
 import { buildInlineVersionSwitcher } from "../lib/_inline-version-switcher";
 import type { JSX } from "preact";
-import { bridgeEntries } from "../_data";
+import { resolveNavSource } from "../lib/_nav-source-docs";
 import { extractHeadings } from "../lib/_extract-headings";
-import DesktopSidebarToggle from "@/components/desktop-sidebar-toggle";
-import { SidebarResizerInit } from "@takazudo/zudo-doc/sidebar-resizer";
-import type { VNode } from "preact";
-import { Island } from "@takazudo/zfb";
+import type { DocPageEntry, AutoIndexNode, DocPageEntryProps, DocPageAutoIndexProps } from "../lib/doc-page-props";
+import { DocPager } from "../lib/_doc-pager";
+import { DocContentHeader } from "../lib/_doc-content-header";
+import { SidebarPrepaint } from "../lib/_sidebar-prepaint";
+import { DocBodyEnd } from "../lib/_doc-body-end";
 
 export const frontmatter = { title: "Docs" };
 
@@ -71,31 +67,9 @@ export const frontmatter = { title: "Docs" };
 // Props contract
 // ---------------------------------------------------------------------------
 
-interface DocPageEntry extends DocsEntry {
-  /** zfb content renderer. */
-  Content: CollectionEntry<unknown>["Content"];
-  /** zfb module specifier (for Content bridge). */
-  module_specifier: string;
-}
-
-interface AutoIndexNode extends NavNode {
-  children: NavNode[];
-}
+// DocPageEntry, AutoIndexNode imported from pages/lib/doc-page-props.ts
 
-interface DocPageProps {
-  /** The docs entry to render, or null for auto-index pages. */
-  entry: DocPageEntry | null;
-  /** Pre-built auto-index node (categories without index.mdx). */
-  autoIndex?: AutoIndexNode;
-  /** Breadcrumb trail, first item is home. */
-  breadcrumbs: BreadcrumbItem[];
-  /** Preceding page in the nav tree. */
-  prev: NavNode | null;
-  /** Following page in the nav tree. */
-  next: NavNode | null;
-  /** Depth-2/3/4 headings extracted from the MDX body, for SSG TOC links. */
-  headings: ReturnType<typeof extractHeadings>;
-}
+type DocPageProps = DocPageEntryProps | DocPageAutoIndexProps;
 
 // ---------------------------------------------------------------------------
 // paths() — synchronous route enumeration (ADR-004)
@@ -113,13 +87,13 @@ export function paths(): Array<{
   props: DocPageProps;
 }> {
   const locale = defaultLocale;
-  const allDocs = (bridgeEntries(getCollection("docs"), "docs") as unknown as DocPageEntry[]);
-  // In static builds, always exclude drafts.
-  const docs = allDocs.filter((doc) => !doc.data.draft);
-  const categoryMeta = loadCategoryMeta(settings.docsDir);
+  // 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 navDocs = docs.filter(isNavVisible);
   const tree = buildNavTree(navDocs as unknown as DocsEntry[], locale, categoryMeta);
   // Full tree (including unlisted) for accurate breadcrumbs
   const fullTree = buildNavTree(docs as unknown as DocsEntry[], locale, categoryMeta);
@@ -156,8 +130,9 @@ export function paths(): Array<{
     }
 
     result.push({
-      params: { slug: slug.split("/") },
+      params: { slug: toSlugParams(slug) },
       props: {
+        kind: "entry",
         entry,
         breadcrumbs: buildBreadcrumbs(fullTree, slug, locale),
         prev: prevNode,
@@ -170,9 +145,9 @@ export function paths(): Array<{
   // Auto-generated index pages for categories without index.mdx
   for (const node of collectAutoIndexNodes(tree)) {
     result.push({
-      params: { slug: node.slug.split("/") },
+      params: { slug: toSlugParams(node.slug) },
       props: {
-        entry: null,
+        kind: "autoIndex",
         autoIndex: node as AutoIndexNode,
         breadcrumbs: buildBreadcrumbs(fullTree, node.slug, locale),
         prev: null,
@@ -189,33 +164,26 @@ export function paths(): Array<{
 // Page component
 // ---------------------------------------------------------------------------
 
-interface PageArgs {
-  params: { slug: string[] };
-  entry: DocPageProps["entry"];
-  autoIndex?: DocPageProps["autoIndex"];
-  breadcrumbs: DocPageProps["breadcrumbs"];
-  prev: DocPageProps["prev"];
-  next: DocPageProps["next"];
-  headings: DocPageProps["headings"];
-}
+type PageArgs = DocPageProps & { params: { slug: string[] } };
 
-export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, headings }: PageArgs): JSX.Element {
+export default function DocsPage(props: PageArgs): JSX.Element {
+  const { breadcrumbs, prev, next, headings } = props;
   const locale = defaultLocale;
 
-  const slug = autoIndex
-    ? autoIndex.slug
-    : (entry!.data.slug ?? toRouteSlug(entry!.slug));
+  const slug = props.kind === "autoIndex"
+    ? props.autoIndex.slug
+    : (props.entry.data.slug ?? toRouteSlug(props.entry.slug));
 
-  const title = autoIndex ? autoIndex.label : entry!.data.title;
-  const description = autoIndex ? autoIndex.description : entry!.data.description;
+  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
-  const autoIndexChildren = autoIndex
-    ? autoIndex.children
+  const autoIndexChildren = props.kind === "autoIndex"
+    ? props.autoIndex.children
         .filter((c: NavNode) => c.hasPage || c.children.length > 0)
         .map((c: NavNode) => ({
           ...c,
@@ -235,7 +203,7 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
   // both lang (BCP-47 locale string) and navSection (filesystem-derived
   // kebab-case slug) come from controlled, trusted sources.
   const navSection = getNavSectionForSlug(slug);
-  const hideSidebar = entry?.data?.hide_sidebar;
+  const hideSidebar = props.kind === "entry" ? props.entry.data.hide_sidebar : undefined;
   const sidebarPersistKey = hideSidebar
     ? undefined
     : `sidebar-${locale}-${navSection ?? "default"}`;
@@ -248,7 +216,7 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
       lang={locale}
       noindex={settings.noindex}
       hideSidebar={hideSidebar}
-      hideToc={entry?.data?.hide_toc}
+      hideToc={props.kind === "entry" ? props.entry.data.hide_toc : undefined}
       headings={headings}
       canonical={canonical}
       sidebarPersistKey={sidebarPersistKey}
@@ -276,36 +244,11 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
           currentPath={docsUrl(slug, locale)}
         />
       }
-      afterSidebar={
-        // Pre-paint inline script: restore persisted sidebar visibility to
-        // <html data-sidebar-hidden> before first paint to avoid flash.
-        // Runs unconditionally when sidebarToggle is enabled; the attribute
-        // is only set when localStorage says "false" so the default (visible)
-        // needs no attribute and causes no layout shift.
-        settings.sidebarToggle ? (
-          <>
-            <script dangerouslySetInnerHTML={{
-              __html: `(function(){try{if(localStorage.getItem('zudo-doc-sidebar-visible')==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`,
-            }} />
-            {Island({
-              when: "load",
-              children: <DesktopSidebarToggle />,
-            }) as unknown as VNode}
-          </>
-        ) : undefined
-      }
+      afterSidebar={<SidebarPrepaint />}
       footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={
-        <>
-          <BodyEndIslands basePath={settings.base ?? "/"} />
-          {/* SidebarResizerInit: attach drag handle to #desktop-sidebar on load
-              and on AFTER_NAVIGATE_EVENT (zfb:after-swap under the Strategy B
-              SPA navigation model). Idempotent — safe on every page. */}
-          {settings.sidebarResizer && <SidebarResizerInit />}
-        </>
-      }
+      bodyEndComponents={<DocBodyEnd />}
     >
-      {autoIndex ? (
+      {props.kind === "autoIndex" ? (
         /* Auto-index page: category without an index.mdx.
            Fragment (not <div>) so children become direct children of
            <article class="zd-content">, picking up the flow-space rule
@@ -313,7 +256,7 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
            Wrapping in <div> would make h1/description p children-of-children
            and the flow gap (~24px) would never apply — see #1460. */
         <>
-          <h1 class="text-heading font-bold mb-vsp-xs">{autoIndex.label}</h1>
+          <h1 class="text-heading font-bold mb-vsp-xs">{props.autoIndex.label}</h1>
 
           {/* Build-time date block — chrome parity (#1461). Auto-index pages
               previously rendered without doc-meta; reference site shows it on
@@ -321,9 +264,9 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
               entry exists for this slug. */}
           <DocMetainfoArea slug={slug} locale={locale} />
 
-          {autoIndex.description && (
+          {props.autoIndex.description && (
             <p class="mb-vsp-lg text-title text-muted">
-              {autoIndex.description}
+              {props.autoIndex.description}
             </p>
           )}
           <NavCardGrid children={autoIndexChildren} />
@@ -332,112 +275,24 @@ export default function DocsPage({ entry, autoIndex, breadcrumbs, prev, next, he
         /* Regular doc page. Fragment (not <div>) for the same reason as
            the auto-index branch above — see #1460. */
         <>
-          <h1 class="text-heading font-bold mb-vsp-xs">{entry!.data.title}</h1>
-
-          {/* 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} />
-
-          {/* Page-level tag chips — matching doc-tags placement (#1658). */}
-          <DocTagsArea slug={slug} locale={locale} tags={entry!.data.tags} />
-
-          {entry!.data.description && (
-            <p class="mb-vsp-lg text-title text-muted">
-              {entry!.data.description}
-            </p>
-          )}
-
-          {/* Frontmatter preview — non-system, custom keys only. Returns
-              null when the entries array is empty, so pages without
-              custom frontmatter emit nothing. Custom per-key renderers
-              from frontmatter-preview-renderers.tsx produce styled cells
-              (pills, badges, etc.) instead of plain text. */}
-          <FrontmatterPreview
-            entries={buildFrontmatterPreviewEntries(entry!.data)}
-            title={t("frontmatter.preview.title", locale)}
-            keyColLabel={t("frontmatter.preview.keyCol", locale)}
-            valueColLabel={t("frontmatter.preview.valueCol", locale)}
-            renderers={frontmatterRenderers}
-            data={entry!.data as Record<string, unknown>}
-            locale={locale}
-          />
+          <DocContentHeader entry={props.entry} slug={slug} locale={locale} />
 
           {/* MDX content rendered via zfb's Content bridge */}
-          {entry && <entry.Content components={components} />}
+          <props.entry.Content components={components} />
 
           {/* Prev / Next pagination — placed before the document utilities
               section to match the Astro reference order: content → pager →
               view-source / history. In the Astro layout, BodyFootUtilArea was
               rendered by the doc-layout wrapper after the <slot /> content,
               so the pager (inside the slot) came first. Fixes #1535. */}
-          <nav class="mt-vsp-2xl grid grid-cols-2 gap-hsp-xl">
-            {prev ? (
-              <a
-                href={prev.href}
-                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent"
-              >
-                <div class="flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs">
-                  <svg
-                    xmlns="http://www.w3.org/2000/svg"
-                    class="h-[1.125rem] w-[1.125rem]"
-                    fill="none"
-                    viewBox="0 0 24 24"
-                    stroke="currentColor"
-                    stroke-width="2"
-                  >
-                    <path
-                      stroke-linecap="round"
-                      stroke-linejoin="round"
-                      d="M15 19l-7-7 7-7"
-                    />
-                  </svg>
-                  <span class="no-underline">{t("nav.previous", locale)}</span>
-                </div>
-                <p class="text-small font-semibold underline group-hover:text-accent">
-                  {prev.label}
-                </p>
-              </a>
-            ) : (
-              <div />
-            )}
-            {next ? (
-              <a
-                href={next.href}
-                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent text-right"
-              >
-                <div class="flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs">
-                  <span class="no-underline">{t("nav.next", locale)}</span>
-                  <svg
-                    xmlns="http://www.w3.org/2000/svg"
-                    class="h-[1.125rem] w-[1.125rem]"
-                    fill="none"
-                    viewBox="0 0 24 24"
-                    stroke="currentColor"
-                    stroke-width="2"
-                  >
-                    <path
-                      stroke-linecap="round"
-                      stroke-linejoin="round"
-                      d="M9 5l7 7-7 7"
-                    />
-                  </svg>
-                </div>
-                <p class="text-small font-semibold underline group-hover:text-accent">
-                  {next.label}
-                </p>
-              </a>
-            ) : (
-              <div />
-            )}
-          </nav>
+          <DocPager prev={prev} next={next} locale={locale} />
 
           {/* Document utilities (revision history + view-source link) — skipped for unlisted pages */}
-          {!entry!.data.unlisted && (
+          {!props.entry.data.unlisted && (
             <DocHistoryArea
               slug={slug}
               locale={locale}
-              entrySlug={entry!.slug}
+              entrySlug={props.entry.slug}
               contentDir={settings.docsDir}
             />
           )}

package/templates/base/pages/index.tsx

@@ -12,16 +12,14 @@
 //   → collectTags()         counts unique tags for the tag section header
 //   → DocLayoutWithDefaults renders the page with no sidebar/TOC
 
-import { loadDocs } from "./_data";
 import { settings } from "@/config/settings";
 import { defaultLocale, t } from "@/config/i18n";
 import { withBase } from "@/utils/base";
 import {
   buildNavTree,
   groupSatelliteNodes,
-  isNavVisible,
 } from "@/utils/docs";
-import { loadCategoryMeta } from "@/utils/docs";
+import { resolveNavSource } from "./lib/_nav-source-docs";
 import { getCategoryOrder } from "@/utils/nav-scope";
 import { collectTags } from "@/utils/tags";
 import { toRouteSlug } from "@/utils/slug";
@@ -41,20 +39,15 @@ export const frontmatter = { title: "Home" };
 export default function IndexPage(): JSX.Element {
   const locale = defaultLocale;
 
-  // `loadDocs` bridges zfb's CollectionEntry → Astro-style DocsEntry
-  // (adds `id`/`collection`) so `@/utils/docs` helpers see the shape
-  // they expect.
-  const allDocs = loadDocs("docs");
-  const docs = allDocs.filter((doc) => !doc.data.draft);
-  const categoryMeta = loadCategoryMeta(settings.docsDir);
-  const navDocs = docs.filter(isNavVisible);
+  // Identity-stable nav source (draft-filtered, unlisted retained). navDocs is
+  // pre-filtered (isNavVisible) and shared with the nav-tree fast-path.
+  const { navDocs, categoryMeta } = resolveNavSource(locale, undefined);
   const tree = buildNavTree(navDocs, locale, categoryMeta);
   const categoryOrder = getCategoryOrder();
   const groupedTree = groupSatelliteNodes(tree, categoryOrder);
 
-  const tagDocs = docs.filter(isNavVisible);
   const tagCount = collectTags(
-    tagDocs,
+    navDocs,
     (id, data) => data.slug ?? toRouteSlug(id),
   ).size;