create-zudo-doc 0.1.0

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

@@ -0,0 +1,467 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/[locale]/docs/[...slug].astro → zfb page module.
+//
+// Non-default-locale catch-all docs route. paths() emits one route per
+// (locale, slug) combination — one locale from settings.locales per each
+// doc in that locale's merged collection (locale-first + base fallback).
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { locale: string; slug: string[] }
+//   props:  { entry, autoIndex, contentDir, isFallback, breadcrumbs, prev, next }
+//
+// i18n / locale routing:
+//   - Default locale (EN) is handled by pages/docs/[...slug].tsx
+//     (prefixDefaultLocale: false).
+//   - 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).
+
+import { getCollection } from "zfb/content";
+import type { CollectionEntry } from "zfb/content";
+import type { DocsEntry } from "@/types/docs-entry";
+import { settings } from "@/config/settings";
+import { t, getContentDir } from "@/config/i18n";
+import { docsUrl, isDefaultLocaleOnlyPath } from "@/utils/base";
+import {
+  buildNavTree,
+  buildBreadcrumbs,
+  flattenTree,
+  findNode,
+  loadCategoryMeta,
+  collectAutoIndexNodes,
+  isNavVisible,
+  type NavNode,
+  type BreadcrumbItem,
+} from "@/utils/docs";
+import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
+import { toRouteSlug } from "@/utils/slug";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import { NavCardGrid } from "@takazudo/zudo-doc/nav-indexing";
+import { FrontmatterPreview } from "@takazudo/zudo-doc/metainfo";
+import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
+// Shared MDX components bag — see `pages/_mdx-components.ts`.
+import { createMdxComponents } from "../../_mdx-components";
+import type { JSX } from "preact";
+import { bridgeEntries } from "../../_data";
+import { extractHeadings } from "../../lib/_extract-headings";
+import { FooterWithDefaults } from "../../lib/_footer-with-defaults";
+import { DocHistoryArea } from "../../lib/_doc-history-area";
+import { BodyEndIslands } from "../../lib/_body-end-islands";
+import { DocMetainfoArea } from "../../lib/_doc-metainfo-area";
+import { DocTagsArea } from "../../lib/_doc-tags-area";
+import { SidebarWithDefaults } from "../../lib/_sidebar-with-defaults";
+import { HeaderWithDefaults } from "../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../lib/_head-with-defaults";
+import { buildFrontmatterPreviewEntries } from "../../lib/_frontmatter-preview-data";
+import { composeMetaTitle } from "../../lib/_compose-meta-title";
+import { buildInlineVersionSwitcher } from "../../lib/_inline-version-switcher";
+import DesktopSidebarToggle from "@/components/desktop-sidebar-toggle";
+import { SidebarResizerInit } from "@takazudo/zudo-doc/sidebar-resizer";
+import type { VNode } from "preact";
+import { Island } from "@takazudo/zfb";
+
+export const frontmatter = { title: "Docs" };
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface DocPageEntry extends DocsEntry {
+  Content: CollectionEntry<unknown>["Content"];
+  module_specifier: string;
+}
+
+interface AutoIndexNode extends NavNode {
+  children: NavNode[];
+}
+
+interface DocPageProps {
+  entry: DocPageEntry | null;
+  autoIndex?: AutoIndexNode;
+  /** Content directory for the active locale (or base EN for fallbacks). */
+  contentDir: string;
+  /** True when this page falls back to the base EN collection. */
+  isFallback: boolean;
+  breadcrumbs: BreadcrumbItem[];
+  prev: NavNode | null;
+  next: NavNode | null;
+  /** Depth-2/3/4 headings extracted from the MDX body, for SSG TOC links. */
+  headings: ReturnType<typeof extractHeadings>;
+}
+
+// ---------------------------------------------------------------------------
+// paths() — synchronous (ADR-004)
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit one route per (non-default locale, slug) combination.
+ *
+ * Merge strategy:
+ *   1. Load locale docs (e.g. "docs-ja").
+ *   2. Load base EN docs ("docs").
+ *   3. Locale docs take priority; base EN fills in slugs not translated.
+ *   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).
+ */
+export function paths(): Array<{
+  params: { locale: string; slug: string[] };
+  props: DocPageProps;
+}> {
+  const result: Array<{
+    params: { locale: string; slug: string[] };
+    props: DocPageProps;
+  }> = [];
+
+  for (const locale of Object.keys(settings.locales) as string[]) {
+    const localeConfig = (settings.locales as Record<string, { dir: string }>)[locale];
+    const contentDir = localeConfig?.dir ?? settings.docsDir;
+
+    // Load locale + base docs, filter drafts
+    const localeDocs = ((bridgeEntries(getCollection(`docs-${locale}`), `docs-${locale}`) as unknown as DocPageEntry[])).filter(
+      (d) => !d.data.draft,
+    );
+    const baseDocs = ((bridgeEntries(getCollection("docs"), "docs") as unknown as DocPageEntry[])).filter(
+      (d) => !d.data.draft,
+    );
+
+    const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? toRouteSlug(d.slug)));
+    const fallbackDocs = baseDocs.filter(
+      (d) => !localeSlugSet.has(d.data.slug ?? toRouteSlug(d.slug)) && !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? toRouteSlug(d.slug)}`),
+    );
+    const fallbackSlugs = new Set(fallbackDocs.map((d) => d.data.slug ?? toRouteSlug(d.slug)));
+    const allDocs = [...localeDocs, ...fallbackDocs];
+
+    // Merge category metadata: base first, locale overrides
+    const baseCategoryMeta = loadCategoryMeta(settings.docsDir);
+    const localeCategoryMeta = loadCategoryMeta(contentDir);
+    const categoryMeta = new Map([...baseCategoryMeta, ...localeCategoryMeta]);
+
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs as unknown as DocsEntry[], locale, categoryMeta);
+    const fullTree = buildNavTree(allDocs as unknown as DocsEntry[], locale, categoryMeta);
+
+    // Regular doc pages
+    for (const entry of allDocs) {
+      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);
+      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;
+
+      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;
+        }
+      }
+
+      result.push({
+        params: { locale, slug: slug.split("/") },
+        props: {
+          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)) {
+      result.push({
+        params: { locale, slug: node.slug.split("/") },
+        props: {
+          entry: null,
+          autoIndex: node as AutoIndexNode,
+          contentDir,
+          isFallback: false,
+          breadcrumbs: buildBreadcrumbs(fullTree, node.slug, locale),
+          prev: null,
+          next: null,
+          headings: [],
+        },
+      });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Page component
+// ---------------------------------------------------------------------------
+
+interface PageArgs {
+  params: { locale: string; slug: string[] };
+  entry: DocPageProps["entry"];
+  autoIndex?: DocPageProps["autoIndex"];
+  contentDir: DocPageProps["contentDir"];
+  isFallback: DocPageProps["isFallback"];
+  breadcrumbs: DocPageProps["breadcrumbs"];
+  prev: DocPageProps["prev"];
+  next: DocPageProps["next"];
+  headings: DocPageProps["headings"];
+}
+
+export default function LocaleDocsPage({ params, entry, autoIndex, contentDir, isFallback, breadcrumbs, prev, next, headings }: PageArgs): JSX.Element {
+  const locale = params.locale;
+
+  const slug = autoIndex
+    ? autoIndex.slug
+    : (entry!.data.slug ?? toRouteSlug(entry!.slug));
+
+  const title = autoIndex ? autoIndex.label : entry!.data.title;
+  const description = autoIndex ? autoIndex.description : 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);
+
+  const autoIndexChildren = autoIndex
+    ? autoIndex.children
+        .filter((c: NavNode) => c.hasPage || c.children.length > 0)
+        .map((c: NavNode) => ({
+          ...c,
+          href: c.href ?? docsUrl(c.slug, locale),
+        }))
+    : [];
+
+  // Canonical URL — only when siteUrl is configured.
+  const pageUrl = docsUrl(slug, locale);
+  const canonical = settings.siteUrl
+    ? settings.siteUrl.replace(/\/$/, "") + pageUrl
+    : undefined;
+
+  // 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 = entry?.data?.hide_sidebar;
+  const sidebarPersistKey = hideSidebar
+    ? undefined
+    : `sidebar-${locale}-${navSection ?? "default"}`;
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(title)}
+      description={description}
+      head={<HeadWithDefaults title={title} description={description} canonical={canonical} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={hideSidebar}
+      hideToc={entry?.data?.hide_toc}
+      headings={headings}
+      canonical={canonical}
+      sidebarPersistKey={sidebarPersistKey}
+      headerOverride={
+        <HeaderWithDefaults
+          lang={locale}
+          currentSlug={slug}
+          navSection={getNavSectionForSlug(slug)}
+          currentPath={docsUrl(slug, locale)}
+        />
+      }
+      breadcrumbOverride={
+        breadcrumbs.length > 0 ? (
+          <Breadcrumb
+            items={breadcrumbs}
+            rightSlot={buildInlineVersionSwitcher(slug, locale)}
+          />
+        ) : undefined
+      }
+      sidebarOverride={
+        <SidebarWithDefaults
+          currentSlug={slug}
+          lang={locale}
+          navSection={getNavSectionForSlug(slug)}
+          currentPath={docsUrl(slug, locale)}
+        />
+      }
+      afterSidebar={
+        settings.sidebarToggle ? (
+          <>
+            <script dangerouslySetInnerHTML={{
+              __html: `(function(){try{if(localStorage.getItem('zudo-doc-sidebar-visible')==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`,
+            }} />
+            {Island({
+              when: "load",
+              children: <DesktopSidebarToggle />,
+            }) as unknown as VNode}
+          </>
+        ) : undefined
+      }
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={
+        <>
+          <BodyEndIslands basePath={settings.base ?? "/"} />
+          {settings.sidebarResizer && <SidebarResizerInit />}
+        </>
+      }
+    >
+      {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">{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} />
+
+          {autoIndex.description && (
+            <p class="mb-vsp-lg text-title text-muted">
+              {autoIndex.description}
+            </p>
+          )}
+          <NavCardGrid children={autoIndexChildren} />
+        </>
+      ) : (
+        /* Regular doc page. Fragment (not <div>) for the same reason as
+           the auto-index branch above — see #1460. */
+        <>
+          <h1 class="text-heading font-bold mb-vsp-xs">{entry!.data.title}</h1>
+
+          {/* Build-time date block (Created / Updated / Author). Mirrors the
+              Astro `doc-metainfo.astro` placement — between <h1> and description.
+              Data from `.zfb/doc-history-meta.json` (esbuild-inlined, no fs). */}
+          <DocMetainfoArea slug={slug} locale={locale} />
+
+          {/* Page-level tag chips — mirroring doc-tags.astro placement (#1658). */}
+          <DocTagsArea slug={slug} locale={locale} tags={entry!.data.tags} />
+
+          {/* Fallback notice for non-translated pages */}
+          {isFallback && !entry!.data.generated && (
+            <div
+              class="mb-vsp-md border border-info/30 bg-info/5 px-hsp-lg py-vsp-sm text-small text-muted rounded"
+              role="note"
+            >
+              {t("doc.fallbackNotice", locale)}
+            </div>
+          )}
+
+          {entry!.data.description && (
+            <p class="mb-vsp-lg text-title text-muted">
+              {entry!.data.description}
+            </p>
+          )}
+
+          {/* Frontmatter preview — non-system, custom keys only. Returns
+              null when the entries array is empty, so pages without
+              custom frontmatter emit nothing. Custom per-key renderers
+              from frontmatter-preview-renderers.tsx produce styled cells
+              (pills, badges, etc.) instead of plain text. */}
+          <FrontmatterPreview
+            entries={buildFrontmatterPreviewEntries(entry!.data)}
+            title={t("frontmatter.preview.title", locale)}
+            keyColLabel={t("frontmatter.preview.keyCol", locale)}
+            valueColLabel={t("frontmatter.preview.valueCol", locale)}
+            renderers={frontmatterRenderers}
+            data={entry!.data as Record<string, unknown>}
+            locale={locale}
+          />
+
+          {entry && <entry.Content components={components} />}
+
+          {/* Prev / Next pagination — placed before the document utilities
+              section to match the Astro reference order: content → pager →
+              view-source / history. In the Astro layout, BodyFootUtilArea was
+              rendered by the doc-layout wrapper after the <slot /> content,
+              so the pager (inside the slot) came first. Fixes #1535. */}
+          <nav class="mt-vsp-2xl grid grid-cols-2 gap-hsp-xl">
+            {prev ? (
+              <a
+                href={prev.href}
+                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent"
+              >
+                <div class="flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    class="h-[1.125rem] w-[1.125rem]"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="2"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M15 19l-7-7 7-7" />
+                  </svg>
+                  <span class="no-underline">{t("nav.previous", locale)}</span>
+                </div>
+                <p class="text-small font-semibold underline group-hover:text-accent">
+                  {prev.label}
+                </p>
+              </a>
+            ) : (
+              <div />
+            )}
+            {next ? (
+              <a
+                href={next.href}
+                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent text-right"
+              >
+                <div class="flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+                  <span class="no-underline">{t("nav.next", locale)}</span>
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    class="h-[1.125rem] w-[1.125rem]"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="2"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
+                  </svg>
+                </div>
+                <p class="text-small font-semibold underline group-hover:text-accent">
+                  {next.label}
+                </p>
+              </a>
+            ) : (
+              <div />
+            )}
+          </nav>
+
+          {/* Document utilities (revision history + view-source link) — skipped for unlisted pages */}
+          {!entry!.data.unlisted && (
+            <DocHistoryArea
+              slug={slug}
+              locale={locale}
+              entrySlug={entry!.slug}
+              contentDir={contentDir}
+            />
+          )}
+        </>
+      )}
+    </DocLayoutWithDefaults>
+  );
+}

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

@@ -0,0 +1,213 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/[locale]/index.astro → zfb page module.
+//
+// Non-default-locale site index. paths() emits one route per locale defined
+// in settings.locales (never the default locale — that is handled by
+// pages/index.tsx since prefixDefaultLocale is false).
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { locale: string }   — e.g. "ja"
+//   props:  { locale }           — resolved locale passed to component
+//
+// Data flow (inside component — sync per ADR-004):
+//   getCollection(`docs-${locale}`)  + base fallback merge
+//   → buildNavTree()   → groupSatelliteNodes()
+//   → collectTags()    → tag section
+
+import { getCollection } from "zfb/content";
+import type { DocsEntry } from "@/types/docs-entry";
+import { settings } from "@/config/settings";
+import { t } from "@/config/i18n";
+import { withBase, isDefaultLocaleOnlyPath } from "@/utils/base";
+import {
+  buildNavTree,
+  groupSatelliteNodes,
+  isNavVisible,
+  loadCategoryMeta,
+} from "@/utils/docs";
+import { getCategoryOrder } from "@/utils/nav-scope";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import type { JSX } from "preact";
+import type { VNode } from "preact";
+import { Island } from "@takazudo/zfb";
+import SiteTreeNav from "@/components/site-tree-nav";
+import { bridgeEntries } 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 { BodyEndIslands } from "../lib/_body-end-islands";
+
+export const frontmatter = { title: "Home" };
+
+// ---------------------------------------------------------------------------
+// paths() — synchronous (ADR-004)
+// ---------------------------------------------------------------------------
+
+/** Emit one route per non-default locale. */
+export function paths(): Array<{
+  params: { locale: string };
+  props: { locale: string };
+}> {
+  return Object.keys(settings.locales).map((locale) => ({
+    params: { locale },
+    props: { locale },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge locale docs with base (EN) fallbacks.
+ * Mirrors the merge strategy in src/utils/locale-docs.ts.
+ */
+function mergeLocaleDocs(locale: string): DocsEntry[] {
+  const localeDocs = ((bridgeEntries(getCollection(`docs-${locale}`), `docs-${locale}`) as unknown as DocsEntry[])).filter(
+    (d) => !d.data.draft,
+  );
+  const baseDocs = ((bridgeEntries(getCollection("docs"), "docs") as unknown as DocsEntry[])).filter(
+    (d) => !d.data.draft,
+  );
+  const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? toRouteSlug(d.slug)));
+  const fallbackDocs = baseDocs.filter((d) => !localeSlugSet.has(d.data.slug ?? toRouteSlug(d.slug)));
+  const filteredFallback = fallbackDocs.filter((d) => {
+    const slug = d.data.slug ?? toRouteSlug(d.slug);
+    return !isDefaultLocaleOnlyPath(`/docs/${slug}/`);
+  });
+  return [...localeDocs, ...filteredFallback];
+}
+
+// ---------------------------------------------------------------------------
+// Page component
+// ---------------------------------------------------------------------------
+
+interface PageArgs {
+  params: { locale: string };
+  props: { locale: string };
+}
+
+export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
+  const locale = params.locale;
+
+  const allDocs = mergeLocaleDocs(locale);
+  const localeConfig = (settings.locales as Record<string, { dir: string }>)[locale];
+  const categoryMeta = localeConfig
+    ? loadCategoryMeta(localeConfig.dir)
+    : loadCategoryMeta(settings.docsDir);
+
+  const navDocs = allDocs.filter(isNavVisible);
+  const tree = buildNavTree(navDocs, locale, categoryMeta);
+  const categoryOrder = getCategoryOrder();
+  const groupedTree = groupSatelliteNodes(tree, categoryOrder);
+
+  const tagCount = collectTags(
+    navDocs,
+    (id, data) => data.slug ?? toRouteSlug(id),
+  ).size;
+
+  const ctaNav = settings.headerNav[0] ?? null;
+  const overview = ctaNav ? withBase(`/${locale}${ctaNav.path}`) : null;
+  const logoUrl = withBase("/img/logo.svg");
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(settings.siteName)}
+      head={<HeadWithDefaults title={settings.siteName} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={true}
+      hideToc={true}
+      headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/`)} />}
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+    >
+      {/* Hero: logo left, title+desc+links right, block centered */}
+      <div class="flex justify-center mb-vsp-xl">
+        <div class="flex flex-col items-center text-center gap-hsp-md lg:flex-row lg:text-left lg:gap-hsp-xl">
+          <img
+            src={logoUrl}
+            alt={settings.siteName}
+            class="w-[320px] max-w-full aspect-[1200/630] shrink-0"
+          />
+          <div>
+            <h1 class="text-heading font-bold mb-vsp-2xs">{settings.siteName}</h1>
+            <p class="text-muted text-small mb-vsp-sm">{settings.siteDescription}</p>
+            <div class="flex items-center justify-center lg:justify-start gap-hsp-md text-small">
+              {overview && (
+                <>
+                  <a href={overview} class="text-fg underline hover:text-accent">
+                    {t("nav.overview", locale)}
+                  </a>
+                  <span class="text-muted">/</span>
+                </>
+              )}
+              {settings.githubUrl && (
+                <>
+                  <a
+                    href={settings.githubUrl as string}
+                    class="inline-flex items-center gap-[0.3em] text-fg underline hover:text-accent"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    <svg viewBox="0 0 16 16" aria-hidden="true" class="w-[1em] h-[1em] shrink-0">
+                      <path
+                        fill="currentColor"
+                        d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"
+                      />
+                    </svg>
+                    GitHub
+                  </a>
+                  <span class="text-muted">/</span>
+                </>
+              )}
+              {/* @Takazudo link — ported from pages/index.tsx (refs #1453).
+                  The locale home was missing this trailing item, leaving a
+                  dangling "/" separator after GitHub. */}
+              <a
+                href="https://x.com/Takazudo"
+                class="text-fg underline hover:text-accent"
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                @Takazudo
+              </a>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Sitemap grid — SiteTreeNav island mirrors the EN home (refs #1453).
+          The locale home was using DocsSitemap (vertical <details> list);
+          replaced with the same SiteTreeNav island used by pages/index.tsx. */}
+      {Island({
+        when: "idle",
+        children: (
+          <SiteTreeNav
+            tree={groupedTree}
+            categoryOrder={categoryOrder}
+            categoryIgnore={["inbox", "develop"]}
+          />
+        ),
+      }) as unknown as VNode}
+
+      {settings.docTags && tagCount > 0 && (
+        <section class="mt-vsp-xl">
+          <h2 class="text-title font-bold mb-vsp-md">
+            {t("doc.allTags", locale)}
+          </h2>
+          <a
+            href={withBase(`/${locale}/docs/tags`)}
+            class="text-accent underline hover:text-accent-hover"
+          >
+            {t("doc.allTags", locale)}
+          </a>
+        </section>
+      )}
+    </DocLayoutWithDefaults>
+  );
+}