@docubook/flame 2.0.0-beta.3 → 2.0.0-beta.5

package/.docu/node/build.ts

@@ -30,7 +30,7 @@ import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
 import { loadPlugins } from "./plugin-loader";
 import { BuildPluginBuilder } from "./plugin-builder";
-import { scanMdxFiles } from "./utils";
+import { scanMdxFiles, resolveDocsIndexSource, DEFAULT_FAVICON } from "./utils";
 import type { BuildCache, BuildCacheMeta, CliArgs } from "./types";
 import { isCacheEntry } from "./types";
 import {
@@ -41,7 +41,7 @@ import {
   runtimeStamp,
 } from "./cache-key";
 import { clearDerivedPageCaches } from "./mdx";
-import { generateNonce } from "./security";
+import { generateNonce, cspHeader } from "./security";
 import type { PageMeta, PageContext } from "./plugin";
 import { buildSeoMeta } from "./seo";
 import DocsPage from "../pages/docs/[[...slug]]";
@@ -109,12 +109,11 @@ type RebuildDecision = "yes" | "hash_check" | "no";
 export function shouldRebuild(path: string, mtime: number, cache: BuildCache): RebuildDecision {
   const cached = cache[path];
   if (!isCacheEntry(cached)) return "yes";
-  // 2s tolerance: mtimeMs (float, fs precision) vs builtAt (int, Date.now())
-  // can miss on fast rebuilds after Bun 1.4's 2x faster startup — equality
-  // within tolerance still falls through to the hash check, never to "no".
-  if (mtime > cached.builtAt + 2000) return "hash_check";
-  if (Math.abs(mtime - cached.builtAt) <= 2000 && mtime !== cached.mtime) return "hash_check";
-  if (mtime !== cached.mtime && mtime > cached.mtime) return "hash_check";
+  // Any mtime drift vs the recorded one — a newer edit, or mtime moving
+  // backwards (rsync -a, cp -p, snapshot restore) — falls through to the
+  // hash check: hashing an unchanged file is cheap, serving a stale page
+  // is not. Only an untouched mtime skips without reading the file.
+  if (mtime !== cached.mtime) return "hash_check";
   return "no";
 }
 
@@ -227,14 +226,18 @@ async function renderDocsPage(
   const bodyExtra = builder?.collectBody(ctx);
 
   const depth = slug ? slug.split("/").length : 1;
-  const favicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const favicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
   const seo = buildSeoMeta(docuConfig, frontmatter, slug || "");
+  // Parity with build.impl.ts: static hosts without header control (GitHub
+  // Pages) rely on the <meta> CSP for the per-page script policy.
+  const csp = nonce ? cspHeader(nonce) : undefined;
   let html = htmlShell({
     title,
     description,
     body,
     favicon,
     seo,
+    csp,
     css: assetManifest.css,
     js: assetManifest.js,
     nonce,
@@ -337,15 +340,16 @@ async function build() {
   });
   await Promise.all(prePassTasks);
 
-  // The docs root (index.mdx) renders with slug "" — mirror that key so the
-  // index page hydrates too. Its render has its own try/catch; skip on error.
-  const indexMdxPath = join(DOCS_DIR, "index.mdx");
-  if (existsSync(indexMdxPath)) {
+  // The docs root (index.mdx, or index.md) renders with slug "" — mirror that
+  // key so the index page hydrates too. Its render has its own try/catch; skip
+  // on error.
+  const indexSource = resolveDocsIndexSource(DOCS_DIR);
+  if (indexSource) {
     try {
-      const indexRaw = await readFile(indexMdxPath, "utf-8");
+      const indexRaw = await readFile(indexSource, "utf-8");
       let indexContent = indexRaw;
       if (builder) {
-        const relPath = indexMdxPath.replace(PROJECT_ROOT + "/", "");
+        const relPath = indexSource.replace(PROJECT_ROOT + "/", "");
         const transformed = await builder.runOnLoad(relPath, indexContent);
         if (transformed?.contents) indexContent = transformed.contents;
       }
@@ -394,9 +398,8 @@ async function build() {
 
   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 + "/", ""));
+  if (indexSource) {
+    allRelPaths.push(indexSource.replace(PROJECT_ROOT + "/", ""));
   }
   const gitDates = await getGitLastModifiedBatch(allRelPaths);
 
@@ -476,38 +479,49 @@ async function build() {
     await Promise.all(buildTasks.slice(i, i + CONCURRENCY).map((fn) => fn()));
   }
 
-  try {
-    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,
-      builder,
-      generateNonce()
-    );
-    await mkdir(join(DIST_DIR, "docs"), { recursive: true });
-    await writeFile(join(DIST_DIR, "docs", "index.html"), indexHtml);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    errors.push(`index.mdx: ${msg}`);
-    console.error(`\n\u274C Failed to build index: ${msg}\n`);
+  if (indexSource) {
+    try {
+      const indexRaw = await readFile(indexSource, "utf-8");
+      const indexRelPath = indexSource.replace(PROJECT_ROOT + "/", "");
+      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) {
+      const msg = err instanceof Error ? err.message : String(err);
+      errors.push(`index: ${msg}`);
+      console.error(`\n❌ Failed to build index: ${msg}\n`);
+    }
+  } else {
+    const msg = "docs root index: docs/index.mdx (or docs/index.md) not found";
+    errors.push(`index: ${msg}`);
+    console.error(`\n❌ Failed to build index: ${msg}\n`);
   }
 
   const landingPage = React.createElement(IndexPage);
-  const landingFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
-  const landingSeo = buildSeoMeta(docuConfig, {}, "");
+  const landingFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const landingSeo = buildSeoMeta(
+    docuConfig,
+    docuConfig.meta as unknown as Record<string, unknown>,
+    ""
+  );
+  const landingNonce = generateNonce();
   const landingHtml = htmlShell({
     title: docuConfig.meta?.title || "DocuBook",
     description: docuConfig.meta?.description || "",
     body: renderToString(landingPage),
     favicon: landingFavicon,
     seo: landingSeo,
+    csp: cspHeader(landingNonce),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: landingNonce,
     themeCss: inlineThemeCss,
   });
   await writeFile(join(DIST_DIR, "index.html"), landingHtml);
@@ -517,16 +531,18 @@ async function build() {
     { repoUrl: docuConfig.repo?.url },
     React.createElement(NotFoundPage)
   );
-  const notFoundFavicon = docuConfig.meta?.favicon || "/docs/assets/images/favicon.ico";
+  const notFoundFavicon = docuConfig.meta?.favicon || DEFAULT_FAVICON;
+  const notFoundNonce = generateNonce();
   const notFoundHtml = htmlShell({
     title: "404 - Not Found",
     description: "",
     body: renderToString(notFoundPage),
     favicon: notFoundFavicon,
     headExtra: ['<meta name="robots" content="noindex,follow">'],
+    csp: cspHeader(notFoundNonce),
     css: assetManifest.css,
     js: assetManifest.js,
-    nonce: generateNonce(),
+    nonce: notFoundNonce,
     themeCss: inlineThemeCss,
     // Served as the static-host fallback at ANY requested path — relative
     // depth can never be right there, so use root-absolute asset URLs.

package/.docu/node/cache-key.ts

@@ -8,7 +8,7 @@ import { FRAMEWORK_ROOT, STYLES_DIR, resolveProjectFile } from "./paths";
  * (e.g. Bun.build barrel optimization, Tailwind CLI upgrade). Old caches
  * with a mismatched version are discarded on read (see build.ts readCache).
  */
-export const BUILD_CACHE_VERSION = 3;
+export const BUILD_CACHE_VERSION = 4;
 
 /** Toolchain fingerprint: Bun version on Bun, Deno version on Deno, Node elsewhere. */
 export function runtimeStamp(): string {

package/.docu/node/html.shared.ts

@@ -7,6 +7,7 @@
  */
 
 import { escapeHtml } from "./escapeHtml";
+import { cspMeta } from "./security";
 
 import type { SeoMeta } from "./seo";
 
@@ -86,7 +87,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${escapeHtml(resolvePath(favicon))}">` : ""}${themeStyle}
   <link rel="preload" href="${escapeHtml(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${escapeHtml(assetPrefix + css)}">
-  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">` : ""}
+  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(cspMeta(csp))}">` : ""}
   ${seoTags}
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>

package/.docu/node/html.ts

@@ -1,5 +1,6 @@
 import type { HtmlShellOptions } from "./html.shared";
 export type { HtmlShellOptions };
+import { cspMeta } from "./security";
 
 export function htmlShell(opts: HtmlShellOptions): string {
   const {
@@ -48,7 +49,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   ${favicon ? `<link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(resolvePath(favicon))}">` : ""}${themeStyle}
   <link rel="preload" href="${Bun.escapeHTML(assetPrefix + css)}" as="style">
   <link rel="stylesheet" href="${Bun.escapeHTML(assetPrefix + css)}">
-  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(csp)}">` : ""}
+  ${csp ? `<meta http-equiv="Content-Security-Policy" content="${Bun.escapeHTML(cspMeta(csp))}">` : ""}
   ${seoTags}
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>${headInjection}
 </head>

package/.docu/node/mdx-manifest.d.ts

@@ -1,5 +1,4 @@
 // Virtual module served by the `mdx-hydrate` esbuild plugin (hydrate.node.ts).
 // Maps doc slug → compiled MDX module. Generated at bundle time; never on disk.
-declare module "./mdx-manifest" {
-  export const mdxModules: Record<string, { default: React.ComponentType }>;
-}
+import type { ComponentType } from "react";
+export declare const mdxModules: Record<string, { default: ComponentType }>;

package/.docu/node/mdx.ts

@@ -3,7 +3,8 @@ import type { Pluggable } from "unified";
 import { z, type ZodType } from "zod";
 import {
   serialize,
-  extractTocsFromRawMdx,
+  rehypeCollectTocs,
+  type TocItem,
   extractFrontmatterWithContent,
   createDefaultRehypePlugins,
   createDefaultRemarkPlugins,
@@ -108,7 +109,7 @@ export interface MdxResult {
   content: React.ReactElement;
   compiledSource: string;
   frontmatter: Frontmatter;
-  tocs: ReturnType<typeof extractTocsFromRawMdx>;
+  tocs: TocItem[];
 }
 
 /**
@@ -186,7 +187,13 @@ async function serializeWithDocPlugins(
   // transforms see already-fixed hrefs.  rehypeDocsHtmlLinks handles plain
   // markdown [text](path) → <a> elements in the HAST phase.
   const finalRemark = [...defaultRemark, remarkMdxJsxDocsHtmlLinks, ...(opts.remarkPlugins ?? [])];
-  const finalRehype = [...defaultRehype, rehypeDocsHtmlLinks, ...(opts.rehypePlugins ?? [])];
+  const tocs: TocItem[] = [];
+  const finalRehype: Pluggable[] = [
+    ...defaultRehype,
+    rehypeDocsHtmlLinks,
+    ...(opts.rehypePlugins ?? []),
+    [rehypeCollectTocs, tocs],
+  ];
 
   // v2 contract: plain markdown + directives only — authored JSX tags are
   // not parsed (dropped, content kept as text). Return the frontmatter parsed
@@ -198,7 +205,7 @@ async function serializeWithDocPlugins(
       rehypePlugins: finalRehype,
       remarkPlugins: finalRemark,
     },
-  }).then((serialized) => ({ ...serialized, frontmatter, strippedContent }));
+  }).then((serialized) => ({ ...serialized, frontmatter, strippedContent, tocs }));
 }
 
 /**
@@ -221,7 +228,6 @@ export async function compileMdx(
   /** Pre-pass extracted data — avoids re-parsing frontmatter in the SSR phase. */
   pre?: { frontmatter: Frontmatter; strippedContent: string }
 ): Promise<MdxResult> {
-  const tocs = extractTocsFromRawMdx(rawMdx);
   const frontmatter =
     pre?.frontmatter ??
     (frontmatterSchema
@@ -252,7 +258,7 @@ export async function compileMdx(
     content,
     compiledSource: serialized.compiledSource,
     frontmatter: { ...frontmatter, date },
-    tocs,
+    tocs: serialized.tocs,
   };
 }
 

package/.docu/node/plugin-builder.ts

@@ -408,6 +408,8 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Execute the transformHtml chain in pipeline pattern.
    * Each callback receives the **previous** callback's return value (or the
    * original HTML for the first). Every callback **must** return a string.
+   * Callbacks returning a non-string (e.g. `undefined`) are skipped with a
+   * warning — the current HTML passes through unchanged for that step.
    * Errors inside individual callbacks are caught and logged — the current
    * HTML passes through unchanged for that step.
    *
@@ -419,7 +421,14 @@ export class BuildPluginBuilder implements PluginBuilder {
     let result = html;
     for (let i = 0; i < this._transformHtml.length; i++) {
       try {
-        result = await this._transformHtml[i](result, context);
+        const next = await this._transformHtml[i](result, context);
+        if (typeof next === "string") {
+          result = next;
+        } else {
+          console.warn(
+            `[plugin] transformHtml callback #${i + 1} returned invalid type (expected a string), keeping previous HTML`
+          );
+        }
       } catch (err) {
         console.error(
           `[plugin] transformHtml callback #${i + 1} error: ${err instanceof Error ? err.message : String(err)}`

package/.docu/node/route.ts

@@ -47,6 +47,22 @@ export function getRouteMap(): Map<string, string> {
   return map;
 }
 
+/**
+ * Single pagination entry builder (DRY) — one `readPageFrontmatter` call
+ * serves both prev + next from the parse-once registry, so no file is
+ * re-read or re-parsed. `description` rides along on prev too; the UI
+ * keeps the paired prev minimal by design and only renders the rich
+ * title + description when prev stands alone (last page, no next).
+ */
+function toPaginationEntry(href: string, routeMap: Map<string, string>) {
+  const fm = readPageFrontmatter(href);
+  return {
+    href,
+    title: fm.title || routeMap.get(href) || "",
+    description: fm.description || "",
+  };
+}
+
 /**
  * Frontmatter for a page — read from the parse-once registry (populated
  * during compilation) instead of re-reading + re-parsing the file. Falls
@@ -86,15 +102,7 @@ export function getPreviousNext(pathname: string) {
     const routeMap = getRouteMap();
     const first = paths[0];
     if (!first) return { prev: null, next: null };
-    const fm = readPageFrontmatter(first);
-    return {
-      prev: null,
-      next: {
-        href: first,
-        title: fm.title || routeMap.get(first) || "",
-        description: fm.description || "",
-      },
-    };
+    return { prev: null, next: toPaginationEntry(first, routeMap) };
   }
 
   const paths = flattenRoutes();
@@ -109,19 +117,9 @@ export function getPreviousNext(pathname: string) {
   const prevHref = index > 0 ? paths[index - 1] : null;
   const nextHref = index < paths.length - 1 ? paths[index + 1] : null;
 
-  const prevFm = prevHref ? readPageFrontmatter(prevHref) : null;
-  const nextFm = nextHref ? readPageFrontmatter(nextHref) : null;
   return {
-    prev: prevHref
-      ? { href: prevHref, title: prevFm?.title || routeMap.get(prevHref) || "" }
-      : null,
-    next: nextHref
-      ? {
-          href: nextHref,
-          title: nextFm?.title || routeMap.get(nextHref) || "",
-          description: nextFm?.description || "",
-        }
-      : null,
+    prev: prevHref ? toPaginationEntry(prevHref, routeMap) : null,
+    next: nextHref ? toPaginationEntry(nextHref, routeMap) : null,
   };
 }
 

package/.docu/node/search-indexer.ts

@@ -39,6 +39,7 @@ export interface SearchRecord {
 interface Frontmatter {
   title?: string;
   description?: string;
+  [key: string]: unknown;
 }
 
 function getSectionTitle(filePath: string): string {
@@ -142,15 +143,20 @@ export function extractRecords(filePath: string, raw: string): SearchRecord[] {
       const level = headingMatch[1].length;
       const title = headingMatch[2].replace(/[*`[\]]/g, "").trim();
 
+      if (level === 1) {
+        // Frontmatter title is authoritative; use H1 only as a fallback.
+        for (let i = 2; i <= 6; i++) {
+          (hierarchy as Record<string, string | null>)[`lvl${i}`] = null;
+        }
+        if (!hierarchy.lvl1) hierarchy.lvl1 = title;
+        continue;
+      }
+
       for (let i = level; i <= 6; i++) {
         (hierarchy as Record<string, string | null>)[`lvl${i}`] = null;
       }
       hierarchy[`lvl${level}` as keyof typeof hierarchy] = title;
 
-      if (level === 1 && !hierarchy.lvl1) {
-        hierarchy.lvl1 = title;
-      }
-
       if (level >= 2) {
         records.push({
           url: `${url}#${slugify(title)}`,

package/.docu/node/search.ts

@@ -54,10 +54,16 @@ function levenshtein(a: string, b: string): number {
 function fuzzyMatch(query: string, text: string): number {
   const q = query.toLowerCase();
   const t = text.toLowerCase();
+  const words = t.split(/\s+/);
+  const shortQuery = q.length <= 3;
 
-  if (t.includes(q)) return 1;
+  // For short queries, prefer a meaningful word prefix (`seq` → `sequence`)
+  // over an isolated exact occurrence in lower-signal text. This keeps search
+  // useful without removing substring or typo matching.
+  if (words.some((word) => word === q)) return shortQuery ? 0.9 : 1;
+  if (words.some((word) => word.startsWith(q))) return 0.95;
+  if (t.includes(q)) return shortQuery ? 0.7 : 1;
 
-  const words = t.split(/\s+/);
   let bestScore = 0;
 
   for (const word of words) {

package/.docu/node/security.ts

@@ -30,6 +30,15 @@ export function cspHeader(nonce: string, allowEval = false): string {
   ].join("; ");
 }
 
+/**
+ * Strip `frame-ancestors` for `<meta http-equiv="Content-Security-Policy">`.
+ * Browsers ignore `frame-ancestors` in meta CSP (header-only directive)
+ * and log a console warning. HTTP header from `cspHeader()` keeps it.
+ */
+export function cspMeta(csp: string): string {
+  return csp.replace(/;\s*frame-ancestors 'none'/, "");
+}
+
 export function isPathSafe(pathname: string, baseDir: string): boolean {
   const decoded = decodeURIComponent(pathname);
   const resolved = resolve(baseDir, decoded.slice(1));
@@ -87,12 +96,20 @@ export function normalizeImporterPath(importer: string): string {
 }
 
 export function injectNonce(html: string, nonce: string): string {
-  return html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
+  const scripts = html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
     if (/nonce\s*=/i.test(match)) {
       return match.replace(/nonce="[^"]*"/i, `nonce="${nonce}"`);
     }
     return match.replace(/>$/, ` nonce="${nonce}">`);
   });
+  // Keep the <meta> CSP nonce in sync: browsers intersect the meta policy
+  // with the response-header policy, so a stale build-time nonce would block
+  // the very scripts re-tagged above.
+  return scripts.replace(/<meta\b[^>]*Content-Security-Policy[^>]*>/gi, (tag) =>
+    tag.replace(/'nonce-[^']*'|&#(?:x27;|39;)nonce-[^&]*(?:&#(?:x27;|39;))/i, (match) =>
+      match.startsWith("&#") ? `&#x27;nonce-${nonce}&#x27;` : `'nonce-${nonce}'`
+    )
+  );
 }
 
 export interface PluginResponseLike {

package/.docu/node/server-routes.ts

@@ -4,7 +4,7 @@ import { readFileSync, statSync } from "node:fs";
 import React, { type ReactNode } from "react";
 import { renderToString } from "react-dom/server";
 import { compileMdx, frontmatterField } from "./mdx";
-import { getContentType } from "./utils";
+import { DEFAULT_FAVICON, getContentType } from "./utils";
 import { DOCS_DIR, DIST_DIR, PROJECT_ROOT } from "./paths";
 import { BuildPluginBuilder } from "./plugin-builder";
 import type { PageContext } from "./plugin";
@@ -32,7 +32,7 @@ function createHtmlResponse(
   depth = 0
 ): Response {
   const nonce = generateNonce();
-  const favicon = state.docuConfig.meta?.favicon || "/favicon.ico";
+  const favicon = state.docuConfig.meta?.favicon || DEFAULT_FAVICON;
   const html = createHtmlShell({
     title,
     description,
@@ -187,7 +187,7 @@ async function renderDocsServerPage(
     const headExtra = state.builder.collectHead(ctx);
     const bodyExtra = state.builder.collectBody(ctx);
     const nonce = generateNonce();
-    const favicon = state.docuConfig.meta?.favicon || "/favicon.ico";
+    const favicon = state.docuConfig.meta?.favicon || DEFAULT_FAVICON;
     let html = createHtmlShell({
       title,
       description,

package/.docu/node/types.ts

@@ -106,7 +106,7 @@ export interface BuildCacheMeta extends BuildCacheEntry {
 }
 
 export interface BuildCache {
-  [path: string]: BuildCacheEntry;
+  [path: string]: BuildCacheEntry | undefined;
   __meta__?: BuildCacheMeta;
   __assets__?: BuildCacheEntry;
   __bundle__?: BuildCacheEntry;

package/.docu/node/utils.ts

@@ -1,5 +1,6 @@
 export { cn, parseDate, formatDate, formatDate2 } from "@docubook/core";
 
+import { existsSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -11,7 +12,8 @@ export interface ScannedMdxFile {
 
 /**
  * Scan a directory recursively for MDX/MD files.
- * Skips "assets" directories, hidden directories (dot-prefixed), and root-level index.mdx.
+ * Skips "assets" directories, hidden directories (dot-prefixed), and root-level
+ * index.mdx/index.md (the docs root renders separately in build).
  * Shared between build.ts and search-indexer.ts.
  */
 export async function scanMdxFiles(dir: string, baseDir = ""): Promise<ScannedMdxFile[]> {
@@ -26,7 +28,9 @@ export async function scanMdxFiles(dir: string, baseDir = ""): Promise<ScannedMd
       if (entry.name === "assets" || entry.name.startsWith(".")) continue;
       files.push(...(await scanMdxFiles(fullPath, relativePath)));
     } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
-      if (entry.name === "index.mdx" && !baseDir) continue;
+      // Root index renders separately (either extension) — scanning it would
+      // produce a duplicate "index" page colliding with dist/docs/index.html.
+      if (!baseDir && (entry.name === "index.mdx" || entry.name === "index.md")) continue;
       const stats = await stat(fullPath);
       let path = relativePath.replace(/\.(mdx|md)$/, "");
 
@@ -44,6 +48,22 @@ export function isExternalUrl(url: string): boolean {
   return /^(https?:\/\/|\/\/)/.test(url);
 }
 
+/**
+ * Resolve the docs root index source — docs/index.mdx preferred, docs/index.md
+ * as fallback (mirrors the dev server's getDocsForSlug extension handling).
+ */
+export function resolveDocsIndexSource(docsDir: string): string | undefined {
+  for (const ext of [".mdx", ".md"]) {
+    const candidate = join(docsDir, `index${ext}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** Default favicon — resolves in both build output (`docs/assets/` is copied
+ *  to `dist/docs/assets/`) and dev (served from `docs/assets/` via fallback). */
+export const DEFAULT_FAVICON = "/docs/assets/images/favicon.ico";
+
 /** Suffix an internal docs link with `.html` to match the flat static build output. */
 export function docsHtmlHref(path: string): string {
   return `${path}.html`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -45,6 +45,10 @@
   "author-url": "https://wildan.dev",
   "license": "MIT",
   "dependencies": {
+    "@docubook/core": "^2.0.0-beta.5",
+    "@docubook/markdown": "^2.0.0-beta.5",
+    "@docubook/themes-colors": "^2.0.0-beta.5",
+    "@docubook/ui-react": "^2.0.0-beta.5",
     "@mdx-js/react": "^3.0.1",
     "@tailwindcss/cli": "4.3.0",
     "@tailwindcss/typography": "0.5.16",
@@ -55,11 +59,7 @@
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
     "vite": "^8.2.1",
-    "zod": "^4.4.3",
-    "@docubook/core": "^2.0.0-beta.3",
-    "@docubook/markdown": "^2.0.0-beta.3",
-    "@docubook/themes-colors": "^2.0.0-beta.3",
-    "@docubook/ui-react": "^2.0.0-beta.3"
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"