@takazudo/zudo-doc 0.2.0-next.6 → 0.2.0-next.8

package/dist/breadcrumb/breadcrumb.js

@@ -6,6 +6,7 @@ function buildBreadcrumbItems(tree, currentId, homeHref) {
   const path = findPath(tree, currentId);
   for (let i = 0; i < path.length; i++) {
     const node = path[i];
+    if (!node) continue;
     const isLast = i === path.length - 1;
     items.push({
       label: node.label,
@@ -20,7 +21,7 @@ function SmartLabel({ label }) {
   const nodes = [];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
-    if (part === "") continue;
+    if (!part) continue;
     nodes.push(part);
     if (i % 2 === 1) nodes.push(/* @__PURE__ */ jsx("wbr", {}, `wbr-${i}`));
   }

package/dist/html-preview-wrapper/dedent.js

@@ -3,7 +3,7 @@ function dedent(text) {
   let minIndent = Infinity;
   for (const line of lines) {
     if (line.trim().length === 0) continue;
-    const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+    const indent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
     if (indent < minIndent) minIndent = indent;
   }
   if (minIndent === 0 || minIndent === Infinity) {

package/dist/html-preview-wrapper/preview-base.js

@@ -53,7 +53,7 @@ function PreviewBase({
     const id = setTimeout(syncHeight, 150);
     return () => clearTimeout(id);
   }, [activeViewport, syncHeight, height]);
-  const containerWidth = VIEWPORTS[activeViewport].width;
+  const containerWidth = VIEWPORTS[activeViewport]?.width ?? "100%";
   return /* @__PURE__ */ jsxs("div", { class: "border border-muted rounded-lg overflow-hidden my-vsp-md", children: [
     /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-between px-hsp-md py-hsp-sm bg-surface border-b border-muted gap-hsp-sm flex-wrap", children: [
       title && /* @__PURE__ */ jsx("span", { class: "text-caption font-semibold text-fg", children: title }),

package/dist/integrations/claude-resources/escape-for-mdx.js

@@ -121,7 +121,7 @@ function escapeForMdx(content) {
     ).replace(/<(-+|=+)/g, "&lt;$1").replace(/<(\d)/g, "&lt;$1").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;");
     escaped = escaped.replace(
       new RegExp(`${inlinePlaceholder}(\\d+)\0`, "g"),
-      (_, idx) => inlineCodes[Number(idx)]
+      (_, idx) => inlineCodes[Number(idx)] ?? ""
     );
     return escaped;
   }).join("");

package/dist/integrations/claude-resources/generate.js

@@ -25,13 +25,16 @@ function listFiles(dir) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
 }
-function writeCategoryMeta(outputDir, label, position, description, noPage = true) {
-  const meta = { label, position, description };
-  if (noPage) meta.noPage = true;
-  fs.writeFileSync(
-    path.join(outputDir, "_category_.json"),
-    JSON.stringify(meta, null, 2) + "\n"
-  );
+function writeCategoryIndex(outputDir, label, position, description) {
+  const mdx = `---
+title: "${escapeTitle(label)}"
+description: "${escapeTitle(description)}"
+sidebar_position: ${position}
+category_no_page: true
+generated: true
+---
+`;
+  fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
 }
 function findClaudeMdFiles(dir, excludeDirs) {
   const results = [];
@@ -89,6 +92,11 @@ function generateClaudemdDocs(config) {
   });
   const emittedSlugs = /* @__PURE__ */ new Map();
   items.forEach((item, index) => {
+    if (item.slug === "index") {
+      throw new Error(
+        `claude-resources: "${item.relPath}" maps to the reserved slug "index", which is used for the category metadata file. Rename the directory to resolve the conflict.`
+      );
+    }
     const previous = emittedSlugs.get(item.slug);
     if (previous !== void 0) {
       throw new Error(
@@ -111,7 +119,7 @@ ${escapeForMdx(content.trim())}
 `;
     fs.writeFileSync(path.join(outputDir, `${item.slug}.mdx`), mdx);
   });
-  writeCategoryMeta(outputDir, "CLAUDE.md", 900, "Project-specific instructions");
+  writeCategoryIndex(outputDir, "CLAUDE.md", 900, "Project-specific instructions");
   return items;
 }
 function generateCommandsDocs(config) {
@@ -128,6 +136,11 @@ function generateCommandsDocs(config) {
     const parsed = parseFrontmatter(content);
     if (!parsed) continue;
     const name = file.replace(/\.md$/, "");
+    if (name === "index") {
+      throw new Error(
+        `claude-resources: ".claude/commands/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the command file to resolve the conflict.`
+      );
+    }
     const description = parsed.data.description || "";
     items.push({ name, description });
     const mdx = `---
@@ -142,7 +155,7 @@ ${escapeForMdx(parsed.content.trim())}
     fs.writeFileSync(path.join(outputDir, `${name}.mdx`), mdx);
   }
   items.sort((a, b) => a.name.localeCompare(b.name));
-  writeCategoryMeta(outputDir, "Commands", 901, "Custom slash commands");
+  writeCategoryIndex(outputDir, "Commands", 901, "Custom slash commands");
   return items;
 }
 function getSkillFileTree(skillDir, subDirs) {
@@ -153,6 +166,7 @@ function getSkillFileTree(skillDir, subDirs) {
   }
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
+    if (!entry) continue;
     const isLast = i === entries.length - 1;
     const prefix = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
     if (!entry.isDir) {
@@ -161,6 +175,7 @@ function getSkillFileTree(skillDir, subDirs) {
       lines.push(`${prefix}${entry.name}/`);
       for (let j = 0; j < entry.children.length; j++) {
         const child = entry.children[j];
+        if (!child) continue;
         const childIsLast = j === entry.children.length - 1;
         const continuation = isLast ? "    " : "\u2502   ";
         const childPrefix = childIsLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
@@ -173,7 +188,8 @@ function getSkillFileTree(skillDir, subDirs) {
 function getScriptDescription(filePath) {
   try {
     const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
-    const commentLine = topLines[0].startsWith("#!") ? topLines[1] || "" : topLines[0];
+    const firstLine = topLines[0] ?? "";
+    const commentLine = firstLine.startsWith("#!") ? topLines[1] ?? "" : firstLine;
     const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
     return match ? ` \u2014 ${match[1]}` : "";
   } catch {
@@ -187,7 +203,7 @@ function getSkillReferences(skillsDir, skillDir) {
     const content = fs.readFileSync(path.join(refsDir, f), "utf8");
     const name = f.replace(/\.md$/, "");
     const h1Match = content.match(/^#\s+(.+)$/m);
-    const title = h1Match ? h1Match[1] : name;
+    const title = h1Match?.[1] ?? name;
     return { name, title, content };
   }).sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -204,6 +220,11 @@ function generateSkillsDocs(config) {
   ensureDir(outputDir);
   const items = [];
   for (const dir of dirs) {
+    if (dir === "index") {
+      throw new Error(
+        `claude-resources: skill directory ".claude/skills/index/" uses the reserved name "index", which is used for the category metadata file. Rename the skill directory to resolve the conflict.`
+      );
+    }
     const content = fs.readFileSync(
       path.join(skillsDir, dir, "SKILL.md"),
       "utf8"
@@ -283,7 +304,7 @@ ${escapeForMdx(ref.content.trim())}
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       fs.writeFileSync(
         path.join(outputDir, `${dir}--script-${slug}.mdx`),
         `---
@@ -305,7 +326,7 @@ ${escapeForMdx(raw.trim())}
         "utf8"
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       fs.writeFileSync(
         path.join(outputDir, `${dir}--asset-${slug}.mdx`),
         `---
@@ -321,7 +342,7 @@ ${escapeForMdx(raw.trim())}
     }
   }
   items.sort((a, b) => a.name.localeCompare(b.name));
-  writeCategoryMeta(outputDir, "Skills", 902, "Skill packages");
+  writeCategoryIndex(outputDir, "Skills", 902, "Skill packages");
   return items;
 }
 function generateAgentsDocs(config) {
@@ -341,6 +362,11 @@ function generateAgentsDocs(config) {
     const description = parsed.data.description || "";
     const model = parsed.data.model || "";
     const fileSlug = file.replace(/\.md$/, "");
+    if (fileSlug === "index") {
+      throw new Error(
+        `claude-resources: ".claude/agents/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the agent file to resolve the conflict.`
+      );
+    }
     items.push({ name, file: fileSlug, description, model });
     const modelBadge = model ? `**Model:** \`${model}\`
 ` : "";
@@ -357,7 +383,7 @@ ${escapeForMdx(parsed.content.trim())}
     fs.writeFileSync(path.join(outputDir, `${fileSlug}.mdx`), mdx);
   }
   items.sort((a, b) => a.name.localeCompare(b.name));
-  writeCategoryMeta(outputDir, "Agents", 903, "Custom subagents");
+  writeCategoryIndex(outputDir, "Agents", 903, "Custom subagents");
   return items;
 }
 function generateOverviewIndex(config, {

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

@@ -87,21 +87,46 @@ interface PostBuildContext {
     /** Optional logger; falls back to silent no-ops when omitted. */
     logger?: PostBuildLogger;
 }
+/** Env var that opts a LOCAL build back into postBuild per-page JSON generation. */
+declare const DOC_HISTORY_GEN_ENV = "GEN_DOC_HISTORY";
+/**
+ * Decide whether the postBuild hook should generate per-page doc-history JSON.
+ *
+ * The per-page JSON is redundant on the normal paths: dev reads it live from
+ * the standalone `:4322` server, and CI generates it in the dedicated parallel
+ * `build-history` job (the CLI directly, NOT this hook). Running it inline
+ * during a plain local `pnpm build` issues ~3 serial `git log --follow` calls
+ * per content file, which on a large corpus exceeds zfb's 120s postBuild
+ * lifecycle-hook budget (#1986). So the default flips to opt-in:
+ *
+ *   - `SKIP_DOC_HISTORY=1` → never generate (highest priority; back-compat).
+ *   - `GEN_DOC_HISTORY=1`  → always generate (explicit local opt-in).
+ *   - CI                   → generate (keeps the CI build-site artifact
+ *                            byte-identical to before; D1's async generator
+ *                            keeps it within budget).
+ *   - otherwise (local)    → skip (the #1986 fix).
+ *
+ * This gates ONLY the postBuild per-page dropdown JSON. The preBuild meta step
+ * (the visible Created/Updated/Author block) is unaffected — it keys off
+ * `SKIP_DOC_HISTORY` alone — so a plain local build still shows real page
+ * metadata; only the per-page history dropdown JSON is absent until opt-in.
+ */
+declare function shouldGeneratePostBuild(env?: NodeJS.ProcessEnv): {
+    generate: boolean;
+    reason: string;
+};
 /**
  * Post-build hook. Spawns the `doc-history-generate` CLI from
  * `@takazudo/zudo-doc-history-server` to write per-page git history JSON
  * files into `<outDir>/doc-history/`.
  *
- * Returns early when `SKIP_DOC_HISTORY=1` is set in the environment;
- * the CI `build-history` job uses that flag because it generates the
- * same output as a separate parallel artifact. Local `pnpm build`
- * runs leave the flag unset so the inline path is taken.
+ * Generation is gated by `shouldGeneratePostBuild` (see its docs): 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`.
  *
- * The CLI is spawned through the platform shell so that the
- * `node_modules/.bin/doc-history-generate` symlink (created by pnpm /
- * npm at install time) resolves naturally. Output is inherited so
- * progress and warnings surface in the user's terminal exactly as
- * they do in CI.
+ * The CLI is spawned as `node <cli> <args>` (shell: false) so option-derived
+ * paths are never interpolated into a command line. Output is inherited so
+ * progress and warnings surface in the user's terminal exactly as in CI.
  */
 declare function runDocHistoryPostBuild(options: DocHistoryOptions, ctx: PostBuildContext): Promise<void>;
 /**
@@ -134,4 +159,4 @@ declare function buildGenerateCliArgs(options: DocHistoryOptions, outDir: string
  */
 declare function resolveDocHistoryGenerateBin(): string;
 
-export { type ConnectMiddleware, DEFAULT_MAX_ENTRIES, DEFAULT_SERVER_PORT, DOC_HISTORY_GENERATE_BIN, DOC_HISTORY_OUTPUT_DIRNAME, DOC_HISTORY_ROUTE_PREFIX, type DocHistoryLocaleConfig, type DocHistoryOptions, type DocHistoryPluginDescriptor, type MiddlewareLogger, type PostBuildContext, type PostBuildLogger, buildGenerateCliArgs, createDocHistoryDevMiddleware, docHistoryPlugin, resolveDocHistoryGenerateBin, runDocHistoryPostBuild };
+export { type ConnectMiddleware, DEFAULT_MAX_ENTRIES, DEFAULT_SERVER_PORT, DOC_HISTORY_GENERATE_BIN, DOC_HISTORY_GEN_ENV, DOC_HISTORY_OUTPUT_DIRNAME, DOC_HISTORY_ROUTE_PREFIX, type DocHistoryLocaleConfig, type DocHistoryOptions, type DocHistoryPluginDescriptor, type MiddlewareLogger, type PostBuildContext, type PostBuildLogger, buildGenerateCliArgs, createDocHistoryDevMiddleware, docHistoryPlugin, resolveDocHistoryGenerateBin, runDocHistoryPostBuild, shouldGeneratePostBuild };

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

@@ -46,11 +46,32 @@ function createDocHistoryDevMiddleware(options, logger) {
     });
   };
 }
+const DOC_HISTORY_GEN_ENV = "GEN_DOC_HISTORY";
+function shouldGeneratePostBuild(env = process.env) {
+  if (env.SKIP_DOC_HISTORY === "1") {
+    return { generate: false, reason: "SKIP_DOC_HISTORY=1" };
+  }
+  if (env[DOC_HISTORY_GEN_ENV] === "1") {
+    return { generate: true, reason: `${DOC_HISTORY_GEN_ENV}=1` };
+  }
+  if (isCiEnv(env)) {
+    return { generate: true, reason: "CI" };
+  }
+  return {
+    generate: false,
+    reason: `local default \u2014 set ${DOC_HISTORY_GEN_ENV}=1 to generate`
+  };
+}
+function isCiEnv(env) {
+  return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true";
+}
 async function runDocHistoryPostBuild(options, ctx) {
-  if (process.env.SKIP_DOC_HISTORY === "1") {
-    ctx.logger?.info("Skipping doc history generation (SKIP_DOC_HISTORY=1)");
+  const { generate, reason } = shouldGeneratePostBuild();
+  if (!generate) {
+    ctx.logger?.info(`Skipping doc history generation (${reason})`);
     return;
   }
+  ctx.logger?.info(`Generating doc history JSON (${reason})`);
   const args = buildGenerateCliArgs(options, ctx.outDir);
   await spawnDocHistoryGenerate(args, ctx.logger);
 }
@@ -127,6 +148,7 @@ export {
   DEFAULT_MAX_ENTRIES,
   DEFAULT_SERVER_PORT,
   DOC_HISTORY_GENERATE_BIN,
+  DOC_HISTORY_GEN_ENV,
   DOC_HISTORY_OUTPUT_DIRNAME,
   DOC_HISTORY_ROUTE_PREFIX,
   buildGenerateCliArgs,
@@ -134,5 +156,6 @@ export {
   docHistoryPlugin,
   resolveDocHistoryGenerateBin,
   runDocHistoryMetaStep,
-  runDocHistoryPostBuild
+  runDocHistoryPostBuild,
+  shouldGeneratePostBuild
 };

package/dist/integrations/doc-history/pre-build.d.ts

@@ -42,6 +42,12 @@ interface DocHistoryMetaEntry {
 }
 /** Manifest shape — keyed by composedSlug. */
 type DocHistoryMetaManifest = Record<string, DocHistoryMetaEntry>;
+/**
+ * Tiny in-file semaphore for bounded parallelism — avoids a p-limit dependency.
+ * Limits concurrent async tasks to `concurrency` at a time.
+ * Ported from packages/doc-history-server/src/cli.ts.
+ */
+declare function makeSemaphore(concurrency: number): () => Promise<() => void>;
 /**
  * Emit `<projectRoot>/.zfb/doc-history-meta.json` from git history.
  *
@@ -55,4 +61,4 @@ type DocHistoryMetaManifest = Record<string, DocHistoryMetaEntry>;
  */
 declare function runDocHistoryMetaStep(options: RunDocHistoryMetaOptions): Promise<void>;
 
-export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, runDocHistoryMetaStep };
+export { type DocHistoryMetaEntry, type DocHistoryMetaLocaleConfig, type DocHistoryMetaManifest, type DocHistoryMetaVersionConfig, type RunDocHistoryMetaOptions, makeSemaphore, runDocHistoryMetaStep };

package/dist/integrations/doc-history/pre-build.js

@@ -1,11 +1,37 @@
 import fs from "node:fs";
 import path from "node:path";
+import { cpus } from "node:os";
 import {
   collectContentFiles,
-  getFileCommitsMeta
+  getFileCommitsMetaAsync
 } from "@takazudo/zudo-doc-history-server/git-history";
 const META_OUT_RELATIVE_DIR = ".zfb";
 const META_OUT_FILENAME = "doc-history-meta.json";
+function makeSemaphore(concurrency) {
+  let running = 0;
+  const queue = [];
+  function next() {
+    if (queue.length > 0 && running < concurrency) {
+      queue.shift()();
+    }
+  }
+  return function acquire() {
+    return new Promise((resolve) => {
+      function tryRun() {
+        if (running < concurrency) {
+          running++;
+          resolve(() => {
+            running--;
+            next();
+          });
+        } else {
+          queue.push(tryRun);
+        }
+      }
+      tryRun();
+    });
+  };
+}
 async function runDocHistoryMetaStep(options) {
   const projectRoot = path.resolve(options.projectRoot);
   const zfbDir = path.join(projectRoot, META_OUT_RELATIVE_DIR);
@@ -27,24 +53,46 @@ async function runDocHistoryMetaStep(options) {
       dirEntries.push([code, path.resolve(projectRoot, locale.dir)]);
     }
   }
-  const meta = {};
+  const concurrency = Math.min(8, Math.max(2, cpus().length));
+  const acquire = makeSemaphore(concurrency);
+  const jobs = [];
   for (const [localeKey, contentDir] of dirEntries) {
     const files = collectContentFiles(contentDir);
     for (const { filePath, slug } of files) {
-      const allCommits = getFileCommitsMeta(filePath);
-      if (allCommits.length === 0) continue;
-      const newestInfo = allCommits[0];
-      const oldestInfo = allCommits[allCommits.length - 1] ?? newestInfo;
       const composedSlug = localeKey ? `${localeKey}/${slug}` : slug;
-      meta[composedSlug] = {
-        // Author comes from the FIRST (oldest) commit.
-        author: oldestInfo.author,
-        // createdDate = oldest commit; updatedDate = newest commit.
-        createdDate: oldestInfo.date,
-        updatedDate: newestInfo.date
-      };
+      jobs.push({ composedSlug, filePath });
     }
   }
+  const results = new Array(jobs.length).fill(null);
+  await Promise.all(
+    jobs.map(async ({ filePath }, i) => {
+      const release = await acquire();
+      try {
+        const allCommits = await getFileCommitsMetaAsync(filePath);
+        if (allCommits.length === 0) return;
+        const newestInfo = allCommits[0];
+        const oldestInfo = allCommits[allCommits.length - 1] ?? newestInfo;
+        results[i] = {
+          newest: { author: newestInfo.author, date: newestInfo.date },
+          oldest: { author: oldestInfo.author, date: oldestInfo.date }
+        };
+      } finally {
+        release();
+      }
+    })
+  );
+  const meta = {};
+  for (let i = 0; i < jobs.length; i++) {
+    const result = results[i];
+    if (result == null) continue;
+    meta[jobs[i].composedSlug] = {
+      // Author comes from the FIRST (oldest) commit.
+      author: result.oldest.author,
+      // createdDate = oldest commit; updatedDate = newest commit.
+      createdDate: result.oldest.date,
+      updatedDate: result.newest.date
+    };
+  }
   fs.mkdirSync(zfbDir, { recursive: true });
   fs.writeFileSync(outPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
   logger.info(
@@ -60,5 +108,6 @@ const defaultLogger = {
   }
 };
 export {
+  makeSemaphore,
   runDocHistoryMetaStep
 };

package/dist/integrations/llms-txt/dev-middleware.js

@@ -53,7 +53,7 @@ function createLlmsTxtDevMiddleware(options, logger) {
   };
 }
 function matchLlmsRoute(url, localeCodes) {
-  const pathname = url.split("?")[0];
+  const pathname = url.split("?")[0] ?? url;
   const m = pathname.match(LLMS_KIND_PATTERN);
   if (!m) return null;
   const prefix = m[1];

package/dist/integrations/llms-txt/load.d.ts

@@ -28,7 +28,9 @@ declare function collectMdFiles(dir: string): Array<{
  * URL is produced.
  */
 declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
-/** Whether a given doc should be excluded from the llms.txt index. */
+/** Whether a given doc should be excluded from the llms.txt index.
+ *  `category_no_page` index files are metadata-only with no built route, so
+ *  they are excluded alongside search_exclude / draft / unlisted. */
 declare function isExcluded(data: LlmsTxtFrontmatter): boolean;
 /**
  * Parse a markdown file into frontmatter + body. Returns `null` when

package/dist/integrations/llms-txt/load.js

@@ -34,7 +34,9 @@ function slugToUrl(slug, locale, base, siteUrl) {
   return path;
 }
 function isExcluded(data) {
-  return Boolean(data.search_exclude || data.draft || data.unlisted);
+  return Boolean(
+    data.search_exclude || data.draft || data.unlisted || data.category_no_page
+  );
 }
 function parseMarkdownFile(filePath) {
   try {

package/dist/integrations/llms-txt/types.d.ts

@@ -22,6 +22,12 @@ interface LlmsTxtFrontmatter {
      * Mirrors the `search_exclude` flag used by the existing project.
      */
     search_exclude?: boolean;
+    /**
+     * A `category_no_page` index.mdx carries category metadata only and builds
+     * no route — so it must NOT appear in llms.txt (the link would 404). Mirrors
+     * the route/sitemap/search exclusion in the host project.
+     */
+    category_no_page?: boolean;
     [key: string]: unknown;
 }
 /**

package/dist/integrations/search-index/content-files.d.ts

@@ -19,6 +19,12 @@ interface DocFrontmatter {
     draft?: boolean;
     unlisted?: boolean;
     search_exclude?: boolean;
+    /**
+     * A `category_no_page` index.mdx carries category metadata only and builds
+     * no route — so its slug must NOT enter the search index (the result link
+     * would 404). Mirrors the route/sitemap exclusion in the host project.
+     */
+    category_no_page?: boolean;
     [key: string]: unknown;
 }
 /** Parse a markdown file. Returns null when the file cannot be read. */
@@ -26,7 +32,11 @@ declare function parseMarkdownFile(filePath: string): {
     data: DocFrontmatter;
     content: string;
 } | null;
-/** A page is excluded from indexing when explicitly opted out, drafted, or unlisted. */
+/**
+ * A page is excluded from indexing when explicitly opted out, drafted,
+ * unlisted, or a `category_no_page` metadata-only category index (no built
+ * route to link to).
+ */
 declare function isExcluded(data: DocFrontmatter): boolean;
 
 export { type DocFrontmatter, collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, stripMarkdown };

package/dist/integrations/search-index/content-files.js

@@ -40,7 +40,7 @@ function parseMarkdownFile(filePath) {
   }
 }
 function isExcluded(data) {
-  return !!(data.search_exclude || data.draft || data.unlisted);
+  return !!(data.search_exclude || data.draft || data.unlisted || data.category_no_page);
 }
 export {
   collectMdFiles,

package/dist/safelist.css

@@ -0,0 +1,2 @@
+/* generated by gen-safelist.mjs — do not edit by hand */
+@source inline("-mb-px [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [doc-history-meta] [doc-layout] a a2 abbr above absolute active actual after after-breadcrumb after-content after-sidebar after-title against agent agents ai-chat ai-chat-trigger align-top all allow-same-origin allow-scripts already-executed an anchor anchored and announce antialiased any application/json applies apply-css-vars are area arg aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow article as asc aside assets assigning assistant async at attach attribute attributes available await away b back backdrop:bg-bg/80 background backtick backticks baked banner bare based be because before below between bg bg-[#fff] bg-accent bg-bg bg-code-bg bg-fg bg-info/10 bg-muted bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blob block blockquote blocks blur body body-end-components body-end-scripts boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-collapse border-fg border-l border-l-[3px] border-muted border-none border-r border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 both br breadcrumb:end breadcrumb:start break-words browser browsers btn bundler but button buttons by caller can cancellation cannot canonical caption cases cat-nav- catch category catppuccin-latte checkbox child ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars click client clip close code code-block-sr-announce col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colors command commands commit component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher concrete configuration configure configured consumer container containers content content-type content-wrapper:end content-wrapper:start contents controller converts copy correct covered covers crashes crumb- css cursor cursor-not-allowed cursor-pointer custom dark data-active data-group-id data-header data-header-logo data-header-nav data-header-right data-mermaid-rendered data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-sidebar-resizer data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zfb-transition-persist dd decimal declare decoration-muted default defaults del desc description design design-token-panel design-token-trigger desktop desktop-sidebar detached details deterministic dfn diagram diagrams dialog dieser directories directory disc display:none dist div dl doc doc-card- doc-history doc-history-generate does drag draggable dropdown dropdowns dt duration-150 duration-200 during dynamically e2e earlier edge el element elements els else em emit emitting empty en entries entry error escape even eventually every exactly exit expected failed fall fallback falls false fast feed fg fieldset figcaption figure file fill fills finally fire fires first fixed fixtures flex flex-1 flex-col flex-wrap flip flipping flips focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:underline font font-bold font-medium font-mono font-semibold footer for form free from frontmatter frontmatter-preview full function further g gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-sm gap-hsp-xs gap-vsp-lg gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps generate generation geometry get github github-link go got gray-matter grid grid-cols-1 group group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.875rem] h-[1.575rem] h-[1lh] h-[3.5rem] h-[calc(100vh-3.5rem)] h-icon-sm h-icon-xs h1 h2 h3 h4 h5 h6 hand handle handled handlers has hash-link have head head-links head-scripts header header-call:end header-call:start height here hex hidden highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr html i i2 i3 i4 identical if iframe img import imports in index inherit initial initialised inline inline-block inline-flex input ins inset-0 inside instanceof instructions intent into inverse invoke is it italic item- items items-center items-start itself javascript justify-between justify-center justify-end kbd keep keeps kept keydown khroma label landing language-switcher last:border-b-0 launch leading-relaxed leading-snug leading-tight leaf- leaving left left-0 left:calc legend lg lg:block lg:flex lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl li li2 light like line link link- list-disc list-none listener literal lives llms llms-txt load local lostpointercapture luminance m m-0 main make maps mark marks matching max-h-[80vh] max-w-[46rem] max-w-[80rem] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs menu merged mermaid message meta metadata min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode mounted mouseenter mouseleave mt-0 mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-sm mt-vsp-xl must mutates mx-auto my-vsp-lg my-vsp-md name named native nav nav-card- navigating navigation navigations near needs new next no-underline node:fs node:module node:os node:path nodes nofollow noindex non-empty non-string none noopener noreferrer normal not not-object note now null number object observe observer of og:description og:image og:title og:type og:url ol older on once one only opacity-60 option or other others out overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl packages padding page page-loading-overlay page-loading-spinner page-navigate-end pages paint panel panels parent parse parsed pass path pb-vsp-xl per pi pick picked picks pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place pointer-events-none pointercancel pointerdown pointermove pointerup polite polyline populates port position position:fixed pr-hsp-lg pr-hsp-md pr-hsp-xl pre preact preact/hooks preact/jsx-runtime preload pres produced produces production propagating properties property proxy pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q r raw re-render re-run reach reaches reading ready real references regenerates reinit relative remains render rendered renders reorder replaced repopulate requires reserved resize resize-x resolve resolved resolves return returns right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-full rounded-lg running runs runtime s safer samp schema-mismatch schema-missing script script-evaluation scripts scroll scrollbar scrolled scrollend search section section- see sel-bg sel-fg select select-none self-start separator server server-rendered set shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shared shiki ships should show shown shrink-0 sidebar signal single sitemap- size skill skills slash slug sm:flex-row sm:grid-cols-2 sm:items-center sm:justify-between small so solid some source space-y-vsp-2xs spacing span spans spec specifiers sr-only stale state stay sticky still stored stray string strip stroke-linecap stroke-linejoin stroke-width strong style styles stylesheet sub subagents subsequent success summary sup support survives svg synchronous synchronously syntactically syntect tab tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag- tag-item- tbody td temp temp-element template temporary temporary-element test-results text text-accent text-bg text-body text-caption text-center text-code-fg text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-small text-title text-warning textarea tfoot th that the thead them theme theme-color theme-toggle then these they this through time title to toggle toggle-ai-chat toggle-design-token-panel token tokens tolerates too top-0 top-[3.5rem] top-full total tr tracking-wider trade-off transition-[background,color,border-color] transition-colors transition-transform tree-child- tree-item- tree-top- trick trigger trigger:ai-chat trigger:design-token-panel triggers true try twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two u ul unavailable undefined under underline understand unknown unmaintained unobserve unreadable unreleased unreliable unset unsupported up uppercase use used uses utf-8 utf8 utilities v val value values var variable version- version-menu version-switcher vertical via video viewport visible vitesse-dark w w-[0.5rem] w-[0.875rem] w-[1.575rem] w-[16px] w-[280px] w-[var(--zd-sidebar-w)] w-full w-icon-sm w-icon-xs was watching wbr wbr- we when where whereas which while whitespace-nowrap whitespace-pre whole will with without word worktrees would wrap wrapper wrappers written wrote xl:flex xl:hidden y-scrollbar yet z-10 z-30 z-50 zd-content zd-html-preview-code zfb zfb:after-swap zfb:before-preparation zudo-doc-design-tokens/v1 zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge zudo-doc-tweak-state zudo-doc-tweak-state-v2");

package/dist/sidebar-tree/build-tree.js

@@ -59,7 +59,8 @@ function toSidebarNodes(parent, locale, buildHref, categoryMeta, parentSortOrder
   for (const child of parent.children.values()) {
     const doc = child.doc;
     const meta = categoryMeta?.get(child.fullPath);
-    const sortOrder = meta?.sortOrder ?? "asc";
+    const noPage = doc?.data.category_no_page ?? meta?.noPage;
+    const sortOrder = doc?.data.category_sort_order ?? meta?.sortOrder ?? "asc";
     const children = toSidebarNodes(
       child,
       locale,
@@ -67,13 +68,14 @@ function toSidebarNodes(parent, locale, buildHref, categoryMeta, parentSortOrder
       categoryMeta,
       sortOrder
     );
-    const hasPage = !!doc;
+    const hasPage = !!doc && noPage !== true;
     const isCategory = !hasPage && children.length > 0;
     const label = doc?.data.sidebar_label ?? doc?.data.title ?? meta?.label ?? toTitleCase(child.segment);
     const description = doc?.data.description ?? meta?.description;
     const positionRaw = doc?.data.sidebar_position ?? meta?.position;
     const position = positionRaw ?? 999;
-    const href = meta?.noPage ? void 0 : doc || children.length > 0 ? buildHref(child.fullPath, locale) : void 0;
+    const href = noPage ? void 0 : doc || children.length > 0 ? buildHref(child.fullPath, locale) : void 0;
+    const hasSortOrder = doc?.data.category_sort_order !== void 0 || meta?.sortOrder !== void 0;
     nodes.push({
       type: isCategory ? "category" : "doc",
       id: child.fullPath,
@@ -82,7 +84,7 @@ function toSidebarNodes(parent, locale, buildHref, categoryMeta, parentSortOrder
       ...positionRaw !== void 0 ? { sidebar_position: positionRaw } : {},
       ...href !== void 0 ? { href } : {},
       hasPage,
-      ...meta?.sortOrder ? { sortOrder } : {},
+      ...hasSortOrder ? { sortOrder } : {},
       children
     });
     Object.defineProperty(nodes[nodes.length - 1], "__sortPosition", {

package/dist/sidebar-tree/types.d.ts

@@ -27,6 +27,20 @@ interface SidebarFrontmatter {
      * the slug from the entry's id (stripping a trailing `/index`).
      */
     slug?: string;
+    /**
+     * Category metadata carried on a directory's `index.mdx` frontmatter — the
+     * frontmatter equivalent of `_category_.json`'s `noPage`. When `true`, this
+     * index file exists only to label/position the category: it renders as a
+     * non-linked sidebar header and is excluded from routes, the sitemap, and
+     * the search index. Frontmatter wins over the sidecar when both are present.
+     */
+    category_no_page?: boolean;
+    /**
+     * Frontmatter equivalent of `_category_.json`'s `sortOrder`. Controls the
+     * sort direction of this category's children. Frontmatter wins over the
+     * sidecar when both are present.
+     */
+    category_sort_order?: "asc" | "desc";
 }
 /**
  * Minimum shape required of a content collection entry. Designed to be a

package/dist/toc/smart-break.js

@@ -20,7 +20,7 @@ function smartBreak(text) {
   const nodes = [];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
-    if (part === "") continue;
+    if (!part) continue;
     nodes.push(part);
     if (i % 2 === 1) nodes.push(/* @__PURE__ */ jsx("wbr", {}, `wbr-${i}`));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "0.2.0-next.6",
+  "version": "0.2.0-next.8",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -150,7 +150,9 @@
     "./icons": {
       "types": "./dist/icons/index.d.ts",
       "default": "./dist/icons/index.js"
-    }
+    },
+    "./safelist.css": "./dist/safelist.css",
+    "./safelist": "./dist/safelist.css"
   },
   "files": [
     "dist",
@@ -158,10 +160,10 @@
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.31",
-    "@takazudo/zfb-runtime": "^0.1.0-next.31",
+    "@takazudo/zfb": "^0.1.0-next.35",
+    "@takazudo/zfb-runtime": "^0.1.0-next.35",
     "@takazudo/zdtp": "^0.2.0-next.2",
-    "@takazudo/zudo-doc-history-server": "^0.2.0-next.6"
+    "@takazudo/zudo-doc-history-server": "^0.2.0-next.8"
   },
   "peerDependenciesMeta": {
     "@takazudo/zudo-doc-history-server": {
@@ -182,8 +184,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0",
-    "@takazudo/zfb": "0.1.0-next.31",
-    "@takazudo/zfb-runtime": "0.1.0-next.31"
+    "@takazudo/zfb": "0.1.0-next.35",
+    "@takazudo/zfb-runtime": "0.1.0-next.35"
   },
   "scripts": {
     "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 tsup",