@takazudo/zudo-doc 5.20.0 → 5.22.0

package/CHANGELOG.md

@@ -8,6 +8,29 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [5.22.0] - 2026-09-11
+
+### Features
+
+- Added `docMetainfoFields` to select the metadata fields displayed on documentation pages. It defaults to all fields; an empty array hides them all, and `["updated"]` displays Updated even when Created has the same formatted date. (`06044fa30`, `3832e08af`)
+- Added `docHistoryUi: false` to retain generated git metadata while disabling the history viewer, history JSON generation, and development proxy. Configured view-source links remain available. (`84cd63af5`)
+- Added a post-build check for missing site-absolute `<img src>` files, using the existing `onBrokenMarkdownLinks` severity setting. (`9cc259d65`)
+
+### Bug Fixes
+
+- Mirrored Claude commands and agents and shared Claude/Codex skills now render repository-relative links as labels when their targets are not emitted. Code examples and links to emitted skill-body sub-pages are preserved. (`bb6d0390c`)
+
+## [5.21.0] - 2026-09-09
+
+### Features
+
+- Added compact Markdown introductions to the home pages. `home.introMarkdown` renders serializable Markdown below the home identity on `/`, and each non-default locale can override it with `LocaleConfig.introMarkdown`. Empty values keep the previous layout, so existing sites are unaffected. (`77ed96b3f`, `8e10ecbc1`)
+- Added `home.sitemapHeading` and `LocaleConfig.sitemapHeading` to override the home sitemap section title. A blank value restores the translated package default. (`77ed96b3f`)
+
+### Bug Fixes
+
+- Rendered the home sitemap and tag section headings through one shared component, so both align with the full-width content band instead of the sitemap heading sitting on the narrower inner column. (`849e04a57`)
+
 ## [5.20.0] - 2026-09-09
 
 ### Features

package/dist/compiled.css

@@ -2155,6 +2155,11 @@
     max-width: 52.5rem;
   }
 }
+.lg\:flex-1 {
+  @media (width >= 1024px) {
+    flex: 1;
+  }
+}
 .lg\:grid-cols-3 {
   @media (width >= 1024px) {
     grid-template-columns: repeat(3, minmax(0, 1fr));
@@ -2727,6 +2732,73 @@ a.text-accent.underline {
   border-radius: var(--zdc-admonition-radius, 0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0);
   border-left-width: var(--zdc-admonition-border-width, 4px);
 }
+.zd-home-inner {
+  inline-size: 100%;
+  max-inline-size: 60rem;
+  min-inline-size: 0;
+  margin-inline: auto;
+  overflow-wrap: anywhere;
+}
+.zd-home-copy, .zd-home-links {
+  min-inline-size: 0;
+}
+.zd-home-links {
+  overflow-wrap: anywhere;
+}
+.zd-home-rule {
+  inline-size: 100%;
+  margin-block: var(--spacing-vsp-xl);
+  margin-inline: 0;
+  border: 0;
+  border-block-start: 1px solid var(--color-muted);
+}
+.zd-compact-prose {
+  min-inline-size: 0;
+  text-align: left;
+  font-size: 1rem;
+  line-height: 1.75;
+  overflow-wrap: anywhere;
+}
+.zd-compact-prose > :where(* + *) {
+  margin-top: var(--flow-space, 1rem);
+}
+.zd-compact-prose :where(h2, h3, h4, h5, h6) {
+  font-weight: var(--font-weight-bold, 700);
+  line-height: 1.4;
+  padding: 0;
+  border: 0;
+  background: none;
+}
+.zd-compact-prose :where(h2) {
+  font-size: 1.3rem;
+  --flow-space: 1.75rem;
+}
+.zd-compact-prose :where(h3) {
+  font-size: 1.125rem;
+  --flow-space: 1.5rem;
+}
+.zd-compact-prose :where(h4) {
+  font-size: 1rem;
+  --flow-space: 1.25rem;
+}
+.zd-compact-prose :where(h5, h6) {
+  font-size: .9375rem;
+  --flow-space: 1.25rem;
+}
+.zd-compact-prose > :where(h2, h3, h4, h5, h6) + * {
+  margin-top: .5rem;
+}
+.zd-compact-prose > :first-child {
+  margin-top: 0;
+}
+.zd-compact-prose :where(pre) {
+  max-inline-size: 100%;
+  overflow-x: auto;
+}
+.zd-compact-prose :where(img) {
+  max-inline-size: 100%;
+  block-size: auto;
+}
 .page-loading-overlay {
   position: fixed;
   inset: 0;

package/dist/config.d.ts

@@ -143,7 +143,7 @@ export interface ZudoDocConfig {
     /**
      * Package-owned home-page layout. Set `wide: true` to let the category grid
      * fill most of the viewport on both `/` and locale home routes.
-     * @default { wide: false }
+     * @default { wide: false, introMarkdown: "", sitemapHeading: "" }
      */
     home?: HomeConfig;
     /**
@@ -249,6 +249,11 @@ export interface ZudoDocConfig {
      * @default false
      */
     docMetainfo?: boolean;
+    /**
+     * Metadata fields to show in the doc metadata area.
+     * @default ["created", "updated", "author"]
+     */
+    docMetainfoFields?: Array<"created" | "updated" | "author">;
     /**
      * Enable the `/docs/tags` + `/docs/tags/[tag]` tag index routes.
      * @default false
@@ -378,6 +383,12 @@ export interface ZudoDocConfig {
      * @default false
      */
     docHistory?: boolean;
+    /**
+     * Enable the doc history dropdown UI, history JSON generation, and dev
+     * history proxy while retaining the history metadata manifest.
+     * @default true
+     */
+    docHistoryUi?: boolean;
     /**
      * Glob patterns matched against the doc slug (path minus extension, `/index`
      * stripped, root = `index`) that exclude matching pages from git-history

package/dist/config.js

@@ -45,7 +45,7 @@ const DEFAULT_SETTINGS = {
   favicon: void 0,
   base: "/",
   trailingSlash: false,
-  home: { wide: false },
+  home: { wide: false, introMarkdown: "", sitemapHeading: "" },
   siteTreeNavIgnore: [],
   minifyHtml: true,
   docsDir: "src/content/docs",
@@ -68,6 +68,7 @@ const DEFAULT_SETTINGS = {
   },
   sitemap: false,
   docMetainfo: false,
+  docMetainfoFields: ["created", "updated", "author"],
   docTags: false,
   tagPlacement: "after-title",
   tagGovernance: "off",
@@ -94,6 +95,7 @@ const DEFAULT_SETTINGS = {
   dynamicPageTransition: false,
   frontmatterPreview: false,
   docHistory: false,
+  docHistoryUi: true,
   docHistoryExclude: [],
   assetViewer: false,
   assetViewerDir: "assets",

package/dist/content.css

@@ -533,3 +533,58 @@ a.text-accent.underline {
 }
 
 /* END --zdc-* component tokens */
+
+/* Compact homepage Markdown uses the same non-heading components and tokens.
+ * Shared width primitive is also available to the home identity group. */
+.zd-home-inner {
+  inline-size: 100%;
+  max-inline-size: 60rem;
+  min-inline-size: 0;
+  margin-inline: auto;
+  overflow-wrap: anywhere;
+}
+
+.zd-home-copy,
+.zd-home-links {
+  min-inline-size: 0;
+}
+
+.zd-home-links {
+  overflow-wrap: anywhere;
+}
+
+.zd-home-rule {
+  inline-size: 100%;
+  margin-block: var(--spacing-vsp-xl);
+  margin-inline: 0;
+  border: 0;
+  border-block-start: 1px solid var(--color-muted);
+}
+
+.zd-compact-prose {
+  min-inline-size: 0;
+  text-align: left;
+  font-size: 1rem;
+  line-height: 1.75;
+  overflow-wrap: anywhere;
+}
+
+.zd-compact-prose > :where(* + *) {
+  margin-top: var(--flow-space, 1rem);
+}
+
+.zd-compact-prose :where(h2, h3, h4, h5, h6) {
+  font-weight: var(--font-weight-bold, 700);
+  line-height: 1.4;
+  padding: 0;
+  border: 0;
+  background: none;
+}
+.zd-compact-prose :where(h2) { font-size: 1.3rem; --flow-space: 1.75rem; }
+.zd-compact-prose :where(h3) { font-size: 1.125rem; --flow-space: 1.5rem; }
+.zd-compact-prose :where(h4) { font-size: 1rem; --flow-space: 1.25rem; }
+.zd-compact-prose :where(h5, h6) { font-size: .9375rem; --flow-space: 1.25rem; }
+.zd-compact-prose > :where(h2, h3, h4, h5, h6) + * { margin-top: .5rem; }
+.zd-compact-prose > :first-child { margin-top: 0; }
+.zd-compact-prose :where(pre) { max-inline-size: 100%; overflow-x: auto; }
+.zd-compact-prose :where(img) { max-inline-size: 100%; block-size: auto; }

package/dist/doc-history-area/index.d.ts

@@ -14,6 +14,8 @@ export interface DocHistoryMetaEntry {
 /** Settings subset read by the DocHistoryArea factory. */
 export interface DocHistoryAreaSettings {
     docHistory: boolean;
+    /** Keep the metadata manifest while suppressing the history island. */
+    docHistoryUi?: boolean;
     docHistoryExclude?: string[];
     bodyFootUtilArea: {
         viewSourceLink?: boolean;

package/dist/doc-history-area/index.js

@@ -31,7 +31,8 @@ function createDocHistoryArea(ctx) {
   }) {
     if (!settings.docHistory) return null;
     const historySlug = toHistorySlug(slug);
-    if (isHistoryExcluded(historySlug)) return null;
+    const showDocHistoryUi = settings.docHistoryUi !== false;
+    if (isHistoryExcluded(historySlug) && showDocHistoryUi) return null;
     const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
     const composedSlug = effectiveHistoryLocale === defaultLocale ? historySlug : `${effectiveHistoryLocale}/${historySlug}`;
     const meta = docHistoryMeta[composedSlug];
@@ -56,7 +57,7 @@ function createDocHistoryArea(ctx) {
         updatedDate ? `: ${updatedDate}` : ""
       ] })
     ] });
-    const docHistoryIsland = Island({
+    const docHistoryIsland = showDocHistoryUi ? Island({
       when: "idle",
       ssrFallback: fallback,
       children: /* @__PURE__ */ jsx(
@@ -69,12 +70,12 @@ function createDocHistoryArea(ctx) {
           dateFormats: docHistoryDateFormats
         }
       )
-    });
+    }) : null;
+    void historyLabel;
     const utilSettings = settings.bodyFootUtilArea;
     const sourceExt = meta ? meta.ext : sourceFileExt;
     const sourceUrl = utilSettings && utilSettings.viewSourceLink && entrySlug && sourceExt && contentDir ? buildGitHubSourceUrl(contentDir, entrySlug + sourceExt) : null;
     const viewSourceLabel = t("doc.viewSource", locale);
-    void historyLabel;
     return /* @__PURE__ */ jsx(
       BodyFootUtilArea,
       {

package/dist/doc-metainfo-area/index.d.ts

@@ -13,6 +13,8 @@ export interface DocHistoryMetaEntry {
 /** Settings subset read by the DocMetainfoArea factory. */
 export interface DocMetainfoAreaSettings {
     docMetainfo: boolean;
+    /** Metadata fields shown in the doc metadata area; omitted means all fields. */
+    docMetainfoFields?: Array<"created" | "updated" | "author">;
 }
 export interface DocMetainfoAreaProps {
     /** Page slug, e.g. "getting-started/intro". */

package/dist/doc-metainfo-area/index.js

@@ -13,6 +13,11 @@ function createDocMetainfoArea(ctx) {
   const dateFormatsFor = deriveDateFormats(ctx);
   function DocMetainfoArea({ slug, locale, isFallback }) {
     if (!settings.docMetainfo) return null;
+    const fields = settings.docMetainfoFields;
+    const showCreated = fields === void 0 || fields.includes("created");
+    const showUpdated = fields === void 0 || fields.includes("updated");
+    const showAuthor = fields === void 0 || fields.includes("author");
+    if (!showCreated && !showUpdated && !showAuthor) return null;
     const historySlug = toHistorySlug(slug);
     const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
     const composedSlug = effectiveHistoryLocale === defaultLocale ? historySlug : `${effectiveHistoryLocale}/${historySlug}`;
@@ -21,9 +26,9 @@ function createDocMetainfoArea(ctx) {
     return /* @__PURE__ */ jsx(
       DocMetainfo,
       {
-        createdAt: meta.createdDate ? formatDate(meta.createdDate, locale, dateFormatsFor(locale).full) : null,
-        updatedAt: meta.updatedDate ? formatDate(meta.updatedDate, locale, dateFormatsFor(locale).full) : null,
-        author: meta.author || null,
+        createdAt: showCreated && meta.createdDate ? formatDate(meta.createdDate, locale, dateFormatsFor(locale).full) : null,
+        updatedAt: showUpdated && meta.updatedDate ? formatDate(meta.updatedDate, locale, dateFormatsFor(locale).full) : null,
+        author: showAuthor ? meta.author || null : null,
         createdLabel: t("doc.created", locale),
         updatedLabel: t("doc.updated", locale)
       }

package/dist/factory-context/index.d.ts

@@ -124,6 +124,8 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     themePackRegistry: ThemePackRegistry | null;
     /** Author-facing asset index, or `null` when the viewer is disabled. */
     assetManifest: AssetManifest | null;
+    /** Prepared, serializable homepage introductions. */
+    homeIntros: import("../home-intro/types.js").PreparedHomeIntros;
     /** The reconstructed i18n surface. */
     i18n: FactoryI18n;
     /** Default locale code (un-prefixed `/docs/...`). */

package/dist/home-intro/index.d.ts

@@ -0,0 +1,10 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import { h } from "preact";
+import type { PreparedHomeIntro } from "./types.js";
+export type { IntroNode, PreparedHomeIntro, PreparedHomeIntros } from "./types.js";
+export { resolveHomeIntro } from "./resolve.js";
+/** Synchronous SSR view of output produced by home-intro/prepare. No raw HTML sink. */
+export declare function CompactProse({ intro }: {
+    intro: PreparedHomeIntro | null | undefined;
+}): h.JSX.Element | null;

package/dist/home-intro/index.js

@@ -0,0 +1,20 @@
+import { jsx } from "preact/jsx-runtime";
+import { h } from "preact";
+import { defaultComponents } from "../content/index.js";
+import { makeAdmonition } from "../content-admonition/index.js";
+import { resolveHomeIntro } from "./resolve.js";
+const { h2: _h2, h3: _h3, h4: _h4, ...typography } = defaultComponents;
+const components = { ...typography };
+for (const variant of ["note", "tip", "info", "warning", "danger", "caution", "important"]) components[variant] = makeAdmonition(variant);
+function renderNode(node) {
+  if (typeof node === "string") return node;
+  return h(components[node.tag] ?? node.tag, node.attrs, node.children.map(renderNode));
+}
+function CompactProse({ intro }) {
+  if (!intro?.nodes.length) return null;
+  return /* @__PURE__ */ jsx("div", { class: "zd-content zd-compact-prose", children: intro.nodes.map(renderNode) });
+}
+export {
+  CompactProse,
+  resolveHomeIntro
+};

package/dist/home-intro/prepare.d.ts

@@ -0,0 +1,9 @@
+import type { Settings } from "../settings.js";
+import type { PreparedHomeIntro, PreparedHomeIntros } from "./types.js";
+export type HomeIntroSettings = Pick<Settings, "home" | "locales" | "defaultLocale" | "base" | "mermaid" | "transclude">;
+/** URL context is the localized homepage, never an invented Markdown file. */
+export declare function resolveIntroUrl(value: string, settings: Pick<HomeIntroSettings, "base" | "defaultLocale">, locale: string, image?: boolean): string;
+/** Async preparation seam. No author JavaScript is ever compiled or evaluated. */
+export declare function prepareHomeIntro(source: string, settings: HomeIntroSettings, locale: string): Promise<PreparedHomeIntro | null>;
+/** Prepare every configured locale once in the async virtual-context loader. */
+export declare function prepareHomeIntros(settings: HomeIntroSettings): Promise<PreparedHomeIntros>;

package/dist/home-intro/prepare.js

@@ -0,0 +1,93 @@
+import { parseFragment } from "parse5";
+import { buildMarkdownFeatures } from "../preset.js";
+import { resolveHomeIntro } from "./resolve.js";
+const origin = "https://home-intro.invalid";
+function resolveIntroUrl(value, settings, locale, image = false) {
+  const url = value.trim();
+  if (/[\u0000-\u001f\u007f\\]/u.test(url)) throw new Error("home.introMarkdown: URL contains controls or backslashes");
+  if (url.startsWith("#")) return url;
+  if (url.startsWith("//")) throw new Error("home.introMarkdown: protocol-relative URLs are unsupported");
+  const base = `/${settings.base.split("/").filter(Boolean).join("/")}`;
+  const prefix = base === "/" ? "" : base;
+  const home = `${prefix}/${locale === settings.defaultLocale ? "" : `${locale}/`}`;
+  if (url.startsWith("/")) {
+    const based = prefix && url !== prefix && !url.startsWith(`${prefix}/`) && !url.startsWith(`${prefix}?`) && !url.startsWith(`${prefix}#`) ? `${prefix}${url}` : url;
+    const parsed2 = new URL(based, origin);
+    return `${parsed2.pathname}${parsed2.search}${parsed2.hash}`;
+  }
+  const parsed = new URL(url, `${origin}${home}`);
+  const allowed = image ? ["https:", "http:"] : ["https:", "http:", "mailto:", "tel:"];
+  if (!allowed.includes(parsed.protocol)) throw new Error(`home.introMarkdown: unsafe URL scheme ${parsed.protocol}`);
+  if (!/^[a-z][a-z0-9+.-]*:/iu.test(url)) return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  return url;
+}
+function inspect(node, settings, locale, source = "") {
+  if (node.type === "mdxTextExpression" && (source.slice(node.position.end.offset, node.position.end.offset + 2) === "^{" || source[node.position.start.offset - 1] === "^")) return;
+  if (node.type === "html" || node.type.startsWith("mdx") || node.type === "yaml" || node.type.endsWith("Directive")) {
+    throw new Error(`home.introMarkdown: unsupported ${node.type} at line ${node.position.start.line}; use plain Markdown, without HTML, JSX, imports, frontmatter or directives`);
+  }
+  if (node.type === "paragraph" && Array.isArray(node.children) && node.children[0]?.type === "text") {
+    const first = node.children[0].value.trimStart();
+    if (["import", "export"].includes(first.split(/\s+/u)[0] ?? "")) {
+      throw new Error("home.introMarkdown: import/export statements are unsupported");
+    }
+  }
+  if ("url" in node && typeof node.url === "string") resolveIntroUrl(node.url, settings, locale, node.type === "image");
+  if ("children" in node && Array.isArray(node.children)) for (const child of node.children) inspect(child, settings, locale, source);
+}
+const allowedTags = new Set("p h1 h2 h3 h4 h5 h6 a img em strong del ul ol li blockquote pre code span br hr table thead tbody tr th td input div ruby rb rt rp note tip info warning danger caution important".split(" "));
+const plainAttrs = /* @__PURE__ */ new Set(["title", "alt", "class", "id", "start", "align", "width", "height", "data-mermaid", "data-lang"]);
+function prepareNode(node, settings, locale) {
+  if (node.nodeName === "#text") return node.value;
+  if (!("tagName" in node)) return null;
+  if (!allowedTags.has(node.tagName) || node.namespaceURI !== "http://www.w3.org/1999/xhtml") throw new Error(`home.introMarkdown: unsupported rendered element ${node.tagName}`);
+  if (node.tagName === "a" && node.attrs.some((attr) => attr.name === "class" && attr.value.split(" ").includes("hash-link"))) return null;
+  const attrs = {};
+  for (const { name, value } of node.attrs) {
+    if (name === "href" && node.tagName === "a") attrs.href = resolveIntroUrl(value, settings, locale);
+    else if (name === "src" && node.tagName === "img") attrs.src = resolveIntroUrl(value, settings, locale, true);
+    else if (name === "style" && ["th", "td"].includes(node.tagName) && ["text-align: left", "text-align: center", "text-align: right"].includes(value)) attrs.style = value;
+    else if (plainAttrs.has(name)) attrs[name === "class" ? "className" : name] = value;
+    else if (node.tagName === "input" && name === "type" && value === "checkbox") attrs.type = value;
+    else if (node.tagName === "input" && (name === "checked" || name === "disabled")) attrs[name] = true;
+    else throw new Error(`home.introMarkdown: unsupported rendered attribute ${name}`);
+  }
+  if (node.tagName === "input") {
+    attrs.type = "checkbox";
+    attrs.disabled = true;
+  }
+  return { tag: node.tagName === "h1" ? "h2" : node.tagName, attrs, children: node.childNodes.map((child) => prepareNode(child, settings, locale)).filter((child) => child !== null) };
+}
+async function prepareHomeIntro(source, settings, locale) {
+  if (!source.trim()) return null;
+  const [{ parseToAst }, { renderHtml }] = await Promise.all([
+    import("@takazudo/zfb-md-wasm/parse"),
+    import("@takazudo/zfb-md-wasm/render")
+  ]).catch((cause) => {
+    throw new Error("home.introMarkdown: the public @takazudo/zfb-md-wasm parse/render peer is required for nonblank introductions", { cause });
+  });
+  const parsed = await parseToAst(source, { dialect: "markdown", directives: true, frontmatter: "node" });
+  if (!parsed.ast) throw new Error(`home.introMarkdown: ${parsed.diagnostics.map((d) => d.message).join("; ")}`);
+  inspect(parsed.ast, settings, locale);
+  const mdx = await parseToAst(source, { dialect: "mdx", frontmatter: "none" });
+  if (mdx.ast) inspect(mdx.ast, settings, locale, source);
+  const features = buildMarkdownFeatures(settings, {});
+  for (const feature of ["transclude", "imageDimensions", "linkValidation", "codeTabs", "codeEnrichment", "tocExport", "readingTime", "headingMarkerToc"]) delete features[feature];
+  const rendered = await renderHtml(source, { dialect: "markdown", pipeline: { gfm: { taskListItem: true, strikethrough: true, table: true, autolinkLiteral: true }, codeHighlight: { mode: "class" }, features } });
+  if (rendered.html === null || rendered.diagnostics.length) throw new Error(`home.introMarkdown: ${rendered.diagnostics.map((d) => d.message).join("; ")}`);
+  const nodes = parseFragment(rendered.html).childNodes.map((node) => prepareNode(node, settings, locale)).filter((node) => node !== null);
+  return nodes.length ? { nodes } : null;
+}
+async function prepareHomeIntros(settings) {
+  const result = {};
+  if (!settings.home?.introMarkdown?.trim() && !Object.values(settings.locales ?? {}).some((locale) => locale.introMarkdown?.trim())) return result;
+  for (const locale of /* @__PURE__ */ new Set([settings.defaultLocale, ...Object.keys(settings.locales ?? {})])) {
+    result[locale] = await prepareHomeIntro(resolveHomeIntro(settings, locale, "").introMarkdown, settings, locale);
+  }
+  return result;
+}
+export {
+  prepareHomeIntro,
+  prepareHomeIntros,
+  resolveIntroUrl
+};

package/dist/home-intro/resolve.d.ts

@@ -0,0 +1,5 @@
+import type { Settings } from "../settings.js";
+export declare function resolveHomeIntro(settings: Pick<Settings, "home" | "locales">, locale: string, translatedSitemapHeading: string): {
+    introMarkdown: string;
+    sitemapHeading: string;
+};

package/dist/home-intro/resolve.js

@@ -0,0 +1,10 @@
+function resolveHomeIntro(settings, locale, translatedSitemapHeading) {
+  const localized = settings.locales[locale];
+  return {
+    introMarkdown: localized?.introMarkdown ?? settings.home?.introMarkdown ?? "",
+    sitemapHeading: (localized?.sitemapHeading ?? settings.home?.sitemapHeading)?.trim() || translatedSitemapHeading
+  };
+}
+export {
+  resolveHomeIntro
+};

package/dist/home-intro/types.d.ts

@@ -0,0 +1,10 @@
+/** Safe, serializable production-renderer output. Only the preparation helper creates it. */
+export type IntroNode = string | {
+    tag: string;
+    attrs: Record<string, string | boolean>;
+    children: IntroNode[];
+};
+export interface PreparedHomeIntro {
+    nodes: IntroNode[];
+}
+export type PreparedHomeIntros = Record<string, PreparedHomeIntro | null>;

package/dist/home-page/index.js

@@ -3,6 +3,7 @@ import { Fragment as Fragment2 } from "preact";
 import { Island } from "@takazudo/zfb";
 import { AutoLogo } from "../auto-logo/index.js";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { CompactProse, resolveHomeIntro } from "../home-intro/index.js";
 import { SiteTreeNav } from "../site-tree-nav-island/index.js";
 import { TagNav } from "../nav-indexing/tag-nav.js";
 import { CategoryLinkIcon } from "../tree-nav-shared/index.js";
@@ -12,6 +13,9 @@ import { deriveComposeMetaTitle, deriveBodyEndIslands, deriveDateFormats } from
 import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 import { prepareHomeData } from "./prepare-home-data.js";
+function HomeSectionHeading({ children }) {
+  return /* @__PURE__ */ jsx("h2", { class: "text-title font-bold mb-vsp-md", children });
+}
 function cssUrl(url) {
   return `url("${url.replace(/[\\"]/g, "\\$&")}")`;
 }
@@ -28,6 +32,7 @@ function createHomePageView(ctx) {
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const homeExtras = ctx.hostBindings.homeExtras;
+  const homeIntros = ctx.homeIntros;
   const dataThemePack = resolveThemePackSsrSlug(
     ctx.themePackRegistry,
     ctx.settings
@@ -49,11 +54,18 @@ function createHomePageView(ctx) {
     const primary = heroLink ? { href: withBase(`${prefix}${heroLink.path}`), label: t(heroLink.labelKey, locale) } : ctaNav ? { href: withBase(`${prefix}${ctaNav.path}`), label: t("nav.overview", locale) } : null;
     const logoSetting = settings.logo ?? "auto";
     const resolvedExtras = extras ?? homeExtras?.({ locale });
+    const intro = homeIntros?.[locale] ?? null;
+    const hasIntro = Boolean(intro?.nodes.length);
+    const sitemapHeading = resolveHomeIntro(
+      settings,
+      locale,
+      t("home.sitemapHeading", locale)
+    ).sitemapHeading;
     const hasExtras = resolvedExtras != null && typeof resolvedExtras !== "boolean";
     const rowItems = [];
     if (primary) {
       rowItems.push(
-        /* @__PURE__ */ jsx("a", { href: primary.href, class: "whitespace-nowrap text-fg underline hover:text-accent", children: primary.label })
+        /* @__PURE__ */ jsx("a", { href: primary.href, class: "text-fg underline hover:text-accent", children: primary.label })
       );
     }
     if (settings.githubUrl) {
@@ -62,7 +74,7 @@ function createHomePageView(ctx) {
           "a",
           {
             href: settings.githubUrl,
-            class: "inline-flex items-center gap-[0.3em] whitespace-nowrap text-fg underline hover:text-accent",
+            class: "inline-flex items-center gap-[0.3em] text-fg underline hover:text-accent",
             target: "_blank",
             rel: "noopener noreferrer",
             children: [
@@ -99,7 +111,7 @@ function createHomePageView(ctx) {
         bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
         enableClientRouter: settings.dynamicPageTransition,
         children: [
-          /* @__PURE__ */ jsx("div", { class: "flex justify-center mb-vsp-xl", children: /* @__PURE__ */ jsxs("div", { class: "flex flex-col items-center text-center gap-hsp-md lg:flex-row lg:text-left lg:gap-hsp-xl", children: [
+          /* @__PURE__ */ jsx("div", { class: "zd-home-hero mb-vsp-xl", children: /* @__PURE__ */ jsxs("div", { class: "zd-home-inner flex flex-col items-center justify-center text-center gap-hsp-md lg:flex-row lg:text-left lg:gap-hsp-xl", children: [
             logoSetting === "auto" ? /* @__PURE__ */ jsx(
               AutoLogo,
               {
@@ -117,32 +129,40 @@ function createHomePageView(ctx) {
                 "aria-hidden": "true"
               }
             ) : null,
-            /* @__PURE__ */ jsxs("div", { class: "min-w-0", children: [
+            /* @__PURE__ */ jsxs("div", { class: "zd-home-copy min-w-0 lg:flex-1", children: [
               /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs break-words", children: settings.siteName }),
               /* @__PURE__ */ jsx("p", { class: "text-muted text-small mb-vsp-sm", children: settings.locales[locale]?.description ?? settings.siteDescription }),
-              /* @__PURE__ */ jsx("div", { class: "flex flex-wrap items-center justify-center lg:justify-start gap-hsp-md text-small", children: rowItems.map((item, index) => /* @__PURE__ */ jsxs(Fragment2, { children: [
+              /* @__PURE__ */ jsx("div", { class: "zd-home-links flex flex-wrap items-center justify-center lg:justify-start gap-hsp-md text-small", children: rowItems.map((item, index) => /* @__PURE__ */ jsxs(Fragment2, { children: [
                 index > 0 && /* @__PURE__ */ jsx("span", { class: "text-muted", children: "/" }),
                 item
               ] }, index)) })
             ] })
           ] }) }),
-          Island({
-            when: "idle",
-            children: /* @__PURE__ */ jsx(
-              SiteTreeNav,
-              {
-                tree,
-                categoryOrder,
-                categoryIgnore,
-                initiallyCollapsedCategorySlugs,
-                locale,
-                updatedLabel: t("doc.updated", locale),
-                dateFormats: dateFormatsFor(locale)
-              }
-            )
-          }),
+          hasIntro && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("hr", { class: "zd-home-rule", "data-home-rule": "upper" }),
+            /* @__PURE__ */ jsx("div", { class: "zd-home-intro", children: /* @__PURE__ */ jsx("div", { class: "zd-home-inner", children: /* @__PURE__ */ jsx(CompactProse, { intro }) }) })
+          ] }),
+          /* @__PURE__ */ jsx("hr", { class: "zd-home-rule", "data-home-rule": "lower" }),
+          /* @__PURE__ */ jsxs("section", { class: "zd-home-sitemap", children: [
+            /* @__PURE__ */ jsx(HomeSectionHeading, { children: sitemapHeading }),
+            Island({
+              when: "idle",
+              children: /* @__PURE__ */ jsx(
+                SiteTreeNav,
+                {
+                  tree,
+                  categoryOrder,
+                  categoryIgnore,
+                  initiallyCollapsedCategorySlugs,
+                  locale,
+                  updatedLabel: t("doc.updated", locale),
+                  dateFormats: dateFormatsFor(locale)
+                }
+              )
+            })
+          ] }),
           settings.docTags && tagCount > 0 && /* @__PURE__ */ jsx("section", { class: "mt-vsp-xl", children: tags && tags.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx("h2", { class: "text-title font-bold mb-vsp-md", children: t("doc.tags", locale) }),
+            /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.tags", locale) }),
             /* @__PURE__ */ jsx(
               TagNav,
               {
@@ -171,7 +191,7 @@ function createHomePageView(ctx) {
             // reproduce the pre-#3027 single "All Tags" link so existing
             // `@takazudo/zudo-doc/home-page` consumers are unaffected.
             /* @__PURE__ */ jsxs(Fragment, { children: [
-              /* @__PURE__ */ jsx("h2", { class: "text-title font-bold mb-vsp-md", children: t("doc.allTags", locale) }),
+              /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.allTags", locale) }),
               /* @__PURE__ */ jsx(
                 "a",
                 {

package/dist/i18n-defaults/index.js

@@ -1,5 +1,6 @@
 const defaultTranslations = {
   en: {
+    "home.sitemapHeading": "Explore the documentation",
     "nav.gettingStarted": "Getting Started",
     "nav.learn": "Learn",
     "nav.guides": "Guides",
@@ -128,6 +129,7 @@ const defaultTranslations = {
     "version.page.docs": "Docs"
   },
   ja: {
+    "home.sitemapHeading": "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u63A2\u3059",
     "nav.gettingStarted": "\u306F\u3058\u3081\u306B",
     "nav.learn": "\u5B66\u3076",
     "nav.guides": "\u30AC\u30A4\u30C9",