@docubook/flame 1.2.0 → 1.3.0

package/.docu/components/Context.tsx

@@ -16,7 +16,8 @@ function getContextRoutes() {
 }
 
 function getFirstItemHref(route: { href: string; items?: { href: string }[] }): string {
-  return route.items?.[0]?.href ? `${route.href}${route.items[0].href}` : route.href;
+  if (!route.items?.length) return route.href;
+  return `${route.href}${getFirstItemHref(route.items[0])}`;
 }
 
 function getActiveContextRoute(path: string) {

package/.docu/node/build.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir, readdir, copyFile, stat } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, copyFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
@@ -14,12 +14,17 @@ import {
   PROJECT_ROOT,
   loadDocuConfig,
 } from "./paths";
-import { htmlShell as createHtmlShell } from "./html";
+import { htmlShell } from "./html";
 import { generateSearchIndex } from "./search-indexer";
 import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
+import { loadPlugins } from "./plugin-loader";
+import { BuildPluginBuilder } from "./plugin-builder";
+import { scanMdxFiles } from "./utils";
 import type { BuildCache, CliArgs } from "./types";
+import { generateNonce } from "./security";
+import type { PageMeta, PageContext } from "./plugin";
 import DocsPage from "../pages/docs/[[...slug]]";
 import IndexPage from "../pages/index";
 import NotFoundPage from "../pages/404";
@@ -55,77 +60,60 @@ async function writeCache(cache: BuildCache): Promise<void> {
   await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2));
 }
 
-async function findMdxFiles(dir: string, baseDir = ""): Promise<{ path: string; mtime: number }[]> {
-  const files: { path: string; mtime: number }[] = [];
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name);
-      const relativePath = baseDir ? `${baseDir}/${entry.name}` : entry.name;
-
-      if (entry.isDirectory()) {
-        if (entry.name === "assets" || entry.name.startsWith(".")) continue;
-        files.push(...(await findMdxFiles(fullPath, relativePath)));
-      } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
-        if (entry.name === "index.mdx" && !baseDir) continue;
-        const stats = await stat(fullPath);
-        let path = relativePath.replace(/\.(mdx|md)$/, "");
-
-        if (/\/index$/.test(path)) {
-          path = path.replace(/\/index$/, "");
-        }
-        files.push({ path, mtime: stats.mtimeMs });
-      }
-    }
-  } catch (err) {
-    console.error("Failed to scan docs directory:", (err as Error).message);
-  }
-  return files;
-}
-
 export function parseConcurrency(): number {
-  return Math.max(1, parseInt(process.env.BUILD_CONCURRENCY || "10", 10) || 10);
+  return Math.max(1, parseInt(process.env.BUILD_CONCURRENCY || "4", 10) || 4);
 }
 
-export function shouldRebuild(path: string, mtime: number, cache: BuildCache): boolean {
+type RebuildDecision = "yes" | "hash_check" | "no";
+
+export function shouldRebuild(path: string, mtime: number, cache: BuildCache): RebuildDecision {
   const cached = cache[path];
-  if (!cached) return true;
-  return mtime > cached.builtAt;
+  if (!cached) return "yes";
+  if (mtime > cached.builtAt) return "hash_check";
+  return "no";
 }
 
 let assetManifest = { js: "client.js", css: "client.css" };
 
 let inlineThemeCss: string | undefined;
 
-function htmlShell(title: string, description: string, body: string): string {
-  const favicon = docuConfig.meta?.favicon || "/favicon.ico";
-  return createHtmlShell({
-    title,
-    description,
-    body,
-    favicon,
-    css: assetManifest.css,
-    js: assetManifest.js,
-    themeCss: inlineThemeCss,
-  });
-}
-
 async function renderDocsPage(
   slug: string,
   rawMdx: string,
   filePath: string,
-  gitDates?: Map<string, string>
+  gitDates?: Map<string, string>,
+  builder?: BuildPluginBuilder,
+  nonce?: string
 ): Promise<string> {
+  let content = rawMdx;
+  if (builder) {
+    const transformed = await builder.runOnLoad(filePath, content);
+    if (transformed?.contents) {
+      content = transformed.contents;
+    }
+  }
+
   let result;
   try {
-    result = await compileMdx(rawMdx, filePath, gitDates);
+    const remarkPlugins = builder?.collectRemarkPlugins();
+    const rehypePlugins = builder?.collectRehypePlugins();
+    result = await compileMdx(content, filePath, gitDates, remarkPlugins, rehypePlugins);
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Unknown MDX error";
     throw new Error(`MDX Error in: docs/${slug}.mdx\n${msg}`, { cause: err });
   }
 
-  const title = result.frontmatter.title || slug || "Docs";
-  const description = result.frontmatter.description || "";
+  let frontmatter = result.frontmatter as Record<string, unknown>;
+  if (builder) {
+    frontmatter = await builder.runTransformFrontmatterChain(frontmatter, {
+      slug,
+      filePath,
+      content,
+    });
+  }
+
+  const title = (frontmatter.title as string) || slug || "Docs";
+  const description = (frontmatter.description as string) || "";
   const slugParts = slug ? slug.split("/") : [];
 
   const page = React.createElement(
@@ -135,7 +123,7 @@ async function renderDocsPage(
       slug: slugParts,
       title,
       description,
-      date: result.frontmatter.date || undefined,
+      date: (frontmatter.date as string) || undefined,
       content: result.content,
       tocs: result.tocs,
       filePath,
@@ -145,7 +133,30 @@ async function renderDocsPage(
   );
 
   const body = renderToString(page);
-  return htmlShell(title, description, body);
+
+  const ctx: PageContext = { slug, filePath, frontmatter, content, config: docuConfig };
+  const headExtra = builder?.collectHead(ctx);
+  const bodyExtra = builder?.collectBody(ctx);
+
+  const favicon = docuConfig.meta?.favicon || "/favicon.ico";
+  let html = htmlShell({
+    title,
+    description,
+    body,
+    favicon,
+    css: assetManifest.css,
+    js: assetManifest.js,
+    nonce,
+    themeCss: inlineThemeCss,
+    headExtra,
+    bodyExtra,
+  });
+
+  if (builder) {
+    html = await builder.runTransformHtmlChain(html, ctx);
+  }
+
+  return html;
 }
 
 async function copyDirectoryRecursive(src: string, dest: string): Promise<void> {
@@ -182,7 +193,7 @@ async function build() {
 
   await copyDirectoryRecursive(DOCS_ASSETS_DIR, join(DIST_DIR, "docs", "assets"));
 
-  const mdxFiles = await findMdxFiles(DOCS_DIR);
+  const mdxFiles = await scanMdxFiles(DOCS_DIR);
   const cache = args.force ? {} : await readCache();
   let built = 0;
   let skipped = 0;
@@ -205,20 +216,25 @@ async function build() {
     };
   }
 
+  const hasPlugins = !!docuConfig.plugins?.length;
+  const builder = hasPlugins ? new BuildPluginBuilder(docuConfig) : null;
+  if (hasPlugins && builder) {
+    const plugins = await loadPlugins(docuConfig.plugins!);
+    for (const plugin of plugins) {
+      await plugin.setup(builder);
+    }
+    await builder.runOnStart();
+  }
+
   logger.spinner.start("Building pages...");
   t = performance.now();
 
-  const allRelPaths = mdxFiles
-    .map((f) => {
-      const mdxPath1 = join(DOCS_DIR, f.path, "index.mdx");
-      const mdxPath2 = join(DOCS_DIR, `${f.path}.mdx`);
-      const mdxPath3 = join(DOCS_DIR, `${f.path}.md`);
-      for (const p of [mdxPath1, mdxPath2, mdxPath3]) {
-        if (existsSync(p)) return p.replace(PROJECT_ROOT + "/", "");
-      }
-      return null;
-    })
-    .filter((p): p is string => p !== null);
+  const allRelPaths = mdxFiles.map((f) => f.absPath.replace(PROJECT_ROOT + "/", ""));
+
+  const indexMdxFull = join(DOCS_DIR, "index.mdx");
+  if (existsSync(indexMdxFull)) {
+    allRelPaths.push(indexMdxFull.replace(PROJECT_ROOT + "/", ""));
+  }
   const gitDates = await getGitLastModifiedBatch(allRelPaths);
 
   const CONCURRENCY = parseConcurrency();
@@ -226,40 +242,54 @@ async function build() {
   const errors: string[] = [];
 
   for (const file of mdxFiles) {
-    const mdxPath1 = join(DOCS_DIR, file.path, "index.mdx");
-    const mdxPath2 = join(DOCS_DIR, `${file.path}.mdx`);
-    const mdxPath3 = join(DOCS_DIR, `${file.path}.md`);
+    const rebuildDecision = shouldRebuild(file.path, file.mtime, cache);
 
-    let rawMdx: string | null = null;
-    let absPath = "";
-    for (const p of [mdxPath1, mdxPath2, mdxPath3]) {
-      try {
-        rawMdx = await readFile(p, "utf-8");
-        absPath = p;
-        break;
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    if (rebuildDecision === "no") {
+      const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+      if (existsSync(outputPath) && !assetsChanged) {
+        skipped++;
+        continue;
       }
     }
-    if (!rawMdx) continue;
 
-    let needRebuild = assetsChanged || shouldRebuild(file.path, file.mtime, cache);
-    if (!needRebuild) {
-      const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
-      if (!existsSync(outputPath)) needRebuild = true;
-    }
-    if (!needRebuild) {
-      skipped++;
+    let rawMdx: string;
+    try {
+      rawMdx = await readFile(file.absPath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
       continue;
     }
 
-    const relPath = absPath.replace(PROJECT_ROOT + "/", "");
+    if (rebuildDecision === "hash_check") {
+      const contentHash = hashContent(rawMdx);
+      const cached = cache[file.path];
+      if (cached && cached.hash === contentHash) {
+        if (!assetsChanged) {
+          const outputPath = join(DIST_DIR, "docs", `${file.path}.html`);
+          if (existsSync(outputPath)) {
+            cache[file.path] = { ...cached, mtime: file.mtime, builtAt: Date.now() };
+            skipped++;
+            continue;
+          }
+        }
+      }
+    }
+
+    const relPath = file.absPath.replace(PROJECT_ROOT + "/", "");
     const capturedRawMdx = rawMdx;
     const capturedFile = file;
 
     buildTasks.push(async () => {
       try {
-        const html = await renderDocsPage(capturedFile.path, capturedRawMdx, relPath, gitDates);
+        const pageNonce = generateNonce();
+        const html = await renderDocsPage(
+          capturedFile.path,
+          capturedRawMdx,
+          relPath,
+          gitDates,
+          builder,
+          pageNonce
+        );
         const outputPath = join(DIST_DIR, "docs", `${capturedFile.path}.html`);
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, html);
@@ -285,7 +315,14 @@ async function build() {
     const indexMdxPath = join(DOCS_DIR, "index.mdx");
     const indexRaw = await readFile(indexMdxPath, "utf-8");
     const indexRelPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
-    const indexHtml = await renderDocsPage("", indexRaw, indexRelPath, gitDates);
+    const indexHtml = await renderDocsPage(
+      "",
+      indexRaw,
+      indexRelPath,
+      gitDates,
+      builder,
+      generateNonce()
+    );
     await mkdir(join(DIST_DIR, "docs"), { recursive: true });
     await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
   } catch (err) {
@@ -295,11 +332,17 @@ async function build() {
   }
 
   const landingPage = React.createElement(IndexPage);
-  const landingHtml = htmlShell(
-    docuConfig.meta?.title || "DocuBook",
-    docuConfig.meta?.description || "",
-    renderToString(landingPage)
-  );
+  const landingFavicon = docuConfig.meta?.favicon || "/favicon.ico";
+  const landingHtml = htmlShell({
+    title: docuConfig.meta?.title || "DocuBook",
+    description: docuConfig.meta?.description || "",
+    body: renderToString(landingPage),
+    favicon: landingFavicon,
+    css: assetManifest.css,
+    js: assetManifest.js,
+    nonce: generateNonce(),
+    themeCss: inlineThemeCss,
+  });
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
 
   const notFoundPage = React.createElement(
@@ -307,13 +350,33 @@ async function build() {
     { repoUrl: docuConfig.repo?.url },
     React.createElement(NotFoundPage)
   );
-  const notFoundHtml = htmlShell("404 - Not Found", "", renderToString(notFoundPage));
+  const notFoundFavicon = docuConfig.meta?.favicon || "/favicon.ico";
+  const notFoundHtml = htmlShell({
+    title: "404 - Not Found",
+    description: "",
+    body: renderToString(notFoundPage),
+    favicon: notFoundFavicon,
+    css: assetManifest.css,
+    js: assetManifest.js,
+    nonce: generateNonce(),
+    themeCss: inlineThemeCss,
+  });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 
   logger.spinner.stop(
     `Built ${built} pages (${skipped} cached) \x1b[90m(${Math.round(performance.now() - t)}ms)\x1b[0m`
   );
 
+  if (builder) {
+    const pages: PageMeta[] = mdxFiles.map((f) => ({
+      slug: f.path,
+      title: f.path.split("/").pop() || f.path,
+      filePath: join(DOCS_DIR, f.path),
+      outputPath: join(DIST_DIR, "docs", `${f.path}.html`),
+    }));
+    await builder.runOnEnd(pages);
+  }
+
   logger.indexStart();
   t = performance.now();
   const indexCount = await generateSearchIndex();
@@ -330,10 +393,12 @@ async function build() {
   }
 }
 
-initSentry()
-  .then(() => build())
-  .catch((err) => {
-    captureException(err);
-    console.error("Build failed:", err);
-    process.exit(1);
-  });
+if (!process.env.VITEST) {
+  initSentry()
+    .then(() => build())
+    .catch((err) => {
+      captureException(err);
+      console.error("Build failed:", err);
+      process.exit(1);
+    });
+}

package/.docu/node/html.ts

@@ -6,14 +6,39 @@ export interface HtmlShellOptions {
   css: string;
   js: string;
   nonce?: string;
+  /**
+   * Content-Security-Policy value (from `cspHeader()` in security.ts).
+   * When provided, injects `<meta http-equiv="Content-Security-Policy">` in `<head>`.
+   * Essential for static deployment where HTTP headers cannot be set.
+   */
+  csp?: string;
   extraScripts?: string;
   themeCss?: string;
+  /** HTML strings to inject before `</head>` (from plugin `injectHead` hooks). */
+  headExtra?: string[];
+  /** HTML strings to inject before `</body>`, after the main script (from plugin `injectBody` hooks). */
+  bodyExtra?: string[];
 }
 
 export function htmlShell(opts: HtmlShellOptions): string {
-  const { title, description, body, favicon, css, js, nonce, extraScripts, themeCss } = opts;
+  const {
+    title,
+    description,
+    body,
+    favicon,
+    css,
+    js,
+    nonce,
+    csp,
+    extraScripts,
+    themeCss,
+    headExtra,
+    bodyExtra,
+  } = opts;
   const nonceAttr = nonce ? ` nonce="${Bun.escapeHTML(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${Bun.escapeHTML(themeCss)}</style>` : "";
+  const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
+  const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -23,15 +48,39 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <meta name="description" content="${Bun.escapeHTML(description)}">
   <link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(favicon)}">${themeStyle}
   <link rel="stylesheet" href="/assets/${Bun.escapeHTML(css)}">
-  <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>
+  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(csp)}">` : ""}
+  <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>
 <body>
   <div id="root">${body}</div>
-  <script${nonceAttr} src="/assets/${Bun.escapeHTML(js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}
+  <script${nonceAttr} src="/assets/${Bun.escapeHTML(js)}"></script>${extraScripts ? `\n  ${extraScripts}` : ""}${bodyInjection}
 </body>
 </html>`;
 }
 
+export function errorHtml(message: string, stack?: string): string {
+  const msg = Bun.escapeHTML(message || "Unknown error");
+  const st = Bun.escapeHTML(stack || "");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Server Error</title>
+  <style>
+    *{margin:0;padding:0;box-sizing:border-box}
+    body{padding:2rem;font-family:ui-monospace,monospace;background:#1a1a2e;color:#e0e0e0}
+    h1{color:#ff6b6b;font-size:1.5rem;margin-bottom:1rem}
+    pre{background:#0d0d1a;border:1px solid #333;border-radius:8px;padding:1.5rem;overflow-x:auto;font-size:14px;line-height:1.6;white-space:pre-wrap;word-break:break-word}
+    .msg{color:#ff6b6b;font-weight:bold}
+  </style>
+</head>
+  <body>
+  <h1>🔥 Server Error</h1>
+    <pre><span class="msg">${msg}</span>${st ? `\n\n${st}` : ""}</pre>
+  </body>
+</html>`;
+}
+
 export function hmrScript(nonce: string): string {
   return `<script nonce="${Bun.escapeHTML(nonce)}">
 (function(){

package/.docu/node/mdx.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { Pluggable } from "unified";
 import {
   serialize,
   extractTocsFromRawMdx,
@@ -19,10 +20,21 @@ export interface MdxResult {
   tocs: ReturnType<typeof extractTocsFromRawMdx>;
 }
 
+/**
+ * Compile MDX/MD content into a React element and compiled source.
+ *
+ * @param rawMdx - Raw MDX/MD file content
+ * @param filePath - Relative file path for git date lookup
+ * @param gitDates - Optional pre-fetched git last-modified map
+ * @param remarkPlugins - Additional remark plugins (merged after defaults, optional)
+ * @param rehypePlugins - Additional rehype plugins (merged after defaults, optional)
+ */
 export async function compileMdx(
   rawMdx: string,
   filePath: string,
-  gitDates?: Map<string, string>
+  gitDates?: Map<string, string>,
+  remarkPlugins?: Pluggable[],
+  rehypePlugins?: Pluggable[]
 ): Promise<MdxResult> {
   const tocs = extractTocsFromRawMdx(rawMdx);
   const { frontmatter, strippedContent } = extractFrontmatterWithContent<{
@@ -31,10 +43,16 @@ export async function compileMdx(
     date?: string;
   }>(rawMdx);
 
+  const defaultRemark = createDefaultRemarkPlugins();
+  const defaultRehype = createDefaultRehypePlugins();
+
+  const finalRemark = remarkPlugins?.length ? [...defaultRemark, ...remarkPlugins] : defaultRemark;
+  const finalRehype = rehypePlugins?.length ? [...defaultRehype, ...rehypePlugins] : defaultRehype;
+
   const serialized = await serialize(strippedContent, {
     mdxOptions: {
-      rehypePlugins: createDefaultRehypePlugins(),
-      remarkPlugins: createDefaultRemarkPlugins(),
+      rehypePlugins: finalRehype,
+      remarkPlugins: finalRemark,
     },
   });