@docubook/flame 2.0.0-alpha.0 → 2.0.0-alpha.1

package/.docu/components/Pagination.tsx

@@ -29,7 +29,15 @@ export default function Pagination({
   return (
     <PaginationDocs
       prev={prev ? { href: docsHtmlHref(`/docs${prev.href}`), title: prev.title } : undefined}
-      next={next ? { href: docsHtmlHref(`/docs${next.href}`), title: next.title } : undefined}
+      next={
+        next
+          ? {
+              href: docsHtmlHref(`/docs${next.href}`),
+              title: next.title,
+              description: next.description,
+            }
+          : undefined
+      }
       className={className}
       prevIcon={prevIcon}
       nextIcon={nextIcon}

package/.docu/components/Toc.tsx

@@ -25,12 +25,12 @@ export default function Toc({ tocs }: TocProps) {
   // CSS scroll-margin-top (prose-headings:scroll-mt-4 desktop /
   // scroll-mt-16 mobile) so a change in one place updates both, and the
   // heading lands exactly where the browser would put a native anchor jump.
-  function getAnchorOffset(): number {
+  const getAnchorOffset = useCallback((): number => {
     if (typeof window === "undefined") return 100;
     const first = tocs[0] ? document.getElementById(tocs[0].href.slice(1)) : null;
     const margin = first ? parseFloat(getComputedStyle(first).scrollMarginTop) : 0;
     return margin || 100;
-  }
+  }, [tocs]);
 
   useEffect(() => {
     // Desktop-only TOC — on mobile this island is display:none but still
@@ -88,7 +88,7 @@ export default function Toc({ tocs }: TocProps) {
       scrollTarget.removeEventListener("scroll", listener);
       if (throttleTimer) clearTimeout(throttleTimer);
     };
-  }, [tocs]);
+  }, [tocs, getAnchorOffset]);
 
   const handleLinkClick = useCallback((id: string) => {
     clickedIdRef.current = id;

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

@@ -1,9 +1,9 @@
 import {
   runBuildCli
-} from "./chunk-2EYRWRDP.js";
-import "./chunk-QPF4DPZQ.js";
+} from "./chunk-MQWWCO6O.js";
+import "./chunk-TRT6WQZG.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/build.deno.ts

package/.docu/lib/{build.impl-WR24HDUT.js → build.impl-VXB4KL4D.js}

@@ -1,10 +1,10 @@
 import {
   runBuild,
   runBuildCli
-} from "./chunk-2EYRWRDP.js";
-import "./chunk-QPF4DPZQ.js";
+} from "./chunk-MQWWCO6O.js";
+import "./chunk-TRT6WQZG.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 export {
   runBuild,

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

@@ -1,9 +1,9 @@
 import {
   runBuildCli
-} from "./chunk-2EYRWRDP.js";
-import "./chunk-QPF4DPZQ.js";
+} from "./chunk-MQWWCO6O.js";
+import "./chunk-TRT6WQZG.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/build.node.ts

package/.docu/lib/{chunk-X7KPVCDN.js → chunk-7PRQ3RQB.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-WR24HDUT.js");
+  const { runBuildCli } = await import("./build.impl-VXB4KL4D.js");
   await runBuildCli();
 }
 async function writeDockerFiles() {

package/.docu/lib/{chunk-VPV7KP7K.js → chunk-A6FIEG3H.js}

@@ -15,7 +15,7 @@ import {
   htmlShell,
   initSentry,
   loadPlugins
-} from "./chunk-QPF4DPZQ.js";
+} from "./chunk-TRT6WQZG.js";
 import {
   SECURITY_HEADERS,
   generateNonce,
@@ -28,7 +28,7 @@ import {
 } from "./chunk-EOK6KATZ.js";
 import {
   logger
-} from "./chunk-AJV2GEDF.js";
+} from "./chunk-JRERMREW.js";
 import {
   DIST_DIR,
   DOCS_DIR,
@@ -60,7 +60,11 @@ function createHtmlResponse(title, description, body, status, state, depth = 0)
     nonce,
     extraScripts: hmrScript(nonce),
     themeCss: state.inlineThemeCss,
-    depth
+    depth,
+    // 404 pages can be requested at arbitrary depths (e.g. a noLink section
+    // path typed in the address bar) — relative asset paths would resolve
+    // against the wrong directory and break CSS/JS.
+    absoluteAssets: status === 404
   });
   return htmlResponse(html, nonce, status, true);
 }

package/.docu/lib/{chunk-AJV2GEDF.js → chunk-JRERMREW.js}

@@ -5,7 +5,7 @@ import {
 // package.json
 var package_default = {
   name: "@docubook/flame",
-  version: "2.0.0-alpha.0",
+  version: "2.0.0-alpha.1",
   description: "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   type: "module",
   bin: {

package/.docu/lib/{chunk-KEWRVASF.js → chunk-LZDEWK25.js}

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

package/.docu/lib/{chunk-2EYRWRDP.js → chunk-MQWWCO6O.js}

@@ -15,7 +15,7 @@ import {
   htmlShell,
   initSentry,
   loadPlugins
-} from "./chunk-QPF4DPZQ.js";
+} from "./chunk-TRT6WQZG.js";
 import {
   cspHeader,
   generateNonce,
@@ -23,7 +23,7 @@ import {
 } from "./chunk-EOK6KATZ.js";
 import {
   logger
-} from "./chunk-AJV2GEDF.js";
+} from "./chunk-JRERMREW.js";
 import {
   ASSETS_DIR,
   CACHE_FILE,
@@ -398,7 +398,10 @@ async function runBuild() {
     css: assetManifest.css,
     js: assetManifest.js,
     nonce: notFoundNonce,
-    themeCss: inlineThemeCss
+    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.
+    absoluteAssets: true
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
   logger.spinner.stop(

package/.docu/lib/{chunk-QPF4DPZQ.js → chunk-TRT6WQZG.js}

@@ -1333,6 +1333,9 @@ function DocsBreadcrumb({ paths }) {
 }
 
 // .docu/node/route.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+import { extractFrontmatter } from "@docubook/core";
 var docuConfig2 = loadDocuConfig();
 var routes = resolveRoutes(docuConfig2.routes);
 function flattenRoutes() {
@@ -1361,8 +1364,42 @@ 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 = "";
+  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;
+      } catch {
+      }
+    }
+    if (description) break;
+  }
+  descriptionCache.set(href, description);
+  return description;
+}
 function getPreviousNext(pathname) {
   const normalizedPath = pathname.replace(/^\/|$/g, "");
+  if (normalizedPath === "docs" || normalizedPath === "") {
+    const paths2 = flattenRoutes();
+    const routeMap2 = getRouteMap();
+    const first = paths2[0];
+    if (!first) return { prev: null, next: null };
+    return {
+      prev: null,
+      next: {
+        href: first,
+        title: routeMap2.get(first) || "",
+        description: readDescription(first)
+      }
+    };
+  }
   const paths = flattenRoutes();
   const index = paths.findIndex((href) => href === `/${normalizedPath}` || href === normalizedPath);
   if (index === -1) {
@@ -1373,7 +1410,11 @@ function getPreviousNext(pathname) {
   const nextHref = index < paths.length - 1 ? paths[index + 1] : null;
   return {
     prev: prevHref ? { href: prevHref, title: routeMap.get(prevHref) || "" } : null,
-    next: nextHref ? { href: nextHref, title: routeMap.get(nextHref) || "" } : null
+    next: nextHref ? {
+      href: nextHref,
+      title: routeMap.get(nextHref) || "",
+      description: readDescription(nextHref)
+    } : null
   };
 }
 
@@ -1395,7 +1436,11 @@ function Pagination({
     PaginationDocs,
     {
       prev: prev ? { href: docsHtmlHref(`/docs${prev.href}`), title: prev.title } : void 0,
-      next: next ? { href: docsHtmlHref(`/docs${next.href}`), title: next.title } : void 0,
+      next: next ? {
+        href: docsHtmlHref(`/docs${next.href}`),
+        title: next.title,
+        description: next.description
+      } : void 0,
       className,
       prevIcon,
       nextIcon,
@@ -1671,12 +1716,12 @@ function Toc({ tocs }) {
   useEffect2(() => {
     activeIdRef.current = activeId;
   }, [activeId]);
-  function getAnchorOffset() {
+  const getAnchorOffset = useCallback2(() => {
     if (typeof window === "undefined") return 100;
     const first = tocs[0] ? document.getElementById(tocs[0].href.slice(1)) : null;
     const margin = first ? parseFloat(getComputedStyle(first).scrollMarginTop) : 0;
     return margin || 100;
-  }
+  }, [tocs]);
   useEffect2(() => {
     if (typeof window === "undefined" || window.innerWidth < 1024) return;
     if (!tocs.length) return;
@@ -1717,7 +1762,7 @@ function Toc({ tocs }) {
       scrollTarget.removeEventListener("scroll", listener);
       if (throttleTimer) clearTimeout(throttleTimer);
     };
-  }, [tocs]);
+  }, [tocs, getAnchorOffset]);
   const handleLinkClick = useCallback2((id) => {
     clickedIdRef.current = id;
     setActiveId(id);
@@ -2475,7 +2520,8 @@ function htmlShell(opts) {
     themeCss,
     depth = 0,
     headExtra,
-    bodyExtra
+    bodyExtra,
+    absoluteAssets = false
   } = opts;
   const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const themeStyle = themeCss ? `
@@ -2485,8 +2531,8 @@ function htmlShell(opts) {
   const bodyInjection = bodyExtra?.length ? `
   ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = depthPrefix + "assets/";
-  const resolvePath = (path) => path.startsWith("/") ? depthPrefix + path.slice(1) : path;
+  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const resolvePath = (path) => absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
   let seoTags = "";
   if (opts.seo) {
     const s = opts.seo;

package/.docu/lib/clean.js

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

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

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

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

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

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

@@ -1,11 +1,11 @@
 import {
   runPreview
-} from "./chunk-KEWRVASF.js";
+} from "./chunk-LZDEWK25.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.deno.ts

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

@@ -1,11 +1,11 @@
 import {
   runPreview
-} from "./chunk-KEWRVASF.js";
+} from "./chunk-LZDEWK25.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/preview.node.ts

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

@@ -1,12 +1,12 @@
 import {
   runServer
-} from "./chunk-VPV7KP7K.js";
-import "./chunk-QPF4DPZQ.js";
+} from "./chunk-A6FIEG3H.js";
+import "./chunk-TRT6WQZG.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.deno.ts

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

@@ -1,12 +1,12 @@
 import {
   runServer
-} from "./chunk-VPV7KP7K.js";
-import "./chunk-QPF4DPZQ.js";
+} from "./chunk-A6FIEG3H.js";
+import "./chunk-TRT6WQZG.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-JRERMREW.js";
 import "./chunk-4IQXHHPF.js";
 
 // .docu/node/server.node.ts

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

@@ -436,6 +436,9 @@ export async function runBuild(): Promise<void> {
     js: assetManifest.js,
     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.
+    absoluteAssets: true,
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 

package/.docu/node/build.ts

@@ -418,6 +418,9 @@ async function build() {
     js: assetManifest.js,
     nonce: generateNonce(),
     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.
+    absoluteAssets: true,
   });
   await writeFile(join(DIST_DIR, "404.html"), notFoundHtml);
 

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

@@ -34,6 +34,9 @@ export interface HtmlShellOptions {
   bodyExtra?: string[];
   /** SEO meta tags derived from config + frontmatter */
   seo?: SeoMeta;
+  /** Root-absolute asset URLs (`/assets/...`). Required for pages served at
+   * arbitrary paths (404 fallback) — relative depth is wrong there. */
+  absoluteAssets?: boolean;
 }
 
 export function htmlShell(opts: HtmlShellOptions): string {
@@ -51,14 +54,16 @@ export function htmlShell(opts: HtmlShellOptions): string {
     depth = 0,
     headExtra,
     bodyExtra,
+    absoluteAssets = false,
   } = opts;
   const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const themeStyle = themeCss ? `\n  <style${nonceAttr}>${escapeHtml(themeCss)}</style>` : "";
   const headInjection = headExtra?.length ? `\n  ${headExtra.join("\n  ")}` : "";
   const bodyInjection = bodyExtra?.length ? `\n  ${bodyExtra.join("\n  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = depthPrefix + "assets/";
-  const resolvePath = (path: string) => (path.startsWith("/") ? depthPrefix + path.slice(1) : path);
+  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const resolvePath = (path: string) =>
+    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

package/.docu/node/html.ts

@@ -16,14 +16,16 @@ export function htmlShell(opts: HtmlShellOptions): string {
     depth = 0,
     headExtra,
     bodyExtra,
+    absoluteAssets = false,
   } = 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  ")}` : "";
   const depthPrefix = depth === 0 ? "" : "../".repeat(depth);
-  const assetPrefix = depthPrefix + "assets/";
-  const resolvePath = (path: string) => (path.startsWith("/") ? depthPrefix + path.slice(1) : path);
+  const assetPrefix = absoluteAssets ? "/assets/" : depthPrefix + "assets/";
+  const resolvePath = (path: string) =>
+    absoluteAssets ? path : path.startsWith("/") ? depthPrefix + path.slice(1) : path;
 
   // Build SEO meta tags (OG, Twitter, canonical)
   let seoTags = "";

package/.docu/node/route.ts

@@ -1,6 +1,11 @@
 import { loadDocuConfig } from "./paths";
 import type { DocuRoute } from "./types";
 import { resolveRoutes } from "./fs-scanner";
+import { DOCS_DIR } from "./paths";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractFrontmatter } from "@docubook/core";
+import type { Frontmatter } from "./mdx";
 
 const docuConfig = loadDocuConfig();
 export const routes: DocuRoute[] = resolveRoutes(docuConfig.routes);
@@ -41,8 +46,53 @@ 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 = "";
+  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;
+      } catch {
+        // not this file — try the next candidate
+      }
+    }
+    if (description) break;
+  }
+  descriptionCache.set(href, description);
+  return description;
+}
+
 export function getPreviousNext(pathname: string) {
   const normalizedPath = pathname.replace(/^\/|$/g, "");
+
+  // Docs index (/docs — DocsPage renders with pathname "" from slug []):
+  // next-only navigation into the first docs page — never read the route
+  // backward from the index, so prev stays null even if a page sits before
+  // it in the route list.
+  if (normalizedPath === "docs" || normalizedPath === "") {
+    const paths = flattenRoutes();
+    const routeMap = getRouteMap();
+    const first = paths[0];
+    if (!first) return { prev: null, next: null };
+    return {
+      prev: null,
+      next: {
+        href: first,
+        title: routeMap.get(first) || "",
+        description: readDescription(first),
+      },
+    };
+  }
+
   const paths = flattenRoutes();
 
   const index = paths.findIndex((href) => href === `/${normalizedPath}` || href === normalizedPath);
@@ -57,7 +107,13 @@ export function getPreviousNext(pathname: string) {
 
   return {
     prev: prevHref ? { href: prevHref, title: routeMap.get(prevHref) || "" } : null,
-    next: nextHref ? { href: nextHref, title: routeMap.get(nextHref) || "" } : null,
+    next: nextHref
+      ? {
+          href: nextHref,
+          title: routeMap.get(nextHref) || "",
+          description: readDescription(nextHref),
+        }
+      : null,
   };
 }
 

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

@@ -44,6 +44,10 @@ function createHtmlResponse(
     extraScripts: hmrScript(nonce),
     themeCss: state.inlineThemeCss,
     depth,
+    // 404 pages can be requested at arbitrary depths (e.g. a noLink section
+    // path typed in the address bar) — relative asset paths would resolve
+    // against the wrong directory and break CSS/JS.
+    absoluteAssets: status === 404,
   });
   /** Dev-only: serves compiledSource → MDXRemote eval path (no CSP in production). */
   return htmlResponse(html, nonce, status, true);

package/.docu/styles/globals.css

@@ -9,6 +9,15 @@
 @plugin "@tailwindcss/typography";
 @source "../../.docu/components";
 @source "../../.docu/pages";
+@source "../../../ui-react/src";
+
+/* daisyUI breadcrumbs underline every li child on hover (including plain
+   spans) — crumbs are not links, so strip the underline (and pointer cursor)
+   for non-anchor items; real anchors keep daisyUI's hover feedback. */
+.breadcrumbs > ul > li > :not(a):hover {
+  text-decoration-line: none;
+  cursor: default;
+}
 @source inline(
   "breadcrumbs collapse collapse-open collapse-close collapse-arrow collapse-plus collapse-title collapse-content"
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.1",
   "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/core": "^2.0.0-alpha.0",
-    "@docubook/themes-colors": "^2.0.0-alpha.0",
-    "@docubook/ui-react": "^2.0.0-alpha.0",
-    "@docubook/markdown": "^2.0.0-alpha.0"
+    "@docubook/core": "^2.0.0-alpha.1",
+    "@docubook/markdown": "^2.0.0-alpha.1",
+    "@docubook/themes-colors": "^2.0.0-alpha.1",
+    "@docubook/ui-react": "^2.0.0-alpha.1"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"

package/template/README.md

@@ -42,7 +42,7 @@ deno task dev
 
 ## Documentation
 
-For the full documentation, please visit **[packages/flame/docs](https://github.com/DocuBook/docubook/tree/main/packages/flame/docs)** or read the official site [docubook.pro](https://docubook.pro)
+For the full documentation, visit **[www.docubook.pro](https://www.docubook.pro/)**
 
 ---
 

package/template/docs/getting-started/configuration.mdx

@@ -3,16 +3,28 @@ title: Configuration
 description: docu.json reference — meta, navbar, themes, routes, and plugins.
 ---
 
-`docu.json` in your project root controls the site. Key sections:
+`docu.json` in the project root controls the whole site. It is validated against `docu.schema.json`.
+
+## First edits
+
+| What | Where |
+|---|---|
+| Site name & tagline | `meta.title`, `meta.description` |
+| Brand in the header | `navbar.logoText` |
+| Landing copy | `home.hero` — headline, description, actions |
+| Colour preset | `themes.colors` — `default`, `freshlime`, `coffee` |
+| Footer links | `footer.social` |
+
+## Reference
 
 | Field | Description |
 |---|---|
 | `meta` | Site title, description, favicon, base URL |
 | `navbar` | Logo, navigation menu links |
-| `home.hero` | Landing page hero with tagline, headline, actions |
-| `home.features` | Feature cards with icon, title, description |
+| `home.hero` | Landing page hero — tagline, headline, actions |
+| `home.features` | Feature cards — icon, title, description |
 | `routes` | Sidebar navigation (auto-detected from `docs/` when empty) |
 | `themes` | Colour preset or custom palette |
 | `plugins` | Build/dev pipeline extensions |
 
-See this site's `docu.json` for a complete example, or refer to `docu.schema.json` in the package root.
+This project's `docu.json` is a complete working example — edit it and the dev server applies the changes live.

package/template/docs/getting-started/overview.mdx

@@ -1,50 +1,42 @@
 ---
 title: Quick Start
-description: Get your first documentation site running on Bun, Node.js, or Deno.
+description: The Flame workflow — dev server, first edit, authoring, and build.
 ---
 
-## Prerequisites
-
-Choose **one** runtime:
-
-- **Bun** >= 1.1: `curl -fsSL https://bun.sh/install | bash`
-- **Node.js** >= 20.11: [nodejs.org](https://nodejs.org)
-- **Deno** >= 2.x: `curl -fsSL https://deno.land/install.sh | sh`
-
-## Create a project
-
-<Tabs>
-  <Tab title="Bun">
-    ```bash
-    mkdir my-docs && cd my-docs
-    bun add @docubook/flame
-    bunx flame init
-    bun run dev
-    ```
-  </Tab>
-  <Tab title="Node.js">
-    ```bash
-    mkdir my-docs && cd my-docs
-    npm install @docubook/flame
-    npx flame init
-    npm run dev
-    ```
-  </Tab>
-  <Tab title="Deno">
-    ```bash
-    mkdir my-docs && cd my-docs
-    deno run -A npm:@docubook/flame init
-    deno task dev
-    ```
-  </Tab>
-</Tabs>
-
-Open http://localhost:3000 — changes to `docs/` or `docu.json` hot-reload.
-
-## Build for production
+Your Flame project is ready — this is the workflow to make it yours.
+
+## 1. Run the dev server
+
+```bash
+bun run dev        # or: npm run dev / deno task dev
+```
+
+Open http://localhost:3000 — edits to `docs/` and `docu.json` hot-reload instantly.
+
+## 2. Make your first edit
+
+Open `docs/getting-started/overview.mdx` (this file):
+
+1. Change `title` and `description` in the frontmatter — the browser updates live
+2. Add a heading below and save
+3. New pages appear in the sidebar and search automatically
+
+## 3. Author with directives
+
+Content is plain markdown — components are directives, no JSX:
+
+```md
+:::tip
+A callout — no JSX needed.
+:::
+```
+
+See [Components](/docs/guide/components) for the full directive set.
+
+## 4. Build for production
 
 ```bash
-npm run build     # or: bun run build / deno task build
+bun run build      # or: npm run build / deno task build
 ```
 
-Static output goes to `.docu/dist/` — deploy to any CDN or static host.
+Flat static HTML lands in `.docu/dist/` — deploy anywhere ([Deployment](/docs/guide/deployment)).

package/template/docs/guide/components.mdx

@@ -1,256 +1,74 @@
 ---
 title: Components
-description: Built-in MDX components available in DocuBook Flame.
-date: 2026-05-25
+description: The directive syntax for built-in components — callouts, tabs, cards, code blocks, and more.
 ---
 
-DocuBook Flame includes pre-built MDX components you can use directly in your docs.
+Components are **directives**, not JSX — content stays plain markdown. A few to get you started; the full reference lives at [docubook.pro/docs/components](https://www.docubook.pro/docs/components/accordion).
 
-> For full documentation and live examples, visit [docubook.pro/docs/components](https://www.docubook.pro/docs/components/accordion).
+## Callout
 
-## Note
-
-Display messages with different severity levels.
-
-```jsx:filename.mdx
-<Note type="tip" title="Tip">
-  This is a tip to suggests a helpful.
-</Note>
-<Note type="info" title="Info">
-  This is a general note to convey information to the user.
-</Note>
-<Note type="danger" title="Danger">
-  This is a danger alert to notify the user of a critical issue.
-</Note>
-<Note type="warning">
-  This note uses default title and default icon from its type.
-</Note>
-<Note type="success" title="Success">
-  This is a success message to inform the user of successful actions.
-</Note>
-```
-
-## Tabs
-
-Organize content into switchable sections.
-
-````jsx:filename.mdx
-<Tabs className="pt-5 pb-1">
-  <Tab title="Java">
-    ```java:HelloWorld.java
-    // HelloWorld.java
-    public class HelloWorld {
-        public static void main(String[] args) {
-            System.out.println("Hello, World!");
-        }
-    }
-    ```
-  </Tab>
-  <Tab title="TypeScript">
-    ```typescript:helloWorld.ts
-    // helloWorld.ts
-    function helloWorld(): void {
-        console.log("Hello, World!");
-    }
-    helloWorld();
-    ```
-  </Tab>
-</Tabs>
-````
-
-## Card
-
-Display content in a compact card layout.
-
-```jsx:filename.mdx
-<Card title="Card with Link and icon" icon="Link" href="/docs/components/card-group">
-  This is how you use a card with an icon and a link. Clicking on this card
-  brings you to the Card Group page.
-</Card>
+```md
+:::tip{title="Optional title"}
+Callout content.
+:::
 ```
 
-## Card Group
+Variants: `tip`, `info`, `warning`, `danger`, `success`.
 
-Group multiple cards in a grid.
+## Code block with title
 
-```jsx:filename.mdx
-<Cards cols={2}>
-  <Card title="Heading 1" icon="Heading1">
-    This is an example of card content with columns.
-  </Card>
-  <Card title="Heading 2" icon="Heading2">
-    This is an example of card content with columns.
-  </Card>
-  <Card title="Grid Card" icon="Grid" horizontal>
-      This is a horizontal card layout.
-  </Card>
-  <Card title="Horizontal Card" icon="Layout" horizontal>
-      This is a horizontal card layout.
-  </Card>
-</Cards>
+````md
+```javascript:app.js showLineNumbers {2-3}
+const docs = "markdown";
+console.log(docs);
 ```
-
-## Accordion
-
-````markdown:filename.mdx
-<Accordions>
-<Accordion title="Basic Usage">
-    This accordion includes a [Lucide Icon](https://lucide.dev/icons/) because the `icon` prop is provided.
-</Accordion>
-
-<Accordion title="With icon props" icon="MousePointerClick">
-    This accordion includes a Lucide icon because the `icon` prop is provided.
-</Accordion>
-
-<Accordion title="With Code Block">
-    You can put other components inside Accordions.
-```jsx:helloword.jsx
-class HelloWorld {
-public static void main(String[] args) {
-        System.out.println("Hello, World!");
-        }
-}
-```
-</Accordion>
-</Accordions>
 ````
 
-## Steps / Stepper
-
-Display step-by-step instructions.
-
-````jsx:filename.mdx
-<Steps>
-  <Step title="Step 1: Clone the DocuBook Repository">
-    ```bash
-    git clone https://github.com/DocuBook/docubook.git
-    ```
-  </Step>
-  <Step title="Step 2: Access the Project Directory">
-    ```bash
-    cd docubook
-    ```
-  </Step>
-  <Step title="Step 3: Install Required Dependencies">
-    ```bash
-    pnpm install
-    ```
-  </Step>
-</Steps>
-````
-
-## Button
-
-Styled buttons with icons.
-
-```jsx
-<Button
-  text="Learn More"
-  href="https://example.com"
-  icon="MoveUpRight"
-  size="md"
-  variant="secondary"
-  target="_blank"
-/>
-```
-
-## File Tree
-
-Display hierarchical file structures.
-
-```jsx
-<Files>
-  <Folder name="src">
-    <File name="App.tsx" />
-    <File name="index.tsx" />
-    <Folder name="components">
-      <File name="Button.tsx" />
-    </Folder>
-  </Folder>
-  <File name="package.json" />
-</Files>
-```
-
-## Code Block
-
-Syntax-highlighted code with title and line highlighting.
+The `:filename` suffix adds a title bar; `showLineNumbers` and `{2-3}` enable line numbers and highlighting.
 
-````jsx
-```ts:server.ts {3-5}
-import { serve } from "bun";
+## Tabs
 
-serve({
-  port: 3000,
-  fetch: () => new Response("Hello!"),
-});
-```
+````md
+::::tabs
+:::tab{title="Bun"}
+bun run dev
+:::
+:::tab{title="Node"}
+npm run dev
+:::
+::::
 ````
 
-## Image
-
-Responsive images with optional caption.
-
-```markdown:filename.mdx
-![Alt text for the image](https://via.placeholder.com/150)
+## Card group
+
+```md
+::::cards{cols="2"}
+:::card{title="First" icon="Heading1"}
+Card content.
+:::
+:::card{title="Second" icon="Heading2"}
+Card content.
+:::
+::::
 ```
 
-## Link
-
-Styled links with external indicator.
+## Mermaid
 
-```markdown:filename.mdx
-[Visit OpenAI](https://www.openai.com)
+```mermaid
+flowchart LR
+    A --> B
 ```
 
-## Keyboard
-
-Display keyboard shortcuts.
+## Tooltip
 
-```tsx
-{/* Windows style (default) */}
-<Kbd show="ctrl" /> + <Kbd show="v" />
-
-{/* Mac style */}
-<Kbd show="cmd" type="mac" /> + <Kbd show="v" type="mac" />
+```md
+Inline :tooltip[hover me]{tip="Extra details"}.
 ```
 
-Renders as:
-- Windows: <Kbd show="ctrl" type="window" /> + <Kbd show="v" type="window" />
-- Mac: <Kbd show="cmd" type="mac" /> + <Kbd show="v" type="mac" />
-
-## Tooltips
-
-Hover tooltips for inline content.
+## Youtube
 
-```markdown:filename.mdx
-This a tooltip <Tooltip text="Hover me show on top" tip="npx @docubook/cli@latest" side="top" /> and <Tooltip text="Hover me show on bottom" tip="npx @docubook/cli@latest" side="bottom" /> thanks you.
+```md
+::youtube{videoId="OPM2t54T-Vo"}
 ```
 
-## YouTube
-
-Embed YouTube videos.
-
-```markdown:filename.mdx
-<Youtube videoId="OPM2t54T-Vo" />
-```
-
-> Usage
-> for example the youtube URL show this https://www.youtube.com/watch?v=OPM2t54T-Vo 
-> the ID is `OPM2t54T-Vo`
-
-## Release Note
-
-Display changelog entries.
-
-```markdown:filename.mdx
-<Release version="1.10.1" date="2025-05-24" title="Accessibility Improvements and Bug Fixes">
-  <Changes type="added">
-    - New feature to improve accessibility
-    - Keyboard navigation support for dialog components
-  </Changes>
-  <Changes type="fixed">
-    - Bug fix for mobile menu
-    - Fixed loading issues on documentation pages
-  </Changes>
-</Release>
-```
+> All directives render server-side to static HTML — no runtime JavaScript unless the component needs it.

package/template/docs/guide/routing.mdx

@@ -1,9 +1,9 @@
 ---
 title: Routing
-description: How Flame maps MDX files to static HTML pages.
+description: How Flame maps markdown files to static pages.
 ---
 
-Flame uses **filesystem-based routing** — every `.mdx` file in `docs/` compiles to a matching `.html` path:
+Flame uses **filesystem-based routing** — every markdown file in `docs/` compiles to a matching `.html` path:
 
 ```
 docs/
@@ -16,10 +16,12 @@ docs/
     └── routing.mdx                 → /docs/guide/routing.html
 ```
 
-## Auto-routing
+## Add a page
 
-When `routes: []` in `docu.json`, Flame automatically scans `docs/` at build time and generates the sidebar from the directory structure.
+1. Create `docs/guide/faq.mdx`
+2. Add frontmatter: `title` and `description`
+3. Write markdown — the page appears in the sidebar and search automatically
 
-## Manual routes
+## Sidebar order
 
-Define `routes` in `docu.json` for a custom sidebar. Add `context` groups with icons for multi-section documentation. See this project's `docu.json` for examples.
+When `routes: []`, Flame scans `docs/` and builds the sidebar from the directory structure. Define `routes` in `docu.json` for a custom order and grouped sections — see this project's `docu.json` for a working example.

package/template/docs/index.mdx

@@ -1,15 +1,16 @@
 ---
-title: DocuBook Flame 🔥
-description: An open-source alternative to Mintlify or GitBook — MDX-powered documentation, static HTML output.
+title: My Docs
+description: Documentation powered by DocuBook Flame.
 ---
 
-**@docubook/flame** is a static site generator for documentation. Write in MDX, compile to flat static HTML — no server required. Runs on **Bun**, **Node.js**, and **Deno**.
+Welcome to **My Docs** — a static documentation site built with [DocuBook Flame](https://www.docubook.pro/).
+
+Flame compiles the markdown in `docs/` into flat static HTML. No server, no database, no runtime — deploy anywhere.
 
 ```mermaid
-flowchart LR
-    A[Your .mdx content] --> B[flame build]
-    B --> C[Static HTML + assets]
-    C --> D[Vercel / Netlify / GitHub Pages / S3]
+flowchart TD
+    A["docs/*.md"] --> B["flame build"]
+    B --> C["Static HTML + assets"]
+    C --> D["Vercel · Netlify · GitHub Pages · S3"]
 ```
 
-Check the sidebar for guides on getting started, configuration, components, routing, and deployment.

package/template/docu.json

@@ -7,6 +7,9 @@
     "favicon": "/docs/assets/images/favicon.ico",
     "ogImage": "/docs/assets/images/og.png"
   },
+  "sidebar": {
+    "context": "separator"
+  },
   "themes": {
     "colors": "default"
   },
@@ -71,13 +74,10 @@
     "social": []
   },
   "repo": {
-    "url": "",
+    "url": "https://github.com/DocuBook/docubook",
     "path": "blob/main/{filePath}",
     "edit": false
   },
-  "sidebar": {
-    "context": "dropdown"
-  },
   "routes": [
     {
       "title": "Getting Started",