create-zudo-doc 0.2.0 → 0.2.1

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}

package/templates/base/pages/lib/_doc-route-entries.ts

@@ -0,0 +1,188 @@
+// Shared, memoized route-entry builder for the 4 doc catch-all routes.
+//
+// Extracted (#2010) from the ~85%-duplicated paths() bodies 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 resolves its own identity-stable nav source (resolveNavSource /
+// resolveVersionedLocaleSource) and URL closure, then delegates the per-entry
+// derived-data work here. The result is memoized with the #1902 WeakMap
+// pattern (memoizeDerived keyed on the identity-stable `source.docs` array +
+// a per-route signature), so the expensive per-entry work — extractHeadings,
+// buildBreadcrumbs, prev/next resolution — runs ONCE per entry per build,
+// not once per entry per page (zfb re-invokes paths() once per built page).
+//
+// Versioned-vs-latest behavior is keyed on the presence of `urlFor` (#1916):
+//   - `urlFor` set (versioned routes): breadcrumbs resolve against the NAV
+//     tree (unlisted excluded) with crumbs remapped to the versioned URL
+//     space; prev/next hrefs are rewritten through the closure; auto-index
+//     child-card hrefs are ALWAYS remapped to the versioned URL.
+//   - `urlFor` unset (latest routes): breadcrumbs resolve against the FULL
+//     tree (unlisted included, for accurate crumbs); prev/next and child
+//     hrefs keep the latest `docsUrl` already baked into the nav nodes.
+// These two behaviors travel together by construction: only versioned routes
+// own a versioned URL closure (see _doc-route-paths.ts for the #1916
+// rationale on why latest routes must never receive one).
+
+import {
+  buildNavTree,
+  buildBreadcrumbs,
+  collectAutoIndexNodes,
+  type NavNode,
+} from "@/utils/docs";
+import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
+import { toRouteSlug, toSlugParams } from "@/utils/slug";
+import type { Locale } from "@/config/i18n";
+import { extractHeadings } from "./_extract-headings";
+import type { AutoIndexNode, DocPageBaseProps } from "./doc-page-props";
+import { memoizeDerived } from "./_nav-source-cache";
+import type { NavSourceDocs } from "./_nav-source-docs";
+import {
+  resolveDocPrevNext,
+  flattenSubtree,
+  rewriteNavHref,
+  remapNavChildHrefs,
+} from "./_doc-route-paths";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** One enumerated doc route: a content entry or an auto-generated category
+ *  index, with all per-page derived data pre-computed. */
+export interface DocRouteEntry {
+  /** Canonical route slug ("" for the docs root index — #1891). */
+  slug: string;
+  /** Optional-catchall params array — `toSlugParams(slug)` ([] for the root). */
+  slugParams: string[];
+  /**
+   * True when the entry came from the base collection rather than the locale
+   * collection (`!localeSlugSet.has(slug)`). Only meaningful on routes whose
+   * nav source performs a locale merge — routes without one (default-locale /
+   * versioned-EN, where `localeSlugSet` is empty) must ignore this field.
+   * Always false for autoIndex items.
+   */
+  isFallback: boolean;
+  /** Shared page props (kind/entry/autoIndex/breadcrumbs/prev/next/headings). */
+  props: DocPageBaseProps;
+}
+
+export interface BuildDocRouteEntriesArgs {
+  /** Identity-stable nav source for this route's (locale, version) context —
+   *  from resolveNavSource / resolveVersionedLocaleSource. The memo is keyed
+   *  on `source.docs` identity, so the source MUST come from those resolvers
+   *  (a fresh array defeats the memo — harmless, but recomputes per call). */
+  source: NavSourceDocs;
+  /** Active locale for nav-tree labels and breadcrumbs. */
+  locale: Locale;
+  /**
+   * Unique memo signature for this route context. Each route file passes its
+   * own prefix plus the loop variables (version slug / locale), e.g.
+   * "docs;en", "locale-docs;ja", "v-docs;1.0", "v-locale-docs;1.0;ja" —
+   * call sites that share a docs array identity must never collide on a key.
+   */
+  routeSig: string;
+  /** Versioned URL closure bound to the route's version (+ locale). Presence
+   *  switches the versioned behaviors documented in the module header. */
+  urlFor?: (slug: string) => string;
+}
+
+// ---------------------------------------------------------------------------
+// buildDocRouteEntries
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate all doc routes (content entries + auto-index pages) for one
+ * (locale, version) context, with per-entry derived data pre-computed.
+ *
+ * Memoized per build on the identity-stable `source.docs` array (#1902), so
+ * repeated paths() invocations across the route's many pages return the SAME
+ * array instance without redoing the per-entry work. In the no-snapshot
+ * fallback path (unit tests / direct Node runs) `source.docs` is a fresh
+ * array per call, so the memo misses and this computes fresh — matching the
+ * deliberate no-memo policy in _nav-source-cache.ts.
+ */
+export function buildDocRouteEntries(
+  args: BuildDocRouteEntriesArgs,
+): DocRouteEntry[] {
+  const { source, locale, routeSig, urlFor } = args;
+
+  return memoizeDerived([source.docs], `docRouteEntries;${routeSig}`, () => {
+    const { docs, navDocs, categoryMeta, localeSlugSet } = source;
+
+    // Nav docs: exclude unlisted (for sidebar/prev-next) but keep for breadcrumbs
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+    // Breadcrumb tree: latest routes use the full tree (including unlisted)
+    // for accurate crumbs; versioned routes resolve crumbs against the nav
+    // tree itself (#1916 #1).
+    const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
+
+    const result: DocRouteEntry[] = [];
+
+    // 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;
+      // Canonical route slug via the one shared rule (@/utils/slug) — yields
+      // "" for a root index (URL /docs/ — #1891).
+      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`; versioned routes then rewrite the hrefs through
+      // their urlFor closure (latest routes pass it through unchanged).
+      const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
+        tree,
+        flattenSubtree(subtree),
+        slug,
+        entry.data,
+      );
+
+      result.push({
+        slug,
+        slugParams: toSlugParams(slug),
+        isFallback: !localeSlugSet.has(slug),
+        props: {
+          kind: "entry",
+          entry,
+          breadcrumbs: buildBreadcrumbs(breadcrumbTree, slug, locale, urlFor),
+          prev: rewriteNavHref(prevNode, urlFor),
+          next: rewriteNavHref(nextNode, urlFor),
+          headings: extractHeadings(entry.body ?? ""),
+        },
+      });
+    }
+
+    // Auto-generated index pages for categories without index.mdx
+    for (const node of collectAutoIndexNodes(tree)) {
+      result.push({
+        slug: node.slug,
+        slugParams: toSlugParams(node.slug),
+        isFallback: false,
+        props: {
+          kind: "autoIndex",
+          autoIndex: urlFor
+            ? // #1916 #2: child-card hrefs ALWAYS resolve to the versioned URL.
+              ({
+                ...node,
+                children: remapNavChildHrefs(node.children, urlFor) as NavNode[],
+              } as AutoIndexNode)
+            : (node as AutoIndexNode),
+          breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
+          prev: null,
+          next: null,
+          headings: [],
+        },
+      });
+    }
+
+    return result;
+  });
+}

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

@@ -34,12 +34,17 @@ import { DocTags } from "@takazudo/zudo-doc/metainfo";
  *
  * Inlined from _footer-with-defaults.tsx `tagHref` — not extracted to avoid
  * ripple (spec rule: no opportunistic refactor on tagHref extraction).
+ *
+ * The tag segment is URL-encoded at the href site only — route params stay
+ * raw, so the built output dir keeps the raw tag name and the server decodes
+ * the percent-encoded href back to it (e.g. "type:guide" → "type%3Aguide").
  */
 function tagHref(tag: string, locale: string): string {
+  const encoded = encodeURIComponent(tag);
   const path =
     locale === defaultLocale
-      ? `/docs/tags/${tag}`
-      : `/${locale}/docs/tags/${tag}`;
+      ? `/docs/tags/${encoded}`
+      : `/${locale}/docs/tags/${encoded}`;
   return withBase(path);
 }