create-zudo-doc 0.2.0 → 0.2.1

package/templates/features/docTags/files/pages/docs/tags/[tag].tsx

@@ -2,7 +2,7 @@
 /** @jsxImportSource preact */
 // Page module for the default-locale per-tag detail route.
 //
-// Default-locale (en) per-tag detail page. paths() enumerates one route per
+// Default-locale per-tag detail page. paths() enumerates one route per
 // unique tag in the "docs" collection and passes the resolved TagInfo as a
 // prop so the component has zero extra collection reads at render time.
 //
@@ -10,29 +10,13 @@
 //   params: { tag: string }
 //   props:  { tagInfo: TagInfo }
 //
-// Data flow:
-//   getCollection("docs") [sync] → collectTags() → one route per tag
-//   render: DocCardGrid with pre-resolved TagInfo.docs items
+// Tag collection + rendering are shared with the locale-prefixed route via
+// pages/lib/_tag-pages.tsx (#2010) — this file owns only the param shape.
 
-import { getCollection } from "zfb/content";
-import { collectTags } from "@/utils/tags";
+import { defaultLocale } from "@/config/i18n";
 import type { TagInfo } from "@/utils/tags";
-import { toRouteSlug } from "@/utils/slug";
-import { t, defaultLocale } from "@/config/i18n";
-import { settings } from "@/config/settings";
-import { withBase, docsUrl } from "@/utils/base";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
-import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
-import { DocCardGrid } from "@takazudo/zudo-doc/nav-indexing";
 import type { JSX } from "preact";
-import { bridgeDocsEntries, type ZfbDocsData } from "../../_data";
-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 { DocHistoryArea } from "../../lib/_doc-history-area";
-import { BodyEndIslands } from "../../lib/_body-end-islands";
+import { collectTagMapForLocale, TagDetailPageView } from "../../lib/_tag-pages";
 
 export const frontmatter = { title: "Tag" };
 
@@ -41,14 +25,7 @@ export function paths(): Array<{
   params: { tag: string };
   props: { tagInfo: TagInfo };
 }> {
-  const allDocs = bridgeDocsEntries(getCollection<ZfbDocsData>("docs"), "docs");
-  // category_no_page index.mdx builds no route — drop it so a tag it carries
-  // doesn't render a DocCard linking to a non-existent /docs/<cat>/ page.
-  const docs = allDocs.filter(
-    (doc) =>
-      !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page,
-  );
-  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+  const tagMap = collectTagMapForLocale(defaultLocale);
 
   return [...tagMap.entries()].map(([tag, tagInfo]) => ({
     params: { tag },
@@ -62,44 +39,5 @@ interface PageProps {
 }
 
 export default function DocTagPage({ params, tagInfo }: PageProps): JSX.Element {
-  const { tag } = params;
-  const locale = defaultLocale;
-
-  const countText =
-    tagInfo.count === 1
-      ? t("doc.pageCountSingle", locale).replace("{count}", String(tagInfo.count))
-      : t("doc.pageCount", locale).replace("{count}", String(tagInfo.count));
-
-  const pageTitle = `${t("doc.taggedWith", locale)}: ${tag}`;
-
-  const breadcrumbItems: BreadcrumbItem[] = [
-    { label: "Docs" },
-    { label: t("doc.allTags", locale), href: withBase("/docs/tags") },
-    { label: tag },
-  ];
-
-  const cardItems = tagInfo.docs.map((doc) => ({
-    href: docsUrl(doc.slug, locale),
-    title: doc.title,
-    description: doc.description,
-  }));
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(pageTitle)}
-      head={<HeadWithDefaults title={pageTitle} />}
-      noindex={settings.noindex}
-      hideSidebar={true}
-      hideToc={true}
-      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/docs/tags/${tag}`)} />}
-      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-    >
-      <h1 class="text-heading font-bold mb-vsp-xs">{pageTitle}</h1>
-      <p class="text-muted mb-vsp-lg">{countText}</p>
-      <DocCardGrid ariaLabel={pageTitle} items={cardItems} />
-      <DocHistoryArea slug={`tags/${tag}`} locale={locale} />
-    </DocLayoutWithDefaults>
-  );
+  return <TagDetailPageView locale={defaultLocale} tag={params.tag} tagInfo={tagInfo} />;
 }

package/templates/features/docTags/files/pages/docs/tags/index.tsx

@@ -2,89 +2,19 @@
 /** @jsxImportSource preact */
 // Page module for the default-locale "All Tags" index route.
 //
-// Default-locale (en) "All Tags" index page. Collects every tag across the
+// Default-locale "All Tags" index page. Collects every tag across the
 // "docs" collection, sorts them alphabetically, and renders a full tag cloud
 // via the v2 TagNav component. No dynamic params — single static route.
 //
-// Data flow:
-//   getCollection("docs")   [sync, zfb/content]
-//   → collectTags()         builds { tag → { count, docs[] } }
-//   → sort by tag           preserves sort parity with Astro original
-//   → TagNav variant="all"  renders the chip cloud
+// Tag collection + rendering are shared with the locale-prefixed route via
+// pages/lib/_tag-pages.tsx (#2010).
 
-import { getCollection } from "zfb/content";
-import { collectTags } from "@/utils/tags";
-import { toRouteSlug } from "@/utils/slug";
-import { t, defaultLocale } from "@/config/i18n";
-import { withBase } from "@/utils/base";
-import { settings } from "@/config/settings";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
-import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
-import { TagNav } from "@takazudo/zudo-doc/nav-indexing";
-import type { TagItem, TagNavLabels } from "@takazudo/zudo-doc/nav-indexing";
+import { defaultLocale } from "@/config/i18n";
 import type { JSX } from "preact";
-import { bridgeDocsEntries, type ZfbDocsData } from "../../_data";
-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 { DocHistoryArea } from "../../lib/_doc-history-area";
-import { BodyEndIslands } from "../../lib/_body-end-islands";
+import { TagsIndexPageView } from "../../lib/_tag-pages";
 
 export const frontmatter = { title: "All Tags" };
 
 export default function DocsTagsIndexPage(): JSX.Element {
-  const locale = defaultLocale;
-  const pageTitle = t("doc.allTags", locale);
-
-  const allDocs = bridgeDocsEntries(getCollection<ZfbDocsData>("docs"), "docs");
-  // category_no_page index.mdx builds no route — drop it so a tag it carries
-  // doesn't inflate the tag list with a card linking to a non-existent page.
-  const docs = allDocs.filter(
-    (doc) =>
-      !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page,
-  );
-  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-
-  const labels: TagNavLabels = {
-    tags: t("doc.tags", locale),
-    taggedWith: t("doc.taggedWith", locale),
-  };
-
-  // Sort alphabetically — matches documented tag-nav sort order.
-  const tags: TagItem[] = [...tagMap.values()]
-    .sort((a, b) => a.tag.localeCompare(b.tag, locale))
-    .map((info) => ({
-      tag: info.tag,
-      count: info.count,
-      href: withBase(`/docs/tags/${info.tag}`),
-    }));
-
-  const breadcrumbItems: BreadcrumbItem[] = [
-    { label: "Docs" },
-    { label: pageTitle },
-  ];
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(pageTitle)}
-      head={<HeadWithDefaults title={pageTitle} />}
-      noindex={settings.noindex}
-      hideSidebar={true}
-      hideToc={true}
-      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/docs/tags")} />}
-      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-    >
-      <h1 class="text-heading font-bold mb-vsp-lg">{pageTitle}</h1>
-      {!settings.docTags || tags.length === 0 ? (
-        <p class="text-muted">{t("doc.noTags", locale)}</p>
-      ) : (
-        <TagNav variant="all" tags={tags} labels={labels} />
-      )}
-      <DocHistoryArea slug="tags" locale={locale} />
-    </DocLayoutWithDefaults>
-  );
+  return <TagsIndexPageView locale={defaultLocale} />;
 }

package/templates/features/docTags/files/pages/lib/_tag-pages.tsx

@@ -0,0 +1,201 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Shared data + renderers for the doc-tags pages (#2010).
+//
+// Collapses the per-locale page pairs:
+//   pages/docs/tags/[tag].tsx   + pages/[locale]/docs/tags/[tag].tsx
+//   pages/docs/tags/index.tsx   + pages/[locale]/docs/tags/index.tsx
+// into locale-parameterized helpers. The page files stay thin shells that own
+// only their paths() param shapes; URL prefixes and the default-vs-locale
+// data path branch live here.
+//
+// Data-path branch (kept exactly as the original pages had it):
+//   - Default locale: the "docs" collection directly, filtered
+//     unlisted/draft/category_no_page before tag collection.
+//   - Non-default locale: locale-first merge with base fallback
+//     (see locale-merge.ts) — draft-filtered inputs, unlisted dropped by the
+//     merge default, category_no_page filtered AFTER the merge so a locale
+//     override carrying the flag first wins the merge (suppressing the base
+//     doc); pre-merge filtering would drop it from localeSlugSet and the
+//     unflagged base doc would resurface as a card linking to a locale route
+//     the docs route never builds.
+
+import { collectTags } from "@/utils/tags";
+import type { TagInfo } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { t, defaultLocale } from "@/config/i18n";
+import { settings } from "@/config/settings";
+import { withBase, docsUrl } from "@/utils/base";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";
+import { DocCardGrid, TagNav } from "@takazudo/zudo-doc/nav-indexing";
+import type { TagItem, TagNavLabels } 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 { DocHistoryArea } from "./_doc-history-area";
+import { BodyEndIslands } from "./_body-end-islands";
+import { stableDocs, memoizeDerived } from "./_nav-source-cache";
+import { mergeLocaleDocs } from "./locale-merge";
+
+// ---------------------------------------------------------------------------
+// Tag collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the { tag → TagInfo } map for one locale, preserving each original
+ * page's exact data path (see the module-header branch notes).
+ *
+ * Memoized on the snapshot-anchored stableDocs identity (same pattern as
+ * _nav-source-cache) so the collection bridging and tag aggregation run once
+ * per locale per build rather than once per built tag page.
+ */
+export function collectTagMapForLocale(locale: string): Map<string, TagInfo> {
+  if (locale === defaultLocale) {
+    const baseDocs = stableDocs("docs");
+    return memoizeDerived([baseDocs], "tagMap;default", () => {
+      // category_no_page index.mdx builds no route — drop it so a tag it carries
+      // doesn't render a DocCard linking to a non-existent /docs/<cat>/ page.
+      const docs = baseDocs.filter(
+        (doc) =>
+          !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page,
+      );
+      return collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    });
+  }
+
+  const baseDocs = stableDocs("docs");
+  const localeDocs = stableDocs(`docs-${locale}`);
+  return memoizeDerived([baseDocs, localeDocs], `tagMap;${locale}`, () => {
+    const { docs: mergedDocs } = mergeLocaleDocs({
+      baseDocs: baseDocs.filter((d) => !d.data.draft),
+      localeDocs: localeDocs.filter((d) => !d.data.draft),
+      applyDefaultLocaleOnlyFilter: true,
+    });
+    const docs = mergedDocs.filter((d) => !d.data.category_no_page);
+    return collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Shared renderers
+// ---------------------------------------------------------------------------
+
+/** URL prefix for a locale: "" for the default locale, "/{locale}" otherwise. */
+function localePrefix(locale: string): string {
+  return locale === defaultLocale ? "" : `/${locale}`;
+}
+
+/** Per-tag detail page (chip target). */
+export function TagDetailPageView({
+  locale,
+  tag,
+  tagInfo,
+}: {
+  locale: string;
+  tag: string;
+  tagInfo: TagInfo;
+}): JSX.Element {
+  const isDefault = locale === defaultLocale;
+  const prefix = localePrefix(locale);
+
+  const countText =
+    tagInfo.count === 1
+      ? t("doc.pageCountSingle", locale).replace("{count}", String(tagInfo.count))
+      : t("doc.pageCount", locale).replace("{count}", String(tagInfo.count));
+
+  const pageTitle = `${t("doc.taggedWith", locale)}: ${tag}`;
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    { label: t("doc.allTags", locale), href: withBase(`${prefix}/docs/tags`) },
+    { label: tag },
+  ];
+
+  const cardItems = tagInfo.docs.map((doc) => ({
+    href: docsUrl(doc.slug, locale),
+    title: doc.title,
+    description: doc.description,
+  }));
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      // The original default-locale page omitted `lang` entirely; passing
+      // undefined relies on Preact treating an undefined prop as absent.
+      lang={isDefault ? undefined : locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      // Tag segment URL-encoded — emitted href/path sites only; route params
+      // stay raw (e.g. "type:guide" → "type%3Aguide").
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags/${encodeURIComponent(tag)}`)} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-xs">{pageTitle}</h1>
+      <p class="text-muted mb-vsp-lg">{countText}</p>
+      <DocCardGrid ariaLabel={pageTitle} items={cardItems} />
+      <DocHistoryArea slug={`tags/${tag}`} locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}
+
+/** "All Tags" index page — computes the tag map at render time (matching the
+ *  original pages, which had no props from paths()). */
+export function TagsIndexPageView({ locale }: { locale: string }): JSX.Element {
+  const isDefault = locale === defaultLocale;
+  const prefix = localePrefix(locale);
+  const pageTitle = t("doc.allTags", locale);
+
+  const tagMap = collectTagMapForLocale(locale);
+
+  const labels: TagNavLabels = {
+    tags: t("doc.tags", locale),
+    taggedWith: t("doc.taggedWith", locale),
+  };
+
+  // Sort alphabetically using the page locale — matches documented tag-nav sort order.
+  const tags: TagItem[] = [...tagMap.values()]
+    .sort((a, b) => a.tag.localeCompare(b.tag, locale))
+    .map((info) => ({
+      tag: info.tag,
+      count: info.count,
+      // Tag segment URL-encoded — href sites only; route params stay raw.
+      href: withBase(`${prefix}/docs/tags/${encodeURIComponent(info.tag)}`),
+    }));
+
+  const breadcrumbItems: BreadcrumbItem[] = [
+    { label: "Docs" },
+    { label: pageTitle },
+  ];
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(pageTitle)}
+      head={<HeadWithDefaults title={pageTitle} />}
+      // Same undefined-≡-absent reliance as TagDetailPageView above.
+      lang={isDefault ? undefined : locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags`)} />}
+      breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      <h1 class="text-heading font-bold mb-vsp-lg">{pageTitle}</h1>
+      {!settings.docTags || tags.length === 0 ? (
+        <p class="text-muted">{t("doc.noTags", locale)}</p>
+      ) : (
+        <TagNav variant="all" tags={tags} labels={labels} />
+      )}
+      <DocHistoryArea slug="tags" locale={locale} />
+    </DocLayoutWithDefaults>
+  );
+}

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

@@ -23,29 +23,18 @@
 //   - Non-default locales emit /{locale}/docs/{slug}.
 //   - Locale-first merge: locale docs take priority; base EN docs fill in
 //     pages not translated yet (shown with a fallback notice).
+//
+// 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 and the param/prop shapes.
 
 import { settings } from "@/config/settings";
-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 components bag — see `pages/_mdx-components.ts`.
-import { createMdxComponents } from "../../_mdx-components";
+import { getLocaleConfig, type Locale } from "@/config/i18n";
 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 { DocHistoryArea } from "../../lib/_doc-history-area";
-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 } 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" };
 
@@ -53,8 +42,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 LocaleDocPageExtra {
   /** Content directory for the active locale (or base EN for fallbacks). */
@@ -81,8 +68,9 @@ type DocPageProps =
  *   4. Track fallback slugs for the fallback-notice banner.
  *   5. Build nav tree, compute breadcrumbs and prev/next for each entry.
  *
- * Fallback slug set drives `isFallback` which the component uses to show
- * the "not yet translated" notice (matching the Astro original).
+ * Fallback detection (`isFallback`) comes from the merge's localeSlugSet —
+ * the component uses it to show the "not yet translated" notice (matching
+ * the Astro original).
  */
 export function paths(): Array<{
   params: { locale: string; slug: string[] };
@@ -94,85 +82,36 @@ export function paths(): Array<{
   }> = [];
 
   for (const locale of Object.keys(settings.locales) as string[]) {
-    const localeConfig = settings.locales[locale];
+    const localeConfig = getLocaleConfig(locale);
     const contentDir = localeConfig?.dir ?? settings.docsDir;
 
     // Identity-stable, locale-first merge with EN fallback. The same `docs` /
     // `navDocs` / `categoryMeta` instances are reused 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: allDocs, navDocs, categoryMeta, localeSlugSet } = resolveNavSource(
-      locale,
-      undefined,
-      { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true },
-    );
-    // isFallback: page came from base docs, not the locale collection.
-    const fallbackSlugs = new Set(
-      allDocs
-        .filter((d) => !localeSlugSet.has(d.data.slug ?? d.id))
-        .map((d) => d.data.slug ?? d.id),
-    );
-
-    const tree = buildNavTree(navDocs, locale, categoryMeta);
-    const fullTree = buildNavTree(allDocs, locale, categoryMeta);
-
-    // 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;
-      // Canonical route slug via the one shared rule (@/utils/slug). `entry.id`
-      // is already `toRouteSlug(entry.slug)` (bridgeEntries → stripIndexSuffix →
-      // toRouteSlug), so this is identical to the previous `entry.id` form for
-      // every entry — but stating it explicitly removes the historical id-vs-
-      // toRouteSlug asymmetry with the EN route and the component below, all of
-      // which now yield "" for a root index (URL /{locale}/docs/ — #1891).
-      const slug = entry.data.slug ?? toRouteSlug(entry.slug);
-      const isFallback = fallbackSlugs.has(slug);
-      const entryContentDir = isFallback ? settings.docsDir : contentDir;
-
-      const navSection = getNavSectionForSlug(slug);
-      const subtree = getNavSubtree(tree, navSection);
-
-      // Prev/next + pagination overrides against THIS locale's own `tree`.
-      // Latest content (no version) — hrefs stay unversioned (no rewrite).
-      const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
-        tree,
-        flattenSubtree(subtree),
-        slug,
-        entry.data,
-      );
-
-      result.push({
-        params: { locale, slug: toSlugParams(slug) },
-        props: {
-          kind: "entry",
-          entry,
-          contentDir: entryContentDir,
-          isFallback,
-          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)) {
+    // per-page paths() 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 as Locale, undefined, {
+      applyDefaultLocaleOnlyFilter: true,
+      keepUnlisted: true,
+    });
+
+    for (const item of buildDocRouteEntries({
+      source,
+      locale: locale as Locale,
+      routeSig: `locale-docs;${locale}`,
+    })) {
+      // isFallback: page came from base docs, not the locale collection.
+      // Always false for autoIndex items (item.isFallback already is).
+      const extra: LocaleDocPageExtra = {
+        contentDir: item.isFallback ? settings.docsDir : contentDir,
+        isFallback: item.isFallback,
+      };
       result.push({
-        params: { locale, slug: toSlugParams(node.slug) },
-        props: {
-          kind: "autoIndex",
-          autoIndex: node as AutoIndexNode,
-          contentDir,
-          isFallback: false,
-          breadcrumbs: buildBreadcrumbs(fullTree, node.slug, locale),
-          prev: null,
-          next: null,
-          headings: [],
-        },
+        params: { locale, slug: item.slugParams },
+        props:
+          item.props.kind === "entry"
+            ? { ...item.props, ...extra }
+            : { ...item.props, ...extra },
       });
     }
   }
@@ -187,86 +126,9 @@ export function paths(): Array<{
 type PageArgs = DocPageProps & { params: { locale: string; slug: string[] } };
 
 export default function LocaleDocsPage(props: PageArgs): JSX.Element {
-  const { breadcrumbs, prev, next, headings, contentDir, 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);
-
-  // Latest content (no version) — keep the nav node's own docsUrl 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 locale 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} isFallback={isFallback} />
-        ) : 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={contentDir}
-            isFallback={isFallback}
-          />
-        ) : null
-      }
-    />
-  );
+  return renderDocPage(props, {
+    locale: props.params.locale as Locale,
+    isFallback: props.isFallback,
+    docHistoryContentDir: props.contentDir,
+  });
 }