create-zudo-doc 0.2.0-next.6 → 0.2.0-next.8

package/dist/constants.d.ts

@@ -5,6 +5,7 @@ export interface LightDarkPairing {
 }
 export declare const LIGHT_DARK_PAIRINGS: LightDarkPairing[];
 export declare const SINGLE_SCHEMES: string[];
+export declare const LIGHT_SCHEMES: string[];
 export interface SupportedLang {
     value: string;
     label: string;
@@ -18,3 +19,4 @@ export interface Feature {
     cliFlag: string;
 }
 export declare const FEATURES: Feature[];
+export declare const HEADER_RIGHT_LABELS: Record<string, string>;

package/dist/constants.js

@@ -55,6 +55,19 @@ export const SINGLE_SCHEMES = [
     "Gruvbox Light",
     "Ayu Light",
 ];
+// Light-only subset of SINGLE_SCHEMES. Used by the preset generator to populate
+// the "Light scheme" dropdown (dark schemes are derived as SINGLE_SCHEMES minus these).
+export const LIGHT_SCHEMES = [
+    "Default Light",
+    "GitHub Light",
+    "Catppuccin Latte",
+    "Solarized Light",
+    "Rose Pine Dawn",
+    "Atom One Light",
+    "Everforest Light",
+    "Gruvbox Light",
+    "Ayu Light",
+];
 export const SUPPORTED_LANGS = [
     { value: "en", label: "English" },
     { value: "ja", label: "Japanese" },
@@ -222,3 +235,16 @@ export const FEATURES = [
         cliFlag: "footer-taglist",
     },
 ];
+// Display labels for header-right items. Keys are canonical component/trigger
+// names from HeaderRightComponentName / HeaderRightTriggerName
+// (src/config/settings-types.ts in the host); they are deliberately not imported
+// here so constants.ts stays pure data with no cross-package dependencies.
+export const HEADER_RIGHT_LABELS = {
+    "version-switcher": "Version switcher",
+    "design-token-panel": "Design token panel (trigger)",
+    "ai-chat": "AI chat (trigger)",
+    "github-link": "GitHub link",
+    "theme-toggle": "Theme toggle",
+    search: "Search",
+    "language-switcher": "Language switcher",
+};

package/dist/scaffold.js

@@ -258,16 +258,22 @@ function generatePackageJson(choices) {
         // 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",
+        // next.33 added the opt-in hierarchical heading-ID strategy
+        // (Takazudo/zudo-front-builder#871): `markdown.features.headingIds.strategy`.
+        // The generated config + TOC builder use it via settings.headingIdStrategy.
+        // next.35 fixes resolve_links rewriting bare same-page `[text](#anchor)` /
+        // `[text](?query)` links to `/<parent-dir>/#anchor` (zudolab/zudo-doc#1948,
+        // upstream Takazudo/zudo-front-builder#875).
+        "@takazudo/zfb": "0.1.0-next.35",
+        "@takazudo/zfb-runtime": "0.1.0-next.35",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.31",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.35",
         // @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.6",
+        "@takazudo/zudo-doc": "^0.2.0-next.8",
         // 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
@@ -325,7 +331,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.6";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.8";
         // 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

@@ -130,6 +130,15 @@ export function generateSettingsFile(choices) {
     else {
         lines.push(`  designTokenPanel: false as boolean,`);
     }
+    lines.push(`  tocMinDepth: 2 as number,`);
+    lines.push(`  tocMaxDepth: 4 as number,`);
+    // Heading-ID (anchor) strategy — single source of truth shared by
+    // zfb.config.ts (markdown.features.headingIds) and the host TOC builder
+    // (pages/lib/_extract-headings.ts). "hierarchical" emits ancestor-prefixed
+    // anchors (foo / foo-moo / foo-moo-mew); "flat" is zfb's legacy scheme.
+    // Default to "hierarchical": safe for greenfield (no existing deep links to
+    // break) and the recommended scheme (upstream zfb#871).
+    lines.push(`  headingIdStrategy: "hierarchical" as "flat" | "hierarchical",`);
     if (choices.features.includes("sidebarResizer")) {
         lines.push(`  sidebarResizer: true as boolean,`);
     }

package/dist/zfb-config-gen.js

@@ -71,6 +71,8 @@ export function generateZfbConfig(choices) {
     lines.push(`    standalone: z.boolean().optional(),`);
     lines.push(`    slug: z.string().optional(),`);
     lines.push(`    generated: z.boolean().optional(),`);
+    lines.push(`    category_no_page: z.boolean().optional(),`);
+    lines.push(`    category_sort_order: z.enum(["asc", "desc"]).optional(),`);
     lines.push(`  })`);
     lines.push(`  .passthrough();`);
     lines.push(``);
@@ -152,6 +154,7 @@ export function generateZfbConfig(choices) {
         lines.push(`          options: {`);
         lines.push(`            docsDir: settings.docsDir,`);
         lines.push(`            locales: localeRecord,`);
+        lines.push(`            base: settings.base,`);
         lines.push(`          },`);
         lines.push(`        },`);
         lines.push(`      ]`);
@@ -211,6 +214,16 @@ export function generateZfbConfig(choices) {
     lines.push(`        dir: locale.dir,`);
     lines.push(`        routePrefix: \`/\${code}/docs/\`,`);
     lines.push(`      })),`);
+    lines.push(`      // Versioned collections: each version's EN dir + per-locale dirs.`);
+    lines.push(`      ...(settings.versions`);
+    lines.push(`        ? settings.versions.flatMap((version) => [`);
+    lines.push(`            { dir: version.docsDir, routePrefix: \`/v/\${version.slug}/docs/\` },`);
+    lines.push(`            ...Object.entries(version.locales ?? {}).map(([code, locale]) => ({`);
+    lines.push(`              dir: locale.dir,`);
+    lines.push(`              routePrefix: \`/v/\${version.slug}/\${code}/docs/\`,`);
+    lines.push(`            })),`);
+    lines.push(`          ])`);
+    lines.push(`        : []),`);
     lines.push(`    ],`);
     lines.push(`    onBrokenLinks: "warn",`);
     lines.push(`  },`);
@@ -271,6 +284,10 @@ export function generateZfbConfig(choices) {
     lines.push(`      imageDimensions: {},`);
     lines.push(`      // warn-only link validation — failOnBroken: false never fails the build.`);
     lines.push(`      linkValidation: { failOnBroken: false },`);
+    lines.push(`      // Heading-ID (anchor) strategy — single source of truth in`);
+    lines.push(`      // settings.headingIdStrategy, also mirrored by the host TOC builder`);
+    lines.push(`      // (pages/lib/_extract-headings.ts) so TOC anchors match rendered ids.`);
+    lines.push(`      headingIds: { strategy: settings.headingIdStrategy },`);
     lines.push(`    },`);
     lines.push(`  },`);
     lines.push(`  plugins: integrationPlugins,`);

package/package.json

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

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 type { DocPageEntry } from "./lib/doc-page-props";
 import { toRouteSlug } from "@/utils/slug";
 
 // ---------------------------------------------------------------------------
@@ -79,7 +80,7 @@ export type ZfbDocsEntry = CollectionEntry<ZfbDocsData> & {
  *   - `collection` — the collection name, for DocsEntry compat
  */
 export function getDocs(collectionName: string): ZfbDocsEntry[] {
-  const entries = getCollection(collectionName) as unknown as CollectionEntry<ZfbDocsData>[];
+  const entries = getCollection<ZfbDocsData>(collectionName);
   return entries.map((e) => ({
     ...e,
     // Astro-compat: strip a trailing `/index` from the entry id so
@@ -123,27 +124,43 @@ export function bridgeEntries<T = ZfbDocsData>(
 }
 
 /**
- * Cast ZfbDocsEntry[] to DocsEntry[] for passing to @/utils/docs utilities.
+ * Typed bridge from a raw zfb collection result to `DocPageEntry[]`.
  *
- * The types are structurally compatible: ZfbDocsEntry has every required field
- * of DocsEntry (id, collection, data, body). The optional `rendered` and
- * `filePath` fields of DocsEntry are absent but not required.
+ * This is the **single, justified** cast at the zfb/DocsEntry boundary.
+ * `CollectionEntry<ZfbDocsData> & { id, collection }` structurally satisfies
+ * `DocPageEntry` because:
+ *   - `id` and `collection` are added by `bridgeEntries`
+ *   - `data` (ZfbDocsData) structurally satisfies `DocsEntry.data` (all
+ *     required/optional fields are present; the index signature is wider)
+ *   - `body`, `slug`, `module_specifier`, `Content` are provided by
+ *     `CollectionEntry<ZfbDocsData>`
+ * The plain `as DocPageEntry[]` (not `as unknown as`) is intentional — it
+ * expresses that this is a well-understood structural subtype relationship,
+ * not an escape from the type system. The zfb type is the source of truth;
+ * DocsEntry/DocPageEntry are local compatibility shapes for @/utils/docs.
  */
-export function asDocsEntries(entries: ZfbDocsEntry[]): DocsEntry[] {
-  return entries as unknown as DocsEntry[];
+export function bridgeDocsEntries(
+  entries: ReadonlyArray<CollectionEntry<ZfbDocsData>>,
+  collectionName: string,
+): DocPageEntry[] {
+  return bridgeEntries(entries, collectionName) as DocPageEntry[];
 }
 
 /**
  * One-shot helper for paths()/render-time pages that just need a
- * `DocsEntry[]` for `@/utils/docs` consumption — wraps `getDocs` and
- * the `asDocsEntries` cast so call sites stay one-line. Use this from
- * any page that previously did
+ * `DocsEntry[]` for `@/utils/docs` consumption — wraps `getDocs` so
+ * call sites stay one-line. Use this from any page that previously did
  * `getCollection("docs") as unknown as DocsEntry[]` — that idiom
  * silently dropped the `id`/`collection` fields the utility helpers
  * read, which threw `Cannot read properties of undefined` at runtime.
+ *
+ * `ZfbDocsEntry` structurally satisfies `DocsEntry`: it carries `id`,
+ * `collection`, `data` (ZfbDocsData satisfies DocsEntry.data field-for-
+ * field), `body`, plus the zfb-specific extras (`slug`, `Content`, etc.)
+ * that DocsEntry does not require.
  */
 export function loadDocs(collectionName: string): DocsEntry[] {
-  return asDocsEntries(getDocs(collectionName));
+  return getDocs(collectionName);
 }
 
 /**

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

@@ -22,44 +22,32 @@
 // Locale: defaultLocale (EN). Non-default locales are handled by
 // pages/[locale]/docs/[[...slug]].tsx.
 
-import type { DocsEntry } from "@/types/docs-entry";
 import { settings } from "@/config/settings";
 import { defaultLocale } from "@/config/i18n";
-import { docsUrl } from "@/utils/base";
+import { docsUrl, absoluteUrl } from "@/utils/base";
 import {
   buildNavTree,
   buildBreadcrumbs,
-  flattenTree,
-  findNode,
   collectAutoIndexNodes,
   type NavNode,
 } from "@/utils/docs";
 import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
 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";
 // 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 { FooterWithDefaults } from "../lib/_footer-with-defaults";
 import { DocHistoryArea } from "../lib/_doc-history-area";
 import { DocMetainfoArea } from "../lib/_doc-metainfo-area";
-import { SidebarWithDefaults } from "../lib/_sidebar-with-defaults";
-import { HeaderWithDefaults } from "../lib/_header-with-defaults";
-import { HeadWithDefaults } from "../lib/_head-with-defaults";
-import { composeMetaTitle } from "../lib/_compose-meta-title";
 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 { 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";
+import { DocPageShell } from "../lib/_doc-page-shell";
+import { resolveDocPrevNext, flattenSubtree } from "../lib/_doc-route-paths";
 
 export const frontmatter = { title: "Docs" };
 
@@ -94,40 +82,31 @@ export function paths(): Array<{
   const { docs, navDocs, categoryMeta } = resolveNavSource(locale, undefined);
 
   // Nav docs: exclude unlisted (for sidebar/prev-next) but keep for breadcrumbs
-  const tree = buildNavTree(navDocs as unknown as DocsEntry[], locale, categoryMeta);
+  const tree = buildNavTree(navDocs, locale, categoryMeta);
   // Full tree (including unlisted) for accurate breadcrumbs
-  const fullTree = buildNavTree(docs as unknown as DocsEntry[], locale, categoryMeta);
+  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);
-    const flat = flattenTree(subtree);
-    const idx = flat.findIndex((n) => n.slug === slug);
 
-    let prevNode = idx > 0 ? flat[idx - 1] ?? null : null;
-    let nextNode = idx >= 0 && idx < flat.length - 1 ? flat[idx + 1] ?? null : null;
-
-    // Frontmatter pagination overrides
-    if (entry.data.pagination_prev !== undefined) {
-      if (entry.data.pagination_prev === null) {
-        prevNode = null;
-      } else {
-        const found = findNode(tree, entry.data.pagination_prev);
-        prevNode = found ?? prevNode;
-      }
-    }
-    if (entry.data.pagination_next !== undefined) {
-      if (entry.data.pagination_next === null) {
-        nextNode = null;
-      } else {
-        const found = findNode(tree, entry.data.pagination_next);
-        nextNode = found ?? nextNode;
-      }
-    }
+    // 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) },
@@ -181,7 +160,8 @@ export default function DocsPage(props: PageArgs): JSX.Element {
   // locale so CategoryNav/CategoryTreeNav/SiteTreeNav query the right collection.
   const components = createMdxComponents(locale);
 
-  // Resolve child hrefs for auto-index pages
+  // 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)
@@ -191,12 +171,9 @@ export default function DocsPage(props: PageArgs): JSX.Element {
         }))
     : [];
 
-  // Canonical URL — only when siteUrl is configured. pageUrl is the
-  // base-prefixed path for this page without the siteUrl origin.
-  const pageUrl = docsUrl(slug, locale);
-  const canonical = settings.siteUrl
-    ? settings.siteUrl.replace(/\/$/, "") + pageUrl
-    : undefined;
+  // 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 —
@@ -209,95 +186,46 @@ export default function DocsPage(props: PageArgs): JSX.Element {
     : `sidebar-${locale}-${navSection ?? "default"}`;
 
   return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(title)}
+    <DocPageShell
+      kind={props.kind}
+      locale={locale}
+      slug={slug}
+      title={title}
       description={description}
-      head={<HeadWithDefaults title={title} description={description} canonical={canonical} />}
-      lang={locale}
-      noindex={settings.noindex}
-      hideSidebar={hideSidebar}
-      hideToc={props.kind === "entry" ? props.entry.data.hide_toc : undefined}
-      headings={headings}
       canonical={canonical}
+      breadcrumbs={breadcrumbs}
+      prev={prev}
+      next={next}
+      headings={headings}
+      navSection={navSection}
       sidebarPersistKey={sidebarPersistKey}
-      headerOverride={
-        <HeaderWithDefaults
-          lang={locale}
-          currentSlug={slug}
-          navSection={getNavSectionForSlug(slug)}
-          currentPath={docsUrl(slug, locale)}
-        />
+      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
       }
-      breadcrumbOverride={
-        breadcrumbs.length > 0 ? (
-          <Breadcrumb
-            items={breadcrumbs}
-            rightSlot={buildInlineVersionSwitcher(slug, locale)}
-          />
+      contentHeaderSlot={
+        props.kind === "entry" ? (
+          <DocContentHeader entry={props.entry} slug={slug} locale={locale} />
         ) : undefined
       }
-      sidebarOverride={
-        <SidebarWithDefaults
-          currentSlug={slug}
-          lang={locale}
-          navSection={getNavSectionForSlug(slug)}
-          currentPath={docsUrl(slug, locale)}
-        />
+      contentSlot={
+        props.kind === "entry" ? <props.entry.Content components={components} /> : undefined
       }
-      afterSidebar={<SidebarPrepaint />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<DocBodyEnd />}
-    >
-      {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
-           (.zd-content > :where(* + *) { margin-top: var(--flow-space) }).
-           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">{props.autoIndex.label}</h1>
-
-          {/* Build-time date block — chrome parity (#1461). Auto-index pages
-              previously rendered without doc-meta; reference site shows it on
-              every docs page. The component returns null when no manifest
-              entry exists for this slug. */}
-          <DocMetainfoArea slug={slug} locale={locale} />
-
-          {props.autoIndex.description && (
-            <p class="mb-vsp-lg text-title text-muted">
-              {props.autoIndex.description}
-            </p>
-          )}
-          <NavCardGrid children={autoIndexChildren} />
-        </>
-      ) : (
-        /* Regular doc page. Fragment (not <div>) for the same reason as
-           the auto-index branch above — see #1460. */
-        <>
-          <DocContentHeader entry={props.entry} slug={slug} locale={locale} />
-
-          {/* MDX content rendered via zfb's Content bridge */}
-          <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. */}
-          <DocPager prev={prev} next={next} locale={locale} />
-
-          {/* Document utilities (revision history + view-source link) — skipped for unlisted pages */}
-          {!props.entry.data.unlisted && (
-            <DocHistoryArea
-              slug={slug}
-              locale={locale}
-              entrySlug={props.entry.slug}
-              contentDir={settings.docsDir}
-            />
-          )}
-        </>
-      )}
-    </DocLayoutWithDefaults>
+      docHistorySlot={
+        props.kind === "entry" && !props.entry.data.unlisted ? (
+          <DocHistoryArea
+            slug={slug}
+            locale={locale}
+            entrySlug={props.entry.slug}
+            contentDir={settings.docsDir}
+          />
+        ) : null
+      }
+    />
   );
 }

package/templates/base/pages/index.tsx

@@ -46,8 +46,10 @@ export default function IndexPage(): JSX.Element {
   const categoryOrder = getCategoryOrder();
   const groupedTree = groupSatelliteNodes(tree, categoryOrder);
 
+  // Drop category_no_page index files so the count matches the number of tag
+  // pages actually built (the tag routes exclude them too).
   const tagCount = collectTags(
-    navDocs,
+    navDocs.filter((d) => !d.data.category_no_page),
     (id, data) => data.slug ?? toRouteSlug(id),
   ).size;
 

package/templates/base/pages/lib/_category-nav.tsx

@@ -21,9 +21,9 @@ import type { NavNode as V2NavNode } from "@takazudo/zudo-doc/nav-indexing/types
 import {
   buildNavTree,
   findNode,
+  firstRoutedHref,
 } from "@/utils/docs";
 import { defaultLocale, type Locale } from "@/config/i18n";
-import { docsUrl } from "@/utils/base";
 import { resolveNavSource } from "./_nav-source-docs";
 
 export interface CategoryNavWrapperProps {
@@ -39,8 +39,9 @@ export interface CategoryNavWrapperProps {
    * of "claude", not children). Each slug is resolved to its nav node; nodes
    * not found in the tree are silently skipped.
    *
-   * For nodes with noPage=true (no index.mdx), the href falls back to the
-   * auto-generated category index URL via docsUrl(slug, lang).
+   * A `category_no_page` category has no route of its own, so its card links to
+   * the first routed descendant page (via firstRoutedHref); categories with no
+   * reachable page are skipped rather than emitting a dead link.
    */
   categories?: string[];
   /**
@@ -61,8 +62,8 @@ export interface CategoryNavWrapperProps {
  * - `categories`: resolves an explicit list of top-level slugs as cards.
  *   Use this when the target categories are siblings in the nav tree rather
  *   than children of a common parent (e.g. claude-md / claude-skills are
- *   top-level peers of claude, not children of it). Nodes with noPage=true
- *   get their href computed via docsUrl() since auto-index pages exist.
+ *   top-level peers of claude, not children of it). A noPage category card
+ *   links to its first routed descendant page (it has no route of its own).
  *
  * Returns null when no visible children are resolved.
  */
@@ -85,14 +86,17 @@ export function CategoryNavWrapper({
   let children: V2NavNode[];
 
   if (categories !== undefined) {
-    // Explicit slug list mode: resolve each slug to its nav node and build
-    // a card for it. noPage nodes have no href in the tree but their
-    // auto-generated category index page is reachable via docsUrl().
+    // Explicit slug list mode: resolve each slug to its nav node and build a
+    // card for it. A `category_no_page` category has no route of its own
+    // (collectAutoIndexNodes skips noPage nodes), so its card links to the
+    // first routed descendant page; categories with no reachable page are
+    // skipped rather than emitting a dead link.
     children = categories
       .map((slug): V2NavNode | null => {
         const node = findNode(tree, slug);
         if (!node) return null;
-        const href = node.href ?? docsUrl(slug, locale);
+        const href = node.href ?? firstRoutedHref(node);
+        if (!href) return null;
         return {
           label: node.label,
           description: node.description,

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

@@ -67,6 +67,17 @@ interface DocHistoryAreaProps {
    * view-source GitHub URL. Omit to suppress the view-source link.
    */
   contentDir?: 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 history data-path derivations use defaultLocale so the island
+   * fetches the correct bare-slug JSON and the SSR manifest lookup hits
+   * the bare key — both of which only exist for EN-origin files.
+   * Display labels (t() calls) still use the active locale so JA users
+   * see JA labels on fallback pages. Omit (or false) for translated pages
+   * and all other call sites (EN route, tag pages) — behavior unchanged.
+   */
+  isFallback?: boolean;
 }
 
 /**
@@ -93,6 +104,7 @@ export function DocHistoryArea({
   locale,
   entrySlug,
   contentDir,
+  isFallback,
 }: DocHistoryAreaProps): VNode | null {
   if (!settings.docHistory) return null;
 
@@ -106,11 +118,18 @@ export function DocHistoryArea({
   // collectContentFiles walk in packages/doc-history-server. (#1891)
   const historySlug = toHistorySlug(slug);
 
+  // On EN-fallback locale pages the history data exists only at the bare
+  // (non-locale-prefixed) path — the prebuild/server writes locale-prefixed
+  // keys/paths only for files physically present in the locale collection.
+  // Use defaultLocale for data lookups when isFallback is true; keep locale
+  // for all display label calls (t()) so JA users see JA labels.
+  const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
+
   // Look up the build-time manifest entry for this page. The composedSlug
   // matches the key written by the prebuild step: bare slug for the default
   // locale, "<localeKey>/<slug>" for non-default locales.
   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];
 
@@ -120,7 +139,8 @@ export function DocHistoryArea({
   const historyLabel = t("doc.history", locale);
 
   // Real-component props — locale omitted for the default locale.
-  const docHistoryLocale = locale === defaultLocale ? undefined : locale;
+  // Use effectiveHistoryLocale so fallback pages fetch the bare (non-ja/) path.
+  const docHistoryLocale = effectiveHistoryLocale === defaultLocale ? undefined : effectiveHistoryLocale;
   const docHistoryBasePath = settings.base ?? "/";
 
   // Build the SSR fallback with only the sr-only metadata block so the

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

@@ -13,9 +13,10 @@
 // (b11-2 pattern).
 //
 // Date formatting uses Intl.DateTimeFormat (browser-safe). We do NOT
-// import `formatDate` from `src/utils/git-info.ts` because that module
-// has top-level Node.js imports (`execFileSync`, `existsSync`) that
-// would be dragged into the client bundle — the B-11 lesson.
+// import the old `formatDate` from `src/utils/git-info.ts` — that module
+// carried top-level Node.js imports (`execFileSync`, `existsSync`) that
+// would be dragged into the client bundle (the B-11 lesson). That file
+// was removed in S1 cleanup (#1928); the mirror below is the canonical copy.
 //
 // Labels are resolved from the project's i18n table so non-default
 // locales (e.g. /ja/) get translated "作成" / "更新" strings.
@@ -36,9 +37,8 @@ import { toHistorySlug } from "@/utils/slug";
 import docHistoryMeta from "#doc-history-meta";
 
 // BCP-47 locale tag mapping used by Intl.DateTimeFormat.
-// Kept in sync with `src/utils/git-info.ts` manually; we cannot import
-// that module here because it carries top-level Node.js imports
-// (`execFileSync`, `existsSync`) — the B-11 lesson applies here too.
+// Originally mirrored from `src/utils/git-info.ts` (removed in S1 #1928).
+// The formatDate function below is the stable copy; kept in sync manually.
 const LOCALE_TO_BCP47: Record<string, string> = {
   en: "en-US",
   ja: "ja-JP",