@docubook/flame 2.0.0-alpha.2 → 2.0.0-beta.0

package/.docu/lib/build.deno.js

@@ -1,9 +1,9 @@
 import {
   runBuildCli
-} from "./chunk-3LRUTZZD.js";
-import "./chunk-42JQLAKP.js";
+} from "./chunk-C3RCUTUE.js";
+import "./chunk-LXJLSXQI.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/build.deno.ts

package/.docu/lib/{build.impl-AZBZN66Q.js → build.impl-S4DS5XPH.js}

@@ -1,10 +1,10 @@
 import {
   runBuild,
   runBuildCli
-} from "./chunk-3LRUTZZD.js";
-import "./chunk-42JQLAKP.js";
+} from "./chunk-C3RCUTUE.js";
+import "./chunk-LXJLSXQI.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 export {
   runBuild,

package/.docu/lib/build.node.js

@@ -1,9 +1,9 @@
 import {
   runBuildCli
-} from "./chunk-3LRUTZZD.js";
-import "./chunk-42JQLAKP.js";
+} from "./chunk-C3RCUTUE.js";
+import "./chunk-LXJLSXQI.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/build.node.ts

package/.docu/lib/{chunk-3LRUTZZD.js → chunk-C3RCUTUE.js}

@@ -12,10 +12,14 @@ import {
   frontmatterField,
   generateSearchIndex,
   getGitLastModifiedBatch,
+  getPageContent,
+  getPageFrontmatter,
+  getPageStripped,
   htmlShell,
   initSentry,
-  loadPlugins
-} from "./chunk-42JQLAKP.js";
+  loadPlugins,
+  registerPageContent
+} from "./chunk-LXJLSXQI.js";
 import {
   cspHeader,
   generateNonce,
@@ -23,7 +27,7 @@ import {
 } from "./chunk-EOK6KATZ.js";
 import {
   logger
-} from "./chunk-IN2QAGDZ.js";
+} from "./chunk-IVM5UM44.js";
 import {
   ASSETS_DIR,
   CACHE_FILE,
@@ -109,7 +113,18 @@ async function renderDocsPage(docuConfig, slug, rawMdx, filePath, gitDates, buil
   try {
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    result = await compileMdx(content, filePath, gitDates, remarkPlugins, rehypePlugins);
+    const preFm = getPageFrontmatter(`/${slug}`);
+    const preStripped = getPageStripped(`/${slug}`);
+    const pre = preFm !== void 0 && preStripped !== void 0 ? { frontmatter: preFm, strippedContent: preStripped } : void 0;
+    result = await compileMdx(
+      content,
+      filePath,
+      gitDates,
+      remarkPlugins,
+      rehypePlugins,
+      void 0,
+      pre
+    );
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Unknown MDX error";
     throw new Error(`MDX Error in: docs/${slug}.mdx
@@ -222,6 +237,7 @@ async function runBuild() {
     } catch {
       return;
     }
+    registerPageContent(`/${file.path}`, raw);
     let content = raw;
     if (builder) {
       const relPath = file.absPath.replace(PROJECT_ROOT + "/", "");
@@ -230,7 +246,12 @@ async function runBuild() {
     }
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    mdxSources[file.path] = await compileMdxModule(content, remarkPlugins, rehypePlugins);
+    mdxSources[file.path] = await compileMdxModule(
+      content,
+      remarkPlugins,
+      rehypePlugins,
+      `/${file.path}`
+    );
   });
   await Promise.all(prePassTasks);
   const indexMdxPath = join(DOCS_DIR, "index.mdx");
@@ -285,12 +306,14 @@ async function runBuild() {
         continue;
       }
     }
-    let rawMdx;
-    try {
-      rawMdx = await readFile(file.absPath, "utf-8");
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-      continue;
+    let rawMdx = getPageContent(`/${file.path}`);
+    if (rawMdx === void 0) {
+      try {
+        rawMdx = await readFile(file.absPath, "utf-8");
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+        continue;
+      }
     }
     if (rebuildDecision === "hash_check") {
       const contentHash = hashContent(rawMdx);
@@ -418,8 +441,9 @@ async function runBuild() {
   }
   logger.indexStart();
   t = performance.now();
-  const indexCount = await generateSearchIndex();
-  logger.indexDone(indexCount, Math.round(performance.now() - t));
+  const indexSkipped = built === 0 && existsSync(join(ASSETS_DIR, "search-index.json"));
+  const indexCount = indexSkipped ? 0 : await generateSearchIndex();
+  logger.indexDone(indexCount, Math.round(performance.now() - t), indexSkipped);
   logger.routes();
   await writeCache(cache);
   if (errors.length > 0) {

package/.docu/lib/{chunk-HF3KKRQL.js → chunk-D3QTSBR4.js}

@@ -15,7 +15,7 @@ import {
   htmlShell,
   initSentry,
   loadPlugins
-} from "./chunk-42JQLAKP.js";
+} from "./chunk-LXJLSXQI.js";
 import {
   SECURITY_HEADERS,
   generateNonce,
@@ -28,7 +28,7 @@ import {
 } from "./chunk-EOK6KATZ.js";
 import {
   logger
-} from "./chunk-IN2QAGDZ.js";
+} from "./chunk-IVM5UM44.js";
 import {
   DIST_DIR,
   DOCS_DIR,

package/.docu/lib/{chunk-IN2QAGDZ.js → chunk-IVM5UM44.js}

@@ -5,7 +5,7 @@ import {
 // package.json
 var package_default = {
   name: "@docubook/flame",
-  version: "2.0.0-alpha.2",
+  version: "2.0.0-beta.0",
   description: "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   type: "module",
   bin: {
@@ -239,9 +239,11 @@ ${c.bold}${c.cyan}  \u{1F525} DocuBook Flame${c.reset} ${c.dim}v${package_defaul
     if (guard("info", "index_start")) return;
     this.spinner.start("Generating search index...");
   },
-  indexDone(records, ms) {
-    if (guard("info", "index_done", { records, duration_ms: ms })) return;
-    this.spinner.stop(`Search index generated ${c.dim}(${records} records, ${ms}ms)${c.reset}`);
+  indexDone(records, ms, skipped = false) {
+    if (guard("info", "index_done", { records, duration_ms: ms, skipped })) return;
+    this.spinner.stop(
+      skipped ? `Search index cached ${c.dim}(${ms}ms)${c.reset}` : `Search index generated ${c.dim}(${records} records, ${ms}ms)${c.reset}`
+    );
   },
   routes() {
     if (guard("debug", "routes")) return;

package/.docu/lib/{chunk-PGIHPW5L.js → chunk-JMQI3FKV.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-EOK6KATZ.js";
 import {
   logger
-} from "./chunk-IN2QAGDZ.js";
+} from "./chunk-IVM5UM44.js";
 import {
   DIST_DIR
 } from "./chunk-4IQXHHPF.js";

package/.docu/lib/{chunk-42JQLAKP.js → chunk-LXJLSXQI.js}

@@ -1101,15 +1101,12 @@ var frontmatterSchema = z.object({
   description: z.coerce.string().optional(),
   image: z.coerce.string().optional(),
   date: z.coerce.string().optional()
-});
+}).passthrough();
 function frontmatterField(frontmatter, key) {
   return typeof frontmatter[key] === "string" ? frontmatter[key] : "";
 }
-async function serializeWithDocPlugins(rawMdx, opts = {}) {
-  const { strippedContent } = extractFrontmatterWithContent(
-    rawMdx,
-    opts.frontmatterSchema
-  );
+async function serializeWithDocPlugins(rawMdx, opts = {}, pre) {
+  const { strippedContent, frontmatter } = pre ?? extractFrontmatterWithContent(rawMdx, opts.frontmatterSchema);
   const defaultRemark = createDefaultRemarkPlugins();
   const defaultRehype = createDefaultRehypePlugins();
   const finalRemark = [...defaultRemark, remarkMdxJsxDocsHtmlLinks, ...opts.remarkPlugins ?? []];
@@ -1121,16 +1118,16 @@ async function serializeWithDocPlugins(rawMdx, opts = {}) {
       rehypePlugins: finalRehype,
       remarkPlugins: finalRemark
     }
-  });
+  }).then((serialized) => ({ ...serialized, frontmatter, strippedContent }));
 }
-async function compileMdx(rawMdx, filePath, gitDates, remarkPlugins, rehypePlugins, frontmatterSchema2) {
+async function compileMdx(rawMdx, filePath, gitDates, remarkPlugins, rehypePlugins, frontmatterSchema2, pre) {
   const tocs = extractTocsFromRawMdx(rawMdx);
-  const { frontmatter } = extractFrontmatterWithContent(rawMdx, frontmatterSchema2);
-  const serialized = await serializeWithDocPlugins(rawMdx, {
-    remarkPlugins,
-    rehypePlugins,
-    frontmatterSchema: frontmatterSchema2
-  });
+  const frontmatter = pre?.frontmatter ?? extractFrontmatterWithContent(rawMdx, frontmatterSchema2).frontmatter;
+  const serialized = await serializeWithDocPlugins(
+    rawMdx,
+    { remarkPlugins, rehypePlugins, frontmatterSchema: frontmatterSchema2 },
+    pre
+  );
   const components = createMdxComponents();
   const content = React.createElement(MDXRemote, {
     compiledSource: serialized.compiledSource,
@@ -1146,12 +1143,37 @@ async function compileMdx(rawMdx, filePath, gitDates, remarkPlugins, rehypePlugi
     tocs
   };
 }
-async function compileMdxModule(rawMdx, remarkPlugins, rehypePlugins) {
+var pageFrontmatter = /* @__PURE__ */ new Map();
+function registerPageFrontmatter(href, frontmatter) {
+  pageFrontmatter.set(href, frontmatter);
+}
+function getPageFrontmatter(href) {
+  return pageFrontmatter.get(href);
+}
+var pageStripped = /* @__PURE__ */ new Map();
+function registerPageStripped(href, stripped) {
+  pageStripped.set(href, stripped);
+}
+function getPageStripped(href) {
+  return pageStripped.get(href);
+}
+var pageContent = /* @__PURE__ */ new Map();
+function registerPageContent(href, raw) {
+  pageContent.set(href, raw);
+}
+function getPageContent(href) {
+  return pageContent.get(href);
+}
+async function compileMdxModule(rawMdx, remarkPlugins, rehypePlugins, href) {
   const serialized = await serializeWithDocPlugins(rawMdx, {
     outputFormat: "program",
     remarkPlugins,
     rehypePlugins
   });
+  if (href) {
+    registerPageFrontmatter(href, serialized.frontmatter);
+    registerPageStripped(href, serialized.strippedContent);
+  }
   return serialized.compiledSource;
 }
 
@@ -1278,7 +1300,7 @@ async function generateSearchIndex(docsDir, outputDir) {
   const mdxFiles = await scanMdxFiles(docs);
   const results = await Promise.all(
     mdxFiles.map(async (file) => {
-      const raw = await readFile2(file.absPath, "utf-8");
+      const raw = getPageContent(`/${file.path}`) ?? await readFile2(file.absPath, "utf-8");
       return extractRecords(file.path, raw);
     })
   );
@@ -1364,25 +1386,23 @@ function getRouteMap() {
   routes.forEach((route) => traverse(route));
   return map;
 }
-var descriptionCache = /* @__PURE__ */ new Map();
-function readDescription(href) {
-  const cached = descriptionCache.get(href);
-  if (cached !== void 0) return cached;
-  let description = "";
+function readPageFrontmatter(href) {
+  const registered = getPageFrontmatter(href);
+  if (registered) return registered;
+  let fm = {};
   const rel = href.replace(/^\/|$/g, "");
   for (const ext of [".mdx", ".md"]) {
     for (const file of [join4(DOCS_DIR, `${rel}${ext}`), join4(DOCS_DIR, `${rel}/index${ext}`)]) {
       try {
-        const fm = extractFrontmatter(readFileSync2(file, "utf-8"));
-        description = typeof fm.description === "string" ? fm.description : "";
-        if (description) break;
+        fm = extractFrontmatter(readFileSync2(file, "utf-8"));
+        break;
       } catch {
       }
     }
-    if (description) break;
+    if (Object.keys(fm).length) break;
   }
-  descriptionCache.set(href, description);
-  return description;
+  registerPageFrontmatter(href, fm);
+  return fm;
 }
 function getPreviousNext(pathname) {
   const normalizedPath = pathname.replace(/^\/|$/g, "");
@@ -1391,12 +1411,13 @@ function getPreviousNext(pathname) {
     const routeMap2 = getRouteMap();
     const first = paths2[0];
     if (!first) return { prev: null, next: null };
+    const fm = readPageFrontmatter(first);
     return {
       prev: null,
       next: {
         href: first,
-        title: routeMap2.get(first) || "",
-        description: readDescription(first)
+        title: fm.title || routeMap2.get(first) || "",
+        description: fm.description || ""
       }
     };
   }
@@ -1408,12 +1429,14 @@ function getPreviousNext(pathname) {
   const routeMap = getRouteMap();
   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: routeMap.get(prevHref) || "" } : null,
+    prev: prevHref ? { href: prevHref, title: prevFm?.title || routeMap.get(prevHref) || "" } : null,
     next: nextHref ? {
       href: nextHref,
-      title: routeMap.get(nextHref) || "",
-      description: readDescription(nextHref)
+      title: nextFm?.title || routeMap.get(nextHref) || "",
+      description: nextFm?.description || ""
     } : null
   };
 }
@@ -2650,6 +2673,10 @@ export {
   getGitLastModifiedBatch,
   frontmatterField,
   compileMdx,
+  getPageFrontmatter,
+  getPageStripped,
+  registerPageContent,
+  getPageContent,
   compileMdxModule,
   generateSearchIndex,
   initSentry,

package/.docu/lib/{chunk-PJVCY4FK.js → chunk-O326MYJE.js}

@@ -137,7 +137,7 @@ async function runBuild() {
     process.env.FLAME_BUILD_SILENT = "1";
     process.env.LOG_LEVEL = "error";
   }
-  const { runBuildCli } = await import("./build.impl-AZBZN66Q.js");
+  const { runBuildCli } = await import("./build.impl-S4DS5XPH.js");
   await runBuildCli();
 }
 async function writeDockerFiles() {

package/.docu/lib/clean.js

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-IN2QAGDZ.js";
+} from "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/clean.ts

package/.docu/lib/deploy.deno.js

@@ -1,6 +1,6 @@
 import {
   runDeploy
-} from "./chunk-PJVCY4FK.js";
+} from "./chunk-O326MYJE.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/deploy.deno.ts

package/.docu/lib/deploy.node.js

@@ -1,6 +1,6 @@
 import {
   runDeploy
-} from "./chunk-PJVCY4FK.js";
+} from "./chunk-O326MYJE.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/deploy.node.ts

package/.docu/lib/preview.deno.js

@@ -1,11 +1,11 @@
 import {
   runPreview
-} from "./chunk-PGIHPW5L.js";
+} from "./chunk-JMQI3FKV.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.deno.ts

package/.docu/lib/preview.node.js

@@ -1,11 +1,11 @@
 import {
   runPreview
-} from "./chunk-PGIHPW5L.js";
+} from "./chunk-JMQI3FKV.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.node.ts

package/.docu/lib/server.deno.js

@@ -1,12 +1,12 @@
 import {
   runServer
-} from "./chunk-HF3KKRQL.js";
-import "./chunk-42JQLAKP.js";
+} from "./chunk-D3QTSBR4.js";
+import "./chunk-LXJLSXQI.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.deno.ts

package/.docu/lib/server.node.js

@@ -1,12 +1,12 @@
 import {
   runServer
-} from "./chunk-HF3KKRQL.js";
-import "./chunk-42JQLAKP.js";
+} from "./chunk-D3QTSBR4.js";
+import "./chunk-LXJLSXQI.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-IN2QAGDZ.js";
+import "./chunk-IVM5UM44.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.node.ts

package/.docu/node/build.impl.ts

@@ -12,7 +12,16 @@ import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 import React from "react";
 import { renderToString } from "react-dom/server";
-import { compileMdx, compileMdxModule, frontmatterField, getGitLastModifiedBatch } from "./mdx";
+import {
+  compileMdx,
+  compileMdxModule,
+  frontmatterField,
+  getGitLastModifiedBatch,
+  getPageContent,
+  getPageFrontmatter,
+  getPageStripped,
+  registerPageContent,
+} from "./mdx";
 import {
   DOCS_DIR,
   DIST_DIR,
@@ -105,7 +114,24 @@ async function renderDocsPage(
   try {
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    result = await compileMdx(content, filePath, gitDates, remarkPlugins, rehypePlugins);
+    // Parse-once: reuse the prePass frontmatter + stripped content so the
+    // SSR phase does not re-extract them. Only when the prePass actually
+    // registered them — otherwise compileMdx does its own extraction.
+    const preFm = getPageFrontmatter(`/${slug}`);
+    const preStripped = getPageStripped(`/${slug}`);
+    const pre =
+      preFm !== undefined && preStripped !== undefined
+        ? { frontmatter: preFm, strippedContent: preStripped }
+        : undefined;
+    result = await compileMdx(
+      content,
+      filePath,
+      gitDates,
+      remarkPlugins,
+      rehypePlugins,
+      undefined,
+      pre
+    );
   } 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 });
@@ -241,6 +267,9 @@ export async function runBuild(): Promise<void> {
     } catch {
       return;
     }
+    // Cache the original content so the page loop does not re-read the file
+    // (one disk read per file — the frontmatter is parsed once here too).
+    registerPageContent(`/${file.path}`, raw);
     let content = raw;
     if (builder) {
       const relPath = file.absPath.replace(PROJECT_ROOT + "/", "");
@@ -249,7 +278,12 @@ export async function runBuild(): Promise<void> {
     }
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    mdxSources[file.path] = await compileMdxModule(content, remarkPlugins, rehypePlugins);
+    mdxSources[file.path] = await compileMdxModule(
+      content,
+      remarkPlugins,
+      rehypePlugins,
+      `/${file.path}`
+    );
   });
   await Promise.all(prePassTasks);
 
@@ -319,12 +353,14 @@ export async function runBuild(): Promise<void> {
       }
     }
 
-    let rawMdx: string;
-    try {
-      rawMdx = await readFile(file.absPath, "utf-8");
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-      continue;
+    let rawMdx = getPageContent(`/${file.path}`);
+    if (rawMdx === undefined) {
+      try {
+        rawMdx = await readFile(file.absPath, "utf-8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+        continue;
+      }
     }
 
     if (rebuildDecision === "hash_check") {
@@ -458,8 +494,11 @@ export async function runBuild(): Promise<void> {
 
   logger.indexStart();
   t = performance.now();
-  const indexCount = await generateSearchIndex();
-  logger.indexDone(indexCount, Math.round(performance.now() - t));
+  // No content changed (all pages cached) → the aggregated index is
+  // unchanged too; reuse the existing file instead of regenerating it.
+  const indexSkipped = built === 0 && existsSync(join(ASSETS_DIR, "search-index.json"));
+  const indexCount = indexSkipped ? 0 : await generateSearchIndex();
+  logger.indexDone(indexCount, Math.round(performance.now() - t), indexSkipped);
 
   logger.routes();
 

package/.docu/node/build.ts

@@ -4,7 +4,16 @@ import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 import React from "react";
 import { renderToString } from "react-dom/server";
-import { compileMdx, compileMdxModule, frontmatterField, getGitLastModifiedBatch } from "./mdx";
+import {
+  compileMdx,
+  compileMdxModule,
+  frontmatterField,
+  getGitLastModifiedBatch,
+  getPageContent,
+  getPageFrontmatter,
+  getPageStripped,
+  registerPageContent,
+} from "./mdx";
 import {
   DOCS_DIR,
   DIST_DIR,
@@ -98,7 +107,24 @@ async function renderDocsPage(
   try {
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    result = await compileMdx(content, filePath, gitDates, remarkPlugins, rehypePlugins);
+    // Parse-once: reuse the prePass frontmatter + stripped content so the
+    // SSR phase does not re-extract them. Only when the prePass actually
+    // registered them — otherwise compileMdx does its own extraction.
+    const preFm = getPageFrontmatter(`/${slug}`);
+    const preStripped = getPageStripped(`/${slug}`);
+    const pre =
+      preFm !== undefined && preStripped !== undefined
+        ? { frontmatter: preFm, strippedContent: preStripped }
+        : undefined;
+    result = await compileMdx(
+      content,
+      filePath,
+      gitDates,
+      remarkPlugins,
+      rehypePlugins,
+      undefined,
+      pre
+    );
   } 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 });
@@ -229,6 +255,9 @@ async function build() {
     } catch {
       return;
     }
+    // Cache the original content so the page loop does not re-read the file
+    // (one disk read per file — the frontmatter is parsed once here too).
+    registerPageContent(`/${file.path}`, raw);
     let content = raw;
     if (builder) {
       const relPath = file.absPath.replace(PROJECT_ROOT + "/", "");
@@ -237,7 +266,12 @@ async function build() {
     }
     const remarkPlugins = builder?.collectRemarkPlugins();
     const rehypePlugins = builder?.collectRehypePlugins();
-    mdxSources[file.path] = await compileMdxModule(content, remarkPlugins, rehypePlugins);
+    mdxSources[file.path] = await compileMdxModule(
+      content,
+      remarkPlugins,
+      rehypePlugins,
+      `/${file.path}`
+    );
   });
   await Promise.all(prePassTasks);
 
@@ -307,12 +341,14 @@ async function build() {
       }
     }
 
-    let rawMdx: string;
-    try {
-      rawMdx = await readFile(file.absPath, "utf-8");
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-      continue;
+    let rawMdx = getPageContent(`/${file.path}`);
+    if (rawMdx === undefined) {
+      try {
+        rawMdx = await readFile(file.absPath, "utf-8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+        continue;
+      }
     }
 
     if (rebuildDecision === "hash_check") {
@@ -440,8 +476,11 @@ async function build() {
 
   logger.indexStart();
   t = performance.now();
-  const indexCount = await generateSearchIndex();
-  logger.indexDone(indexCount, Math.round(performance.now() - t));
+  // No content changed (all pages cached) → the aggregated index is
+  // unchanged too; reuse the existing file instead of regenerating it.
+  const indexSkipped = built === 0 && existsSync(join(ASSETS_DIR, "search-index.json"));
+  const indexCount = indexSkipped ? 0 : await generateSearchIndex();
+  logger.indexDone(indexCount, Math.round(performance.now() - t), indexSkipped);
 
   logger.routes();
   console.log("");

package/.docu/node/logger.ts

@@ -179,9 +179,13 @@ export const logger = {
     this.spinner.start("Generating search index...");
   },
 
-  indexDone(records: number, ms: number) {
-    if (guard("info", "index_done", { records, duration_ms: ms })) return;
-    this.spinner.stop(`Search index generated ${c.dim}(${records} records, ${ms}ms)${c.reset}`);
+  indexDone(records: number, ms: number, skipped = false) {
+    if (guard("info", "index_done", { records, duration_ms: ms, skipped })) return;
+    this.spinner.stop(
+      skipped
+        ? `Search index cached ${c.dim}(${ms}ms)${c.reset}`
+        : `Search index generated ${c.dim}(${records} records, ${ms}ms)${c.reset}`
+    );
   },
 
   routes() {

package/.docu/node/mdx.ts

@@ -115,13 +115,19 @@ export interface MdxResult {
  * DocuBook frontmatter contract — single source of truth for frontmatter
  * fields. Add new properties here; types and validation derive from it.
  * YAML coerces unquoted values, so string fields use `z.coerce.*`.
+ * `.passthrough()` keeps unknown fields (e.g. `author: wildan`, `tags`)
+ * in the parsed output — arbitrary frontmatter metadata stays available
+ * via `frontmatterField(frontmatter, key)` instead of being silently
+ * stripped by Zod's default object parsing.
  */
-export const frontmatterSchema = z.object({
-  title: z.coerce.string().optional(),
-  description: z.coerce.string().optional(),
-  image: z.coerce.string().optional(),
-  date: z.coerce.string().optional(),
-});
+export const frontmatterSchema = z
+  .object({
+    title: z.coerce.string().optional(),
+    description: z.coerce.string().optional(),
+    image: z.coerce.string().optional(),
+    date: z.coerce.string().optional(),
+  })
+  .passthrough();
 
 export type Frontmatter = z.infer<typeof frontmatterSchema>;
 
@@ -162,12 +168,13 @@ async function serializeWithDocPlugins(
     remarkPlugins?: Pluggable[];
     rehypePlugins?: Pluggable[];
     frontmatterSchema?: FrontmatterSchema;
-  } = {}
+  } = {},
+  pre?: { frontmatter: Frontmatter; strippedContent: string }
 ) {
-  const { strippedContent } = extractFrontmatterWithContent<Frontmatter>(
-    rawMdx,
-    opts.frontmatterSchema
-  );
+  // Parse-once: when the prePass already extracted the frontmatter + stripped
+  // content, reuse it instead of re-parsing (the SSR phase skips extraction).
+  const { strippedContent, frontmatter } =
+    pre ?? extractFrontmatterWithContent<Frontmatter>(rawMdx, opts.frontmatterSchema);
 
   const defaultRemark = createDefaultRemarkPlugins();
   const defaultRehype = createDefaultRehypePlugins();
@@ -179,7 +186,8 @@ async function serializeWithDocPlugins(
   const finalRehype = [...defaultRehype, rehypeDocsHtmlLinks, ...(opts.rehypePlugins ?? [])];
 
   // v2 contract: plain markdown + directives only — authored JSX tags are
-  // not parsed (dropped, content kept as text).
+  // not parsed (dropped, content kept as text). Return the frontmatter parsed
+  // above — `serialize()` only parses it when `parseFrontmatter` is set.
   return serialize(strippedContent, {
     outputFormat: opts.outputFormat,
     format: "md",
@@ -187,7 +195,7 @@ async function serializeWithDocPlugins(
       rehypePlugins: finalRehype,
       remarkPlugins: finalRemark,
     },
-  });
+  }).then((serialized) => ({ ...serialized, frontmatter, strippedContent }));
 }
 
 /**
@@ -206,15 +214,19 @@ export async function compileMdx(
   gitDates?: Map<string, string>,
   remarkPlugins?: Pluggable[],
   rehypePlugins?: Pluggable[],
-  frontmatterSchema?: FrontmatterSchema
+  frontmatterSchema?: FrontmatterSchema,
+  /** 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 } = extractFrontmatterWithContent<Frontmatter>(rawMdx, frontmatterSchema);
-  const serialized = await serializeWithDocPlugins(rawMdx, {
-    remarkPlugins,
-    rehypePlugins,
-    frontmatterSchema,
-  });
+  const frontmatter =
+    pre?.frontmatter ??
+    extractFrontmatterWithContent<Frontmatter>(rawMdx, frontmatterSchema).frontmatter;
+  const serialized = await serializeWithDocPlugins(
+    rawMdx,
+    { remarkPlugins, rehypePlugins, frontmatterSchema },
+    pre
+  );
 
   const components = createMdxComponents();
   const content = React.createElement(MDXRemote, {
@@ -245,15 +257,69 @@ export async function compileMdx(
  * instead of `new Function(compiledSource)`. Uses the same plugin chain as
  * `compileMdx` so the hydrated tree matches the SSR output.
  */
+/**
+ * Frontmatter records collected once during compilation — pagination title /
+ * description and other metadata consumers read from here instead of
+ * re-reading + re-parsing files (parse-once contract: the frontmatter is
+ * already parsed by `serializeWithDocPlugins`).
+ */
+const pageFrontmatter = new Map<string, Frontmatter>();
+
+/** Register a page's frontmatter, keyed by its href. */
+export function registerPageFrontmatter(href: string, frontmatter: Frontmatter): void {
+  pageFrontmatter.set(href, frontmatter);
+}
+
+/** Look up a page's frontmatter (undefined when not yet compiled). */
+export function getPageFrontmatter(href: string): Frontmatter | undefined {
+  return pageFrontmatter.get(href);
+}
+
+/**
+ * Frontmatter-stripped content from the prePass — lets the SSR compile
+ * phase skip its own `extractFrontmatterWithContent` (parse-once across
+ * both compile phases).
+ */
+const pageStripped = new Map<string, string>();
+
+export function registerPageStripped(href: string, stripped: string): void {
+  pageStripped.set(href, stripped);
+}
+
+export function getPageStripped(href: string): string | undefined {
+  return pageStripped.get(href);
+}
+
+/**
+ * Original (pre-transform) file content, cached during the prePass so the
+ * page loop does not re-read the file from disk — one read per file.
+ */
+const pageContent = new Map<string, string>();
+
+export function registerPageContent(href: string, raw: string): void {
+  pageContent.set(href, raw);
+}
+
+export function getPageContent(href: string): string | undefined {
+  return pageContent.get(href);
+}
+
 export async function compileMdxModule(
   rawMdx: string,
   remarkPlugins?: Pluggable[],
-  rehypePlugins?: Pluggable[]
+  rehypePlugins?: Pluggable[],
+  /** Page href — registers the frontmatter (title/description/image/date)
+   * once for pagination and metadata consumers. */
+  href?: string
 ): Promise<string> {
   const serialized = await serializeWithDocPlugins(rawMdx, {
     outputFormat: "program",
     remarkPlugins,
     rehypePlugins,
   });
+  if (href) {
+    registerPageFrontmatter(href, serialized.frontmatter as Frontmatter);
+    registerPageStripped(href, serialized.strippedContent);
+  }
   return serialized.compiledSource;
 }

package/.docu/node/route.ts

@@ -5,6 +5,7 @@ import { DOCS_DIR } from "./paths";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { extractFrontmatter } from "@docubook/core";
+import { getPageFrontmatter, registerPageFrontmatter } from "./mdx";
 import type { Frontmatter } from "./mdx";
 
 const docuConfig = loadDocuConfig();
@@ -46,29 +47,31 @@ export function getRouteMap(): Map<string, string> {
   return map;
 }
 
-/** Build-time cache of href → frontmatter description (docs content is static). */
-const descriptionCache = new Map<string, string>();
-
-function readDescription(href: string): string {
-  const cached = descriptionCache.get(href);
-  if (cached !== undefined) return cached;
-
-  let description = "";
+/**
+ * Frontmatter for a page — read from the parse-once registry (populated
+ * during compilation) instead of re-reading + re-parsing the file. Falls
+ * back to a direct read only for pages the dev server has not compiled yet,
+ * and caches the result back into the registry.
+ */
+function readPageFrontmatter(href: string): Frontmatter {
+  const registered = getPageFrontmatter(href);
+  if (registered) return registered;
+
+  let fm: Frontmatter = {};
   const rel = href.replace(/^\/|$/g, "");
   for (const ext of [".mdx", ".md"]) {
     for (const file of [join(DOCS_DIR, `${rel}${ext}`), join(DOCS_DIR, `${rel}/index${ext}`)]) {
       try {
-        const fm = extractFrontmatter<Frontmatter>(readFileSync(file, "utf-8"));
-        description = typeof fm.description === "string" ? fm.description : "";
-        if (description) break;
+        fm = extractFrontmatter<Frontmatter>(readFileSync(file, "utf-8"));
+        break;
       } catch {
         // not this file — try the next candidate
       }
     }
-    if (description) break;
+    if (Object.keys(fm).length) break;
   }
-  descriptionCache.set(href, description);
-  return description;
+  registerPageFrontmatter(href, fm);
+  return fm;
 }
 
 export function getPreviousNext(pathname: string) {
@@ -83,12 +86,13 @@ 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: routeMap.get(first) || "",
-        description: readDescription(first),
+        title: fm.title || routeMap.get(first) || "",
+        description: fm.description || "",
       },
     };
   }
@@ -105,13 +109,17 @@ 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: routeMap.get(prevHref) || "" } : null,
+    prev: prevHref
+      ? { href: prevHref, title: prevFm?.title || routeMap.get(prevHref) || "" }
+      : null,
     next: nextHref
       ? {
           href: nextHref,
-          title: routeMap.get(nextHref) || "",
-          description: readDescription(nextHref),
+          title: nextFm?.title || routeMap.get(nextHref) || "",
+          description: nextFm?.description || "",
         }
       : null,
   };

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

@@ -13,6 +13,7 @@
 
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
+import { getPageContent } from "./mdx";
 import { extractFrontmatterWithContent } from "@docubook/core";
 import { frontmatterField } from "./mdx";
 import { DOCS_DIR, ASSETS_DIR, loadDocuConfig } from "./paths";
@@ -193,7 +194,9 @@ export async function generateSearchIndex(docsDir?: string, outputDir?: string):
   const mdxFiles = await scanMdxFiles(docs);
   const results = await Promise.all(
     mdxFiles.map(async (file) => {
-      const raw = await readFile(file.absPath, "utf-8");
+      // Parse-once: reuse the prePass-cached raw content when available —
+      // no second disk read of every file.
+      const raw = getPageContent(`/${file.path}`) ?? (await readFile(file.absPath, "utf-8"));
       return extractRecords(file.path, raw);
     })
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-beta.0",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -56,10 +56,10 @@
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
     "zod": "^4.4.3",
-    "@docubook/markdown": "^2.0.0-alpha.2",
-    "@docubook/ui-react": "^2.0.0-alpha.2",
-    "@docubook/themes-colors": "^2.0.0-alpha.2",
-    "@docubook/core": "^2.0.0-alpha.2"
+    "@docubook/core": "^2.0.0-beta.0",
+    "@docubook/markdown": "^2.0.0-beta.0",
+    "@docubook/themes-colors": "^2.0.0-beta.0",
+    "@docubook/ui-react": "^2.0.0-beta.0"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"