@takazudo/zudo-doc 5.20.0 → 5.22.0

package/dist/plugins/doc-history.js

@@ -29,8 +29,10 @@ const plugin = {
     });
   },
   async postBuild(ctx) {
+    const options = ctx.options;
+    if (options.ui === false) return;
     try {
-      await runDocHistoryPostBuild(ctx.options, {
+      await runDocHistoryPostBuild(options, {
         outDir: ctx.outDir,
         logger: ctx.logger
       });
@@ -44,11 +46,13 @@ const plugin = {
     }
   },
   devMiddleware(ctx) {
+    const options = ctx.options;
+    if (options.ui === false) return;
     const middleware = createDocHistoryDevMiddleware(
-      ctx.options,
+      options,
       ctx.logger
     );
-    const basePrefix = getBasePrefix(ctx.options["base"]);
+    const basePrefix = getBasePrefix(options.base);
     ctx.register(`${basePrefix}/doc-history`, connectToZfbHandler(middleware));
   }
 };

package/dist/plugins/img-src-check.d.ts

@@ -0,0 +1,3 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/img-src-check.js

@@ -0,0 +1,21 @@
+import { checkImgSrcs } from "./internal/img-src-check/index.js";
+function severity(value) {
+  return value === "error" || value === "ignore" ? value : "warn";
+}
+const plugin = {
+  name: "img-src-check",
+  postBuild(ctx) {
+    const onBroken = severity(ctx.options["onBroken"]);
+    if (onBroken === "ignore") return;
+    checkImgSrcs({
+      outDir: ctx.outDir,
+      base: typeof ctx.options["base"] === "string" ? ctx.options["base"] : "/",
+      onBroken,
+      logger: ctx.logger
+    });
+  }
+};
+var img_src_check_default = plugin;
+export {
+  img_src_check_default as default
+};

package/dist/plugins/internal/claude-resources/generate.js

@@ -133,7 +133,7 @@ sidebar_label: "${escapeTitle(name)}"
 generated: true
 ---
 
-${escapeForMdx(parsed.content.trim())}
+${escapeForMdx(downgradeRepoRelativeLinks(parsed.content.trim()))}
 `;
     fs.writeFileSync(path.join(outputDir, `${name}.mdx`), mdx);
   }
@@ -196,7 +196,7 @@ generated: true
 ---
 
 ${modelBadge}
-${escapeForMdx(parsed.content.trim())}
+${escapeForMdx(downgradeRepoRelativeLinks(parsed.content.trim()))}
 `;
     fs.writeFileSync(path.join(outputDir, `${fileSlug}.mdx`), mdx);
   }

package/dist/plugins/internal/doc-history/index.d.ts

@@ -13,6 +13,10 @@ export interface DocHistoryOptions {
     locales?: Record<string, DocHistoryLocaleConfig>;
     /** Slug globs excluded from pre-build metadata and post-build history JSON. */
     exclude?: string[];
+    /** Whether the history UI, JSON generation, and dev proxy are enabled. Defaults to `true`. */
+    ui?: boolean;
+    /** Site base path used when registering the dev proxy route. */
+    base?: string;
     /**
      * Port the standalone `@takazudo/zudo-doc-history-server` listens on.
      * Defaults to `4322` to match the server's CLI default. Only used by
@@ -118,7 +122,8 @@ export declare function shouldGeneratePostBuild(env?: NodeJS.ProcessEnv): {
  * `@takazudo/zudo-doc-history-server` to write per-page git history JSON
  * files into `<outDir>/doc-history/`.
  *
- * Generation is gated by `shouldGeneratePostBuild` (see its docs): skipped by
+ * Generation is gated by `options.ui` and `shouldGeneratePostBuild` (see its
+ * docs): `ui: false` is always skipped; otherwise generation is skipped by
  * default on local builds (opt in with `GEN_DOC_HISTORY=1`), run in CI and
  * when explicitly opted in, and always suppressed by `SKIP_DOC_HISTORY=1` or
  * `DOC_HISTORY_SKIP_POSTBUILD=1`.

package/dist/plugins/internal/doc-history/index.js

@@ -70,6 +70,7 @@ function isCiEnv(env) {
   return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true";
 }
 async function runDocHistoryPostBuild(options, ctx) {
+  if (options.ui === false) return;
   const { generate, reason } = shouldGeneratePostBuild();
   if (!generate) {
     ctx.logger?.info(`Skipping doc history generation (${reason})`);

package/dist/plugins/internal/img-src-check/index.d.ts

@@ -0,0 +1,65 @@
+/** Severity used by the raw image-source check. */
+export type ImgSrcCheckSeverity = "warn" | "error" | "ignore";
+/** Logger surface needed by the scanner's reporting phase. */
+export interface ImgSrcCheckLogger {
+    warn(message: string): void;
+}
+/** One raw image reference that could not be resolved to a file. */
+export interface BrokenImgSrc {
+    /** HTML page path relative to the build output directory. */
+    pagePath: string;
+    /** The decoded attribute value as authored in the rendered HTML. */
+    src: string;
+    /** Why the reference was considered broken. */
+    reason: string;
+}
+/** Result returned by the filesystem scanner before reporting. */
+export interface ImgSrcCheckResult {
+    /** Number of HTML files visited under `outDir`. */
+    htmlFileCount: number;
+    /** Number of site-absolute `src` attributes inspected. */
+    imageCount: number;
+    /** Every broken occurrence, including duplicate references. */
+    broken: BrokenImgSrc[];
+}
+/** Options for scanning and reporting built HTML. */
+export interface ImgSrcCheckOptions {
+    /** Absolute or relative build output directory. */
+    outDir: string;
+    /** URL base configured for the build (for example `/docs/`). */
+    base?: string;
+    /** Broken-reference behavior. Defaults to `warn`. */
+    onBroken?: ImgSrcCheckSeverity;
+    /** zfb's logger. A missing logger makes the scan quiet. */
+    logger?: ImgSrcCheckLogger;
+}
+/**
+ * Parse rendered HTML and return the `src` values on real `<img>` elements.
+ *
+ * parse5 performs HTML tokenisation (including comment/script handling) and
+ * decodes character references in attribute values. Walking its element tree
+ * therefore avoids false positives from comments, script bodies, and escaped
+ * code examples without trying to emulate an HTML parser with regular
+ * expressions.
+ */
+export declare function extractImgSrcs(html: string): string[];
+/** Normalize a zfb base to a slash-delimited URL prefix. */
+export declare function normalizeImgSrcBase(base: string | undefined): string;
+/**
+ * Walk every built HTML file and validate its site-absolute image sources.
+ *
+ * This is intentionally synchronous: zfb's postBuild hook is async-compatible
+ * but the operation is a deterministic local filesystem walk, and a sync
+ * implementation keeps result ordering stable for warnings and tests.
+ */
+export declare function scanImgSrcs(options: ImgSrcCheckOptions): ImgSrcCheckResult;
+/** Format one warning in a stable, page-first form suitable for zfb output. */
+export declare function formatBrokenImgSrc(reference: BrokenImgSrc): string;
+/**
+ * Run the scanner and report every broken occurrence. Error mode reports the
+ * complete set first, then throws so zfb fails the build with all diagnostics.
+ */
+export declare function checkImgSrcs(options: ImgSrcCheckOptions): ImgSrcCheckResult;
+export declare const extractImageSources: typeof extractImgSrcs;
+export declare const scanImageSources: typeof scanImgSrcs;
+export declare const checkImageSources: typeof checkImgSrcs;

package/dist/plugins/internal/img-src-check/index.js

@@ -0,0 +1,179 @@
+import { realpathSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { parse } from "parse5";
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/u;
+function extractImgSrcs(html) {
+  const document = parse(html);
+  const srcs = [];
+  const visit = (node) => {
+    if (!("tagName" in node)) return;
+    const element = node;
+    if (element.tagName.toLowerCase() === "img" && element.namespaceURI === HTML_NAMESPACE) {
+      const src = element.attrs.find((attribute) => attribute.name.toLowerCase() === "src")?.value;
+      if (src !== void 0) srcs.push(src);
+    }
+    for (const child of element.childNodes) visit(child);
+    if (element.nodeName === "template") {
+      const template = element;
+      for (const child of template.content.childNodes) visit(child);
+    }
+  };
+  for (const child of document.childNodes) visit(child);
+  return srcs;
+}
+function normalizeImgSrcBase(base) {
+  if (!base || base === "/") return "/";
+  const withLeadingSlash = base.startsWith("/") ? base : `/${base}`;
+  const segments = withLeadingSlash.split("/").filter(Boolean);
+  return segments.length === 0 ? "/" : `/${segments.join("/")}/`;
+}
+function isWithin(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep);
+}
+function stripQueryAndFragment(src) {
+  const query = src.indexOf("?");
+  const fragment = src.indexOf("#");
+  const end = [query, fragment].filter((index) => index >= 0).sort((a, b) => a - b)[0];
+  return end === void 0 ? src : src.slice(0, end);
+}
+function resolveImgSrc(src, outDir, base, canonicalOutDir) {
+  const value = src.trim();
+  if (!value.startsWith("/") || value.startsWith("//") || SCHEME_RE.test(value)) {
+    return { kind: "skip" };
+  }
+  const pathPart = stripQueryAndFragment(value);
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(pathPart);
+  } catch {
+    return { kind: "broken", reason: "malformed percent escape" };
+  }
+  if (decodedPath.includes("\0")) {
+    return { kind: "broken", reason: "invalid path" };
+  }
+  let relativeUrlPath;
+  if (base === "/") {
+    relativeUrlPath = decodedPath.slice(1).replace(/^\/+/, "");
+  } else {
+    const baseWithoutTrailingSlash = base.slice(0, -1);
+    if (decodedPath === baseWithoutTrailingSlash || decodedPath.startsWith(base)) {
+      relativeUrlPath = decodedPath.slice(base.length).replace(/^\/+/, "");
+    } else {
+      return { kind: "broken", reason: `outside configured base ${base}` };
+    }
+  }
+  const candidate = resolve(outDir, relativeUrlPath);
+  if (!isWithin(outDir, candidate)) {
+    return { kind: "broken", reason: "resolves outside the build output directory" };
+  }
+  let stat;
+  try {
+    stat = statSync(candidate);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { kind: "broken", reason: "file does not exist" };
+    }
+    throw error;
+  }
+  if (!stat.isFile()) return { kind: "broken", reason: "path is not a file" };
+  try {
+    if (!isWithin(canonicalOutDir, realpathSync(candidate))) {
+      return { kind: "broken", reason: "resolves outside the build output directory" };
+    }
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { kind: "broken", reason: "file does not exist" };
+    }
+    throw error;
+  }
+  return { kind: "path", path: candidate };
+}
+function listHtmlFiles(outDir) {
+  const files = [];
+  if (!statSync(outDir).isDirectory()) return files;
+  const walk = (dir) => {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, "en"));
+    for (const entry of entries) {
+      const filePath = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(filePath);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".html")) {
+        files.push(filePath);
+      }
+    }
+  };
+  walk(outDir);
+  return files;
+}
+function scanImgSrcs(options) {
+  const outDir = resolve(options.outDir);
+  let canonicalOutDir;
+  try {
+    canonicalOutDir = realpathSync(outDir);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { htmlFileCount: 0, imageCount: 0, broken: [] };
+    }
+    throw error;
+  }
+  const base = normalizeImgSrcBase(options.base);
+  const htmlFiles = listHtmlFiles(outDir);
+  const broken = [];
+  let imageCount = 0;
+  for (const htmlFile of htmlFiles) {
+    const pagePath = relative(outDir, htmlFile).split(sep).join("/");
+    const html = readFileSync(htmlFile, "utf8");
+    if (!/<img\b/iu.test(html)) continue;
+    for (const src of extractImgSrcs(html)) {
+      const resolved = resolveImgSrc(src, outDir, base, canonicalOutDir);
+      if (resolved.kind === "skip") continue;
+      imageCount += 1;
+      if (resolved.kind === "broken") {
+        broken.push({ pagePath, src, reason: resolved.reason });
+      }
+    }
+  }
+  return { htmlFileCount: htmlFiles.length, imageCount, broken };
+}
+function formatBrokenImgSrc(reference) {
+  return `[img-src-check] Broken image source in ${reference.pagePath}: ${reference.src} (${reference.reason})`;
+}
+function checkImgSrcs(options) {
+  const severity = options.onBroken ?? "warn";
+  if (severity === "ignore") {
+    return { htmlFileCount: 0, imageCount: 0, broken: [] };
+  }
+  const result = scanImgSrcs(options);
+  if (result.broken.length === 0) return result;
+  if (options.logger) {
+    for (const reference of result.broken) options.logger.warn(formatBrokenImgSrc(reference));
+    options.logger.warn(
+      `[img-src-check] Found ${result.broken.length} broken image source${result.broken.length === 1 ? "" : "s"} in ${result.htmlFileCount} HTML file${result.htmlFileCount === 1 ? "" : "s"}.`
+    );
+  }
+  if (severity === "error") {
+    throw new Error(
+      `[img-src-check] Build contains ${result.broken.length} broken image source${result.broken.length === 1 ? "" : "s"}.`
+    );
+  }
+  return result;
+}
+const extractImageSources = extractImgSrcs;
+const scanImageSources = scanImgSrcs;
+const checkImageSources = checkImgSrcs;
+export {
+  checkImageSources,
+  checkImgSrcs,
+  extractImageSources,
+  extractImgSrcs,
+  formatBrokenImgSrc,
+  normalizeImgSrcBase,
+  scanImageSources,
+  scanImgSrcs
+};

package/dist/plugins/internal/resource-docs-shared/index.d.ts

@@ -3,7 +3,7 @@ export { cleanDir, ensureDir, listFiles, removeGeneratedIndex, resolveLocaleDirs
 export { resolveLabel, resolveResourceLabel, type ResolveResourceLabelOptions, type ResourceTranslations, } from "./labels.js";
 export { shouldEmitResourceLocaleRoute, type ResourceLocaleRouteOptions, } from "./locale-routes.js";
 export { assertNotIndexReserved, escapeTitle, formatFrontmatterString, parseFrontmatter, type FrontmatterStringRenderer, type MdxFileWriter, writeCategoryIndex, writeUnlistedSubPage, } from "./mdx.js";
-export { isRepoRelativeLink, downgradeRepoRelativeLinks } from "./links.js";
+export { isRepoRelativeLink, rewriteMarkdownLinks, downgradeRepoRelativeLinks, } from "./links.js";
 export { escapeMarkdownTableCell, renderCodeFence, } from "./markdown-structure.js";
 export { EXCLUDED_DIR_NAMES, findNamedFiles } from "./walk.js";
 export { generateSkillsCategory, getScriptDescription, getSkillFileTree, getSkillReferences, type GenerateSkillsCategoryOptions, type RenderExtraHeader, type SkillItem, type SkillReference, } from "./skills.js";

package/dist/plugins/internal/resource-docs-shared/index.js

@@ -22,7 +22,11 @@ import {
   writeCategoryIndex,
   writeUnlistedSubPage
 } from "./mdx.js";
-import { isRepoRelativeLink, downgradeRepoRelativeLinks } from "./links.js";
+import {
+  isRepoRelativeLink,
+  rewriteMarkdownLinks,
+  downgradeRepoRelativeLinks
+} from "./links.js";
 import {
   escapeMarkdownTableCell,
   renderCodeFence
@@ -57,6 +61,7 @@ export {
   resolveLabel,
   resolveLocaleDirs,
   resolveResourceLabel,
+  rewriteMarkdownLinks,
   shouldEmitResourceLocaleRoute,
   writeCategoryIndex,
   writeGeneratedIndex,

package/dist/plugins/internal/resource-docs-shared/links.d.ts

@@ -6,6 +6,11 @@
  * anchor (`#…`), or a scheme (`mailto:`, `tel:`).
  */
 export declare function isRepoRelativeLink(url: string): boolean;
+/**
+ * Rewrite markdown link destinations outside fenced and inline code.
+ * Returning `undefined` from `rewrite` leaves that link unchanged.
+ */
+export declare function rewriteMarkdownLinks(content: string, rewrite: (url: string) => string | undefined): string;
 /**
  * Downgrade repo-relative markdown links in a mirrored `CLAUDE.md` body to
  * inline code so they don't dangle in the flattened mirror tree (#2411).
@@ -19,4 +24,4 @@ export declare function isRepoRelativeLink(url: string): boolean;
  * Code spans are preserved verbatim: a `[x](./y)` inside a fenced block or an
  * inline-code span is literal text, not a link, and must not be rewritten.
  */
-export declare function downgradeRepoRelativeLinks(content: string): string;
+export declare function downgradeRepoRelativeLinks(content: string, keep?: (url: string) => boolean): string;

package/dist/plugins/internal/resource-docs-shared/links.js

@@ -6,7 +6,7 @@ function isRepoRelativeLink(url) {
   if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false;
   return true;
 }
-function downgradeRepoRelativeLinks(content) {
+function transformMarkdownLinks(content, transform) {
   const blockPlaceholder = "\0CRLINK_BLOCK_";
   const inlinePlaceholder = "\0CRLINK_INLINE_";
   const codeBlocks = [];
@@ -26,7 +26,7 @@ function downgradeRepoRelativeLinks(content) {
     );
     const rewritten = withInline.replace(
       /!?\[([^\]]*)\]\(([^)]+)\)/g,
-      (match, text, url) => isRepoRelativeLink(url) ? `\`${text}\`` : match
+      (match, text, url) => transform(match, text, url)
     );
     return rewritten.replace(
       new RegExp(`${inlinePlaceholder}(\\d+)\0`, "g"),
@@ -38,7 +38,25 @@ function downgradeRepoRelativeLinks(content) {
     (_, idx) => codeBlocks[Number(idx)] ?? ""
   );
 }
+function rewriteMarkdownLinks(content, rewrite) {
+  return transformMarkdownLinks(content, (match, _text, url) => {
+    const replacement = rewrite(url);
+    if (replacement === void 0) return match;
+    const urlStart = match.length - url.length - 1;
+    if (urlStart < 0 || match.slice(urlStart, urlStart + url.length) !== url) {
+      return match;
+    }
+    return `${match.slice(0, urlStart)}${replacement}${match.slice(urlStart + url.length)}`;
+  });
+}
+function downgradeRepoRelativeLinks(content, keep) {
+  return transformMarkdownLinks(
+    content,
+    (match, text, url) => isRepoRelativeLink(url) && !(keep?.(url) ?? false) ? `\`${text}\`` : match
+  );
+}
 export {
   downgradeRepoRelativeLinks,
-  isRepoRelativeLink
+  isRepoRelativeLink,
+  rewriteMarkdownLinks
 };

package/dist/plugins/internal/resource-docs-shared/skills.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { escapeForMdx } from "./escape-for-mdx.js";
+import {
+  downgradeRepoRelativeLinks,
+  rewriteMarkdownLinks
+} from "./links.js";
 import {
   assertNotIndexReserved,
   escapeTitle,
@@ -236,8 +240,26 @@ ${tree}${linkList}`;
         );
       }
     }
-    let skillBody = parsed.content.trim();
-    skillBody = skillBody.replace(/\]\(references\/([^)]+)\.md\)/g, "](./ref-$1)").replace(/\]\(scripts\/([^)]+)\.md\)/g, "](./script-$1)").replace(/\]\(assets\/([^)]+)\.md\)/g, "](./asset-$1)");
+    const skillLinkRewrites = /* @__PURE__ */ new Map();
+    for (const ref of references) {
+      skillLinkRewrites.set(`references/${ref.name}.md`, `./ref-${ref.name}`);
+    }
+    for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
+      const slug = f.replace(/\.md$/, "");
+      skillLinkRewrites.set(`scripts/${f}`, `./script-${slug}`);
+    }
+    for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
+      const slug = f.replace(/\.md$/, "");
+      skillLinkRewrites.set(`assets/${f}`, `./asset-${slug}`);
+    }
+    const emittedSkillLinks = new Set(skillLinkRewrites.values());
+    const skillBody = downgradeRepoRelativeLinks(
+      rewriteMarkdownLinks(
+        parsed.content.trim(),
+        (url) => skillLinkRewrites.get(url)
+      ),
+      (url) => emittedSkillLinks.has(url)
+    );
     const body = [
       extraHeader,
       fileStructureSection,
@@ -259,7 +281,7 @@ ${body}`;
       writeUnlistedSubPage(
         path.join(skillDirOut, `ref-${ref.name}.mdx`),
         ref.title,
-        escapeForMdx(ref.content.trim()),
+        escapeForMdx(downgradeRepoRelativeLinks(ref.content.trim())),
         renderFrontmatterString
       );
     }
@@ -280,7 +302,7 @@ ${body}`;
       writeUnlistedSubPage(
         path.join(skillDirOut, `script-${slug}.mdx`),
         title,
-        escapeForMdx(raw.trim()),
+        escapeForMdx(downgradeRepoRelativeLinks(raw.trim())),
         renderFrontmatterString
       );
     }
@@ -301,7 +323,7 @@ ${body}`;
       writeUnlistedSubPage(
         path.join(skillDirOut, `asset-${slug}.mdx`),
         title,
-        escapeForMdx(raw.trim()),
+        escapeForMdx(downgradeRepoRelativeLinks(raw.trim())),
         renderFrontmatterString
       );
     }

package/dist/plugins/routes.js

@@ -1,3 +1,4 @@
+import { prepareHomeIntros } from "../home-intro/prepare.js";
 import { createRequire } from "node:module";
 import { existsSync, statSync, readFileSync, cpSync, rmSync, mkdirSync } from "node:fs";
 import { dirname, basename, join } from "node:path";
@@ -242,6 +243,7 @@ const plugin = definePlugin({
       async () => {
         beginLoader("context");
         if (assetViewer && !highlightCodeReady) await assetBodiesLoader(false);
+        const homeIntros = await prepareHomeIntros(settings);
         const assetManifest = assetViewer ? (await getSnapshot()).manifest : null;
         return `export const routeContext = ${JSON.stringify({
           settings,
@@ -249,7 +251,8 @@ const plugin = definePlugin({
           tagVocabulary,
           colorSchemes,
           themePackRegistry,
-          assetManifest
+          assetManifest,
+          homeIntros
         })};
 `;
       },

package/dist/preset.d.ts

@@ -34,11 +34,12 @@
  */
 import { z } from "zod";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { AssetViewerIndexingConfig, TagVocabularyEntry, FaviconConfig } from "./settings.js";
+import type { AssetViewerIndexingConfig, TagVocabularyEntry, FaviconConfig, HomeConfig } from "./settings.js";
 import type { DirectiveSpec } from "@takazudo/zfb/config";
 /** A single locale's content directory (`settings.locales[code]`). */
 export interface PresetLocaleConfig {
     dir: string;
+    introMarkdown?: string;
 }
 /** A single docs version (`settings.versions[n]`). */
 export interface PresetVersionConfig {
@@ -94,6 +95,8 @@ export interface PresetSettings {
     base: string;
     siteName: string;
     siteDescription: string;
+    /** Serializable home prose requires the preparation virtual module even with host routes. */
+    home?: HomeConfig;
     /**
      * Home-hero logo. `zudoDocPreset()` doesn't otherwise consume this field —
      * rendering happens in `home-page/index.tsx` against the full `Settings`
@@ -116,7 +119,11 @@ export interface PresetSettings {
     onBrokenMarkdownLinks: "warn" | "error" | "ignore";
     llmsTxt?: boolean;
     changelogs?: PresetChangelogConfig[] | false;
+    /** Metadata fields shown in the doc metadata area. */
+    docMetainfoFields?: Array<"created" | "updated" | "author">;
     docHistory?: boolean;
+    /** Whether the doc history dropdown UI and related artifacts are enabled. */
+    docHistoryUi?: boolean;
     docHistoryExclude?: string[];
     /** Generate package-owned viewer pages for files under the configured asset directory. */
     assetViewer?: boolean;
@@ -311,3 +318,4 @@ export interface ZudoDocPresetResult {
  * ```
  */
 export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, colorSchemes, }: ZudoDocPresetArgs): ZudoDocPresetResult;
+export declare function buildMarkdownFeatures(settings: Pick<PresetSettings, "mermaid" | "transclude">, directiveVocabulary: DirectiveVocabulary): Record<string, boolean | Record<string, unknown>>;

package/dist/preset.js

@@ -129,6 +129,7 @@ function buildPlugins(settings, routeContext) {
     Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }])
   );
   const effectivePackageOwnedRoutes = settings.packageOwnedRoutes ?? true;
+  const homeIntro = Boolean(settings.home?.introMarkdown?.trim()) || Object.values(settings.locales).some((locale) => Boolean(locale.introMarkdown?.trim()));
   const assetViewer = settings.assetViewer === true;
   const assetViewerDir = settings.assetViewerDir ?? "assets";
   const assetViewerRoutePrefix = settings.assetViewerRoutePrefix ?? "files";
@@ -177,7 +178,7 @@ function buildPlugins(settings, routeContext) {
     // the route catalog from `settings.locales` / `settings.versions`. Listed
     // FIRST so an injected route is registered before the other plugins'
     // preBuild work runs (ordering is cosmetic — injection happens in `setup`).
-    ...effectivePackageOwnedRoutes || assetViewer ? [
+    ...effectivePackageOwnedRoutes || assetViewer || homeIntro ? [
       {
         name: "@takazudo/zudo-doc/plugins/routes",
         options: {
@@ -240,6 +241,7 @@ function buildPlugins(settings, routeContext) {
           docsDir: settings.docsDir,
           locales: localeRecord,
           base: settings.base,
+          ui: settings.docHistoryUi !== false,
           exclude: settings.docHistoryExclude ?? []
         }
       }
@@ -290,9 +292,21 @@ function buildPlugins(settings, routeContext) {
           changelogs: settings.changelogs.map((changelog) => ({ ...changelog }))
         }
       }
-    ] : []
+    ] : [],
+    // Raw HTML image sources are checked after the build has emitted every
+    // page. Keep this as a bare descriptor so the node-backed scanner never
+    // enters the config-evaluation graph; its severity intentionally follows
+    // the existing broken-markdown-links setting.
+    {
+      name: "@takazudo/zudo-doc/plugins/img-src-check",
+      options: {
+        base: settings.base,
+        onBroken: settings.onBrokenMarkdownLinks
+      }
+    }
   ];
 }
 export {
+  buildMarkdownFeatures,
   zudoDocPreset
 };

package/dist/route-context/index.js

@@ -108,6 +108,7 @@ function createRouteContext(payload, options = {}) {
     colorSchemes,
     themePackRegistry,
     assetManifest,
+    homeIntros: payload.homeIntros ?? {},
     i18n,
     defaultLocale,
     locales,

package/dist/route-context-payload/index.d.ts

@@ -55,6 +55,8 @@ export interface CreateRouteContextPayloadInput {
     themePackRegistry?: ThemePackRegistry | null;
     /** Author-facing asset index replacement. `null` forces the feature inert. */
     assetManifest?: AssetManifest | null;
+    /** Trusted output of the async server home-intro/prepare helper. */
+    homeIntros?: import("../home-intro/types.js").PreparedHomeIntros;
 }
 /**
  * Build the serializable payload consumed by `createRouteContext` from plain

package/dist/route-context-payload/index.js

@@ -41,7 +41,8 @@ function createRouteContextPayload(input) {
     tagVocabulary: input.tagVocabulary ?? [],
     colorSchemes: input.colorSchemes === void 0 ? defaultColorSchemes : input.colorSchemes,
     themePackRegistry,
-    assetManifest: input.assetManifest ?? null
+    assetManifest: input.assetManifest ?? null,
+    homeIntros: input.homeIntros ?? {}
   };
 }
 export {

package/dist/route-context-payload/types.d.ts

@@ -149,4 +149,6 @@ export interface RouteContextPayload<S = Settings> {
     themePackRegistry?: ThemePackRegistry | null;
     /** Asset-viewer index payload. Omitted by older hosts; omission is inert. */
     assetManifest?: AssetManifest | null;
+    /** Safe per-locale homepage content prepared by the server plugin. */
+    homeIntros?: import("../home-intro/types.js").PreparedHomeIntros;
 }