create-zudo-doc 0.1.0

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

@@ -0,0 +1,178 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locale-aware DocHistory area wrapper for the zfb doc pages.
+//
+// Mirrors the Phase B-1 pattern used by _footer-with-defaults.tsx: this
+// wrapper lives in pages/lib/ with a leading underscore so the zfb router
+// skips it as a page module, while the two doc-page modules
+// (docs/[...slug].tsx and [locale]/docs/[...slug].tsx) import it directly.
+// It gates on settings.docHistory, resolves the correct locale prop
+// (omitted for the default locale, matching the doc-history fetch-path
+// branch in src/components/doc-history.tsx), and passes the assembled
+// island into BodyFootUtilArea — restoring the
+// `<section aria-label="Document utilities">` landmark and its Revision
+// History heading in the SSG output for all zfb doc routes.
+//
+// Wave 8 (Path A — super-epic #1333 / child epic #1355): the doc-history
+// island is now built right here using zfb's native `<Island ssrFallback>`
+// API with the real DocHistory component imported from
+// `@/components/doc-history`. Previously this file passed
+// DocHistoryIslandProps to BodyFootUtilArea, which fed an SSR-skip
+// wrapper that did not import the real component — the orphan-component
+// bug that left the marker un-bundled. The host-side import here is the
+// page → real-component chain zfb's island scanner walks.
+
+import type { VNode } from "preact";
+import { Island } from "@takazudo/zfb";
+import { settings } from "@/config/settings";
+import { defaultLocale, t } from "@/config/i18n";
+import { BodyFootUtilArea } from "@takazudo/zudo-doc/body-foot-util";
+import { buildGitHubSourceUrl } from "@/utils/github";
+import { DocHistory } from "@/components/doc-history";
+// SSR author + date metadata comes from `.zfb/doc-history-meta.json`, a
+// build-time manifest emitted by `scripts/zfb-prebuild.mjs` (step 2:
+// doc-history-meta) before `zfb build` runs. esbuild inlines the JSON
+// statically so no Node-only `fs` code reaches the client bundle.
+// The `#doc-history-meta` alias is defined in tsconfig.json and resolves
+// to the absolute path of `.zfb/doc-history-meta.json` — this is needed
+// because the zfb bundler builds pages from a shadow tree; relative paths
+// across the shadow boundary would resolve to the wrong location.
+import docHistoryMeta from "#doc-history-meta";
+
+// Set explicit `displayName` on the named-export DocHistory so zfb's
+// `captureComponentName` produces a stable marker even after the SSR
+// pipeline runs the component through a function-name-rewriting layer.
+// (DocHistory is `export function DocHistory(...)` — `name` is already
+// "DocHistory" but the explicit assignment is a guard for production
+// minification regressions, mirroring the BodyEndIslands helper.)
+(DocHistory as { displayName?: string }).displayName = "DocHistory";
+
+interface DocHistoryAreaProps {
+  /** Page slug, e.g. "getting-started/intro". */
+  slug: string;
+  /** Active locale string, e.g. "en", "ja". */
+  locale: string;
+  /**
+   * 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.
+   * Omit for auto-index pages (no underlying MDX file) — sourceUrl
+   * will be suppressed automatically.
+   */
+  entrySlug?: string;
+  /**
+   * Content directory for the active locale, e.g. "src/content/docs"
+   * or "src/content/docs-ja". Combined with entrySlug to build the
+   * view-source GitHub URL. Omit to suppress the view-source link.
+   */
+  contentDir?: string;
+}
+
+/**
+ * Renders the `<BodyFootUtilArea>` shell with a doc-history island when
+ * `settings.docHistory` is enabled.  Returns null otherwise so no empty
+ * landmark appears on pages where history is disabled.
+ *
+ * The locale prop is forwarded to the real DocHistory component only for
+ * non-default locales — the history JSON server stores default-locale
+ * files without a locale path segment (matching the fetch-path branch in
+ * doc-history.tsx).
+ *
+ * When entrySlug + contentDir are both provided and settings.bodyFootUtilArea
+ * has viewSourceLink enabled, computes sourceUrl via buildGitHubSourceUrl and
+ * resolves the i18n label for the active locale — keeping the v2 component
+ * oblivious to project settings (host-side computation, B-8-2).
+ *
+ * The SSR fallback for the doc-history island is built from git metadata
+ * (author name, created/updated dates) so that static HTML contains the
+ * author marker before JS hydration, visible to screen readers and crawlers.
+ */
+export function DocHistoryArea({
+  slug,
+  locale,
+  entrySlug,
+  contentDir,
+}: DocHistoryAreaProps): VNode | null {
+  if (!settings.docHistory) return null;
+
+  // 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 ? slug : `${locale}/${slug}`;
+  type MetaEntry = { author: string; createdDate: string; updatedDate: string };
+  const meta = (docHistoryMeta as Record<string, MetaEntry>)[composedSlug];
+
+  // Locale-aware labels for the SSR fallback.
+  const createdLabel = t("doc.created", locale);
+  const updatedLabel = t("doc.updated", locale);
+  const historyLabel = t("doc.history", locale);
+
+  // Real-component props — locale omitted for the default locale.
+  const docHistoryLocale = locale === defaultLocale ? undefined : locale;
+  const docHistoryBasePath = settings.base ?? "/";
+
+  // Build the SSR fallback with only the sr-only metadata block so the
+  // author marker and Created/Updated labels are present in SSG output
+  // before JS hydration, discoverable by screen readers and crawlers.
+  // The visible "History" trigger button is NOT included here — DocHistory
+  // renders its own trigger after hydration, and including one in the
+  // ssrFallback as well caused a duplicate button in the DOM because
+  // Preact's render() does not reliably remove static ssrFallback HTML
+  // before mounting the new component output (same wrapper-self-Island
+  // pattern fixed for Toc/Sidebar in commit 4014cdc).
+  const author = meta?.author;
+  const createdDate = meta?.createdDate;
+  const updatedDate = meta?.updatedDate;
+
+  const fallback: VNode = (
+    <div class="sr-only">
+      {author && <span>{author}</span>}
+      <span>
+        {createdLabel}
+        {createdDate ? `: ${createdDate}` : ""}
+      </span>
+      <span>
+        {updatedLabel}
+        {updatedDate ? `: ${updatedDate}` : ""}
+      </span>
+    </div>
+  );
+
+  // Compose the SSR-skip island with zfb's native `<Island ssrFallback>` API.
+  // The page → this file → real DocHistory import chain is what the scanner
+  // walks; the marker emitted is "DocHistory" via captureComponentName.
+  const docHistoryIsland = Island({
+    when: "idle",
+    ssrFallback: fallback,
+    children: (
+      <DocHistory
+        slug={slug}
+        locale={docHistoryLocale}
+        basePath={docHistoryBasePath}
+      />
+    ),
+  }) as unknown as VNode;
+
+  // Compute the view-source GitHub URL host-side so the v2 BodyFootUtilArea
+  // component stays oblivious to project settings. Guards mirror the legacy
+  // body-foot-util-area.astro: gate on bodyFootUtilArea.viewSourceLink, and
+  // require both entrySlug and contentDir (auto-index pages pass neither).
+  const utilSettings = settings.bodyFootUtilArea;
+  const sourceUrl =
+    utilSettings && utilSettings.viewSourceLink && entrySlug && contentDir
+      ? buildGitHubSourceUrl(contentDir, entrySlug + ".mdx")
+      : null;
+
+  // Resolve the i18n label host-side; pass the result so the v2 component
+  // stays framework-agnostic. Falls back to the EN default when locale has
+  // no translation (see DEFAULT_VIEW_SOURCE_LABEL in the v2 package).
+  const viewSourceLabel = t("doc.viewSource", locale);
+
+  return (
+    <BodyFootUtilArea
+      docHistoryIsland={docHistoryIsland}
+      sourceUrl={sourceUrl}
+      viewSourceLabel={viewSourceLabel}
+    />
+  );
+}

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

@@ -0,0 +1,100 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locale-aware DocMetainfo area wrapper for the zfb doc pages.
+//
+// Renders the visible date block (created / updated dates + author)
+// between the article <h1> and the description paragraph, mirroring the
+// position of the legacy `doc-metainfo.astro` in the Astro layout.
+//
+// Data source: `.zfb/doc-history-meta.json`, a build-time manifest
+// emitted by `scripts/zfb-prebuild.mjs` before `zfb build` runs.
+// esbuild inlines the JSON statically so no Node.js `fs` code reaches
+// the client bundle — the same approach used by `_doc-history-area.tsx`
+// (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.
+//
+// Labels are resolved from the project's i18n table so non-default
+// locales (e.g. /ja/) get translated "作成" / "更新" strings.
+
+import type { VNode } from "preact";
+import { settings } from "@/config/settings";
+import { defaultLocale, t } from "@/config/i18n";
+import { DocMetainfo } from "@takazudo/zudo-doc/metainfo";
+// SSR author + date metadata comes from `.zfb/doc-history-meta.json`, a
+// build-time manifest emitted by `scripts/zfb-prebuild.mjs` (step 2:
+// doc-history-meta) before `zfb build` runs. esbuild inlines the JSON
+// statically so no Node-only `fs` code reaches the client bundle.
+// The `#doc-history-meta` alias is defined in tsconfig.json and resolves
+// to the absolute path of `.zfb/doc-history-meta.json` — this is needed
+// because the zfb bundler builds pages from a shadow tree; relative paths
+// across the shadow boundary would resolve to the wrong location.
+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.
+const LOCALE_TO_BCP47: Record<string, string> = {
+  en: "en-US",
+  ja: "ja-JP",
+  de: "de-DE",
+};
+
+/** Format an ISO date string for display, respecting the active locale. */
+function formatDate(isoDate: string, locale: string): string {
+  const d = new Date(isoDate);
+  if (isNaN(d.getTime())) return isoDate;
+  return d.toLocaleDateString(LOCALE_TO_BCP47[locale] ?? "en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+interface DocMetainfoAreaProps {
+  /** Page slug, e.g. "getting-started/intro". */
+  slug: string;
+  /** Active locale string, e.g. "en", "ja". */
+  locale: string;
+}
+
+/**
+ * Renders the visible date block (Created / Updated / Author) when
+ * `settings.docMetainfo` is enabled and the build-time manifest has an
+ * entry for the active page.
+ *
+ * Returns null when `docMetainfo` is disabled, the page is untracked
+ * (no manifest entry), or the manifest was generated in a shallow clone
+ * (`SKIP_DOC_HISTORY=1` → empty JSON).
+ *
+ * The component is intentionally server-render-only: it emits static
+ * HTML from build-time data and has no client JS footprint. It sits
+ * between `<h1>` and the description `<p>`, mirroring the legacy Astro
+ * `doc-metainfo.astro` placement.
+ */
+export function DocMetainfoArea({ slug, locale }: DocMetainfoAreaProps): VNode | null {
+  if (!settings.docMetainfo) return null;
+
+  // Key format: bare slug for default locale, "<locale>/<slug>" for others.
+  // Matches the prebuild step's composedSlug logic in scripts/zfb-prebuild.mjs.
+  const composedSlug = locale === defaultLocale ? slug : `${locale}/${slug}`;
+
+  type MetaEntry = { author: string; createdDate: string; updatedDate: string };
+  const meta = (docHistoryMeta as Record<string, MetaEntry>)[composedSlug];
+
+  if (!meta) return null;
+
+  return (
+    <DocMetainfo
+      createdAt={meta.createdDate ? formatDate(meta.createdDate, locale) : null}
+      updatedAt={meta.updatedDate ? formatDate(meta.updatedDate, locale) : null}
+      author={meta.author || null}
+      createdLabel={t("doc.created", locale)}
+      updatedLabel={t("doc.updated", locale)}
+    />
+  );
+}

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

@@ -0,0 +1,89 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locale-aware DocTags area wrapper for the zfb doc pages.
+//
+// Renders the page-level tag chips (e.g. "Tags: #customization") between
+// the DocMetainfo block and the description paragraph, mirroring the
+// position of the legacy `doc-tags.astro` in the Astro layout.
+//
+// Restoration of a Astro→zfb migration regression: the DocTags component
+// was correctly ported into @takazudo/zudo-doc/metainfo/doc-tags.tsx
+// but no page template wired it up (#1658, closes #1508).
+//
+// tagHref logic: inlined from _footer-with-defaults.tsx (the `tagHref`
+// helper there). Extraction was considered but would cause ripple in the
+// footer file and its callers — per the spec's "no opportunistic refactor"
+// rule, a local copy is used here instead.
+//
+// i18n: both `doc.tags` and `doc.taggedWith` are confirmed present for all
+// project locales (en, ja, de) in src/config/i18n.ts — no fallback needed.
+
+import type { VNode } from "preact";
+import { settings } from "@/config/settings";
+import { defaultLocale, t } from "@/config/i18n";
+import { withBase } from "@/utils/base";
+import { resolvePageTags } from "@/utils/tags";
+import { DocTags } from "@takazudo/zudo-doc/metainfo";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the base-prefixed tag detail page href for the given locale.
+ *
+ * Inlined from _footer-with-defaults.tsx `tagHref` — not extracted to avoid
+ * ripple (spec rule: no opportunistic refactor on tagHref extraction).
+ */
+function tagHref(tag: string, locale: string): string {
+  const path =
+    locale === defaultLocale
+      ? `/docs/tags/${tag}`
+      : `/${locale}/docs/tags/${tag}`;
+  return withBase(path);
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+interface DocTagsAreaProps {
+  /** Page slug, e.g. "guides/sidebar". */
+  slug: string;
+  /** Active locale string, e.g. "en", "ja". */
+  locale: string;
+  /** Raw tag strings from the page frontmatter (entry.data.tags). */
+  tags: readonly string[] | undefined;
+}
+
+/**
+ * Renders the page-level tag chip block when `settings.docTags` is enabled
+ * and the page has at least one resolved (non-deprecated) tag.
+ *
+ * Returns null when `docTags` is disabled, the page has no tags, or all
+ * raw tags resolve to deprecated entries.
+ *
+ * Placement is "after-title" to match the legacy `doc-tags.astro` position
+ * (between the date block and description paragraph).
+ */
+export function DocTagsArea({ locale, tags }: DocTagsAreaProps): VNode | null {
+  if (!settings.docTags) return null;
+
+  const rawTags = tags ?? [];
+  const canonicalTags = resolvePageTags(rawTags);
+  if (canonicalTags.length === 0) return null;
+
+  const resolvedTags = canonicalTags.map((tag) => ({
+    tag,
+    href: tagHref(tag, locale),
+  }));
+
+  return (
+    <DocTags
+      placement="after-title"
+      tags={resolvedTags}
+      tagsLabel={t("doc.tags", locale)}
+      taggedWithLabel={t("doc.taggedWith", locale)}
+    />
+  );
+}

package/templates/base/pages/lib/_extract-headings.ts

@@ -0,0 +1,81 @@
+// pages/lib/_extract-headings.ts — extract TOC headings from a raw MDX body.
+//
+// Shared helper called by all four catch-all `paths()` functions so each page
+// passes real heading data to `DocLayoutWithDefaults` rather than an empty
+// array. The result drops directly into the `headings` prop of `Toc` /
+// `MobileToc` — the shape is byte-aligned with `HeadingItem` in
+// `packages/zudo-doc/src/toc/types.ts`.
+//
+// Algorithm:
+//   1. Walk the body line-by-line looking for ATX-style markdown headings
+//      (`## Text`, `### Text`, `#### Text`).
+//   2. Compute a GitHub-compatible slug using the same `GithubSlugger` that
+//      the `rehype-heading-links` plugin uses at render time, so the TOC
+//      anchor hrefs match the rendered heading IDs in the HTML.
+//   3. Return only depth 2–4 headings — depth 1 is the page title (rendered
+//      separately as an <h1>); depth 5–6 are too granular for the TOC.
+//
+// Caveats:
+//   - This is a regex walk over raw text, not an AST parse. MDX JSX expressions
+//     or code fences that contain `##` on their own line are matched. In
+//     practice this is rare; Astro's `entry.render()` returned the same shape
+//     and relied on the same assumption (headings extracted pre-render).
+//   - Lines inside code fences (``` … ```) are skipped to avoid treating
+//     literal `## code` examples as real headings.
+
+import GithubSlugger from "github-slugger";
+
+export interface HeadingItem {
+  readonly depth: number;
+  readonly slug: string;
+  readonly text: string;
+}
+
+/**
+ * Extract depth-2/3/4 headings from a raw MDX/markdown body.
+ *
+ * Uses the same slugging algorithm as `rehype-heading-links` so the
+ * `href="#slug"` values in the TOC match the rendered heading element IDs.
+ *
+ * @param body - Raw markdown body string (frontmatter already stripped).
+ * @returns Array of `{ depth, slug, text }` items in document order.
+ */
+export function extractHeadings(body: string): HeadingItem[] {
+  const slugger = new GithubSlugger();
+  const headings: HeadingItem[] = [];
+
+  // Track the opening fence string (`` ``` `` or ```` ```` ````) so we match the
+  // correct closing fence — Markdown allows longer fences to nest shorter ones.
+  let codeFenceOpener: string | null = null;
+  for (const line of body.split("\n")) {
+    // Detect code fence open/close. A fence is 3+ backticks optionally followed
+    // by a language specifier. The closing fence must match the opener's length.
+    const fenceMatch = /^(`{3,})/.exec(line);
+    if (fenceMatch) {
+      const fence = fenceMatch[1] as string;
+      if (codeFenceOpener === null) {
+        codeFenceOpener = fence;
+      } else if (fence.length >= codeFenceOpener.length) {
+        codeFenceOpener = null;
+      }
+      continue;
+    }
+    if (codeFenceOpener !== null) continue;
+
+    // Match ATX headings at depth 2, 3, or 4. Allow one or more spaces/tabs
+    // after the hash characters (both are valid per the CommonMark spec).
+    const match = /^(#{2,4})[ \t]+(.+)$/.exec(line.trim());
+    if (!match) continue;
+
+    const depth = (match[1] as string).length;
+    const raw = (match[2] as string).trim();
+
+    headings.push({
+      depth,
+      slug: slugger.slug(raw),
+      text: raw,
+    });
+  }
+
+  return headings;
+}

package/templates/base/pages/lib/_footer-with-defaults.tsx

@@ -0,0 +1,234 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locale-aware Footer wrapper for the zfb doc pages.
+//
+// Mirrors the data-prep logic that lived in src/components/footer.astro
+// (deleted in commit a4d9956) — reading settings.footer, localizing link
+// hrefs and titles, and optionally collecting tag columns when taglist is
+// enabled — then feeds the result into the presentational <Footer> shell
+// from @takazudo/zudo-doc/footer.
+//
+// Callers pass a `lang` prop (the active locale string, e.g. "en", "ja").
+// The component returns a fully populated <Footer> when settings.footer is
+// configured, or a bare <Footer /> shell when it is not (the shell still
+// emits the contentinfo ARIA landmark).
+//
+// Data-prep helpers used:
+//   settings.footer            — link columns, copyright, taglist config
+//   isExternal / resolveHref / withBase  — href normalization
+//   defaultLocale              — determines when locale prefix is needed
+//   tagVocabulary              — group-by ordering for grouped taglist mode
+//   collectTags                — builds tag → { count, docs } map
+//   toRouteSlug                — derives route slug from collection id
+//   loadDocs / filterDrafts    — synchronous zfb collection helpers (ADR-004)
+
+import type { VNode } from "preact";
+import { settings } from "@/config/settings";
+import { Footer } from "@takazudo/zudo-doc/footer";
+import type { FooterLinkColumn, FooterTagColumn } from "@takazudo/zudo-doc/footer";
+import { isExternal, resolveHref, withBase } from "@/utils/base";
+import { defaultLocale } from "@/config/i18n";
+import { tagVocabulary } from "@/config/tag-vocabulary";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { loadDocs } from "../_data";
+import type { DocsEntry } from "@/types/docs-entry";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Prefix an internal href with the locale path for non-default locales,
+ * then apply the configured base prefix. External hrefs pass through.
+ *
+ * Mirrors the `localizeHref` function from the historical footer.astro.
+ */
+function localizeHref(href: string, lang: string): string {
+  if (isExternal(href)) return href;
+  if (lang !== defaultLocale) {
+    const path = href.startsWith("/") ? href : `/${href}`;
+    return resolveHref(`/${lang}${path}`);
+  }
+  return resolveHref(href);
+}
+
+/** Build the base-prefixed tag detail page href for the given locale. */
+function tagHref(tag: string, lang: string): string {
+  const path =
+    lang === defaultLocale
+      ? `/docs/tags/${tag}`
+      : `/${lang}/docs/tags/${tag}`;
+  return withBase(path);
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+interface FooterWithDefaultsProps {
+  /** Active locale string, e.g. "en", "ja". Defaults to defaultLocale. */
+  lang?: string;
+}
+
+/**
+ * Locale-aware Footer wrapper.
+ *
+ * Reads settings.footer and assembles the linkColumns / tagColumns /
+ * copyright props expected by the presentational <Footer> shell.  When
+ * settings.footer is false, a bare <Footer /> shell is returned (the
+ * contentinfo ARIA landmark is still present).
+ */
+export function FooterWithDefaults({
+  lang = defaultLocale,
+}: FooterWithDefaultsProps): VNode {
+  const footer = settings.footer;
+
+  // Locale-keyed persist key: same-locale swaps preserve DOM identity;
+  // cross-locale swaps discard the stale footer and re-render. (#1546)
+  const persistKey = `footer-${lang}`;
+
+  // When footer is not configured, return the bare shell so the
+  // contentinfo ARIA landmark is present.
+  if (!footer) {
+    return <Footer persistKey={persistKey} />;
+  }
+
+  const { links, copyright, taglist } = footer;
+
+  // ── Link columns ────────────────────────────────────────────────────────
+
+  const linkColumns: FooterLinkColumn[] = links.map((column) => ({
+    title: (column.locales as Record<string, { title: string }> | undefined)?.[lang]?.title ?? column.title,
+    items: column.items.map((item) => ({
+      label: (item.locales as Record<string, { label: string }> | undefined)?.[lang]?.label ?? item.label,
+      href: localizeHref(item.href, lang),
+      isExternal: isExternal(item.href),
+    })),
+  }));
+
+  // ── Tag columns (optional) ───────────────────────────────────────────────
+
+  let tagColumns: FooterTagColumn[] = [];
+
+  if (taglist?.enabled) {
+    // Load docs synchronously (zfb ADR-004 — synchronous content snapshot).
+    let docs: DocsEntry[];
+    if (lang === defaultLocale) {
+      docs = loadDocs("docs").filter((d) => !d.data.draft && !d.data.unlisted);
+    } else {
+      const localeDocs = loadDocs(`docs-${lang}`).filter(
+        (d) => !d.data.draft && !d.data.unlisted,
+      );
+      const baseDocs = loadDocs("docs").filter(
+        (d) => !d.data.draft && !d.data.unlisted,
+      );
+      const localeSlugSet = new Set(
+        localeDocs.map((d) => d.data.slug ?? toRouteSlug(d.id)),
+      );
+      docs = [
+        ...localeDocs,
+        ...baseDocs.filter(
+          (d) => !localeSlugSet.has(d.data.slug ?? toRouteSlug(d.id)),
+        ),
+      ];
+    }
+
+    const tagMap = collectTags(
+      docs,
+      (id, data) => data.slug ?? toRouteSlug(id),
+    );
+    const allTags = [...tagMap.values()].sort((a, b) =>
+      a.tag.localeCompare(b.tag, lang),
+    );
+
+    const vocabularyActive =
+      Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
+    const requestedGroupBy = taglist.groupBy ?? "group";
+    const effectiveGroupBy = vocabularyActive ? requestedGroupBy : "flat";
+
+    const localeOverrides = (taglist.locales as Record<string, { title?: string; groupTitles?: Record<string, string> }> | undefined)?.[lang];
+    const groupTitles: Record<string, string> = {
+      ...taglist.groupTitles,
+      ...localeOverrides?.groupTitles,
+    };
+    const flatTitle = localeOverrides?.title ?? taglist.title ?? "Tags";
+
+    if (effectiveGroupBy === "flat" || !vocabularyActive) {
+      if (allTags.length > 0) {
+        tagColumns = [
+          {
+            group: "__flat__",
+            title: flatTitle,
+            tags: allTags.map(({ tag, count }) => ({
+              tag,
+              count,
+              href: tagHref(tag, lang),
+            })),
+          },
+        ];
+      }
+    } else {
+      // Grouped mode: one column per vocabulary group, in declaration order.
+      const groupByCanonical = new Map<string, string>();
+      const groupOrder: string[] = [];
+      const seenGroups = new Set<string>();
+      for (const entry of tagVocabulary) {
+        if (!entry.group) continue;
+        groupByCanonical.set(entry.id, entry.group);
+        if (!seenGroups.has(entry.group)) {
+          seenGroups.add(entry.group);
+          groupOrder.push(entry.group);
+        }
+      }
+
+      const buckets = new Map<string, typeof allTags>();
+      for (const group of groupOrder) buckets.set(group, []);
+      const ungrouped: typeof allTags = [];
+
+      for (const info of allTags) {
+        const group = groupByCanonical.get(info.tag);
+        if (group && buckets.has(group)) {
+          buckets.get(group)!.push(info);
+        } else {
+          ungrouped.push(info);
+        }
+      }
+
+      tagColumns = groupOrder
+        .filter((g) => (buckets.get(g)?.length ?? 0) > 0)
+        .map((g) => ({
+          group: g,
+          title:
+            groupTitles[g] ??
+            g.charAt(0).toUpperCase() + g.slice(1),
+          tags: buckets.get(g)!.map(({ tag, count }) => ({
+            tag,
+            count,
+            href: tagHref(tag, lang),
+          })),
+        }));
+
+      if (ungrouped.length > 0) {
+        tagColumns.push({
+          group: "__flat__",
+          title: flatTitle,
+          tags: ungrouped.map(({ tag, count }) => ({
+            tag,
+            count,
+            href: tagHref(tag, lang),
+          })),
+        });
+      }
+    }
+  }
+
+  return (
+    <Footer
+      linkColumns={linkColumns}
+      tagColumns={tagColumns}
+      copyright={copyright}
+      persistKey={persistKey}
+    />
+  );
+}