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

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

@@ -1,6 +1,6 @@
 import {
   runDeploy
-} from "./chunk-X7KPVCDN.js";
+} from "./chunk-PJVCY4FK.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-PGIHPW5L.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-IN2QAGDZ.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-PGIHPW5L.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-IN2QAGDZ.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-HF3KKRQL.js";
+import "./chunk-42JQLAKP.js";
 import {
   denoAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-IN2QAGDZ.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-HF3KKRQL.js";
+import "./chunk-42JQLAKP.js";
 import {
   nodeAdapter
 } from "./chunk-UISOJ4RW.js";
 import "./chunk-EOK6KATZ.js";
-import "./chunk-AJV2GEDF.js";
+import "./chunk-IN2QAGDZ.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";
+@import "@docubook/ui-react/styles.css";
+
+/* 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.2",
   "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/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"
   },
   "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)).