@docubook/flame 1.0.0-beta.80 → 1.0.1

package/template/docs/index.mdx

@@ -1,11 +1,26 @@
 ---
-title: DocuBook Flame
-description: A Bun-native framework for modern documentation experiences.
+title: DocuBook Flame 🔥
+description: Fast as flame — a Bun-native framework for modern documentation experiences.
 date: 2026-05-24
 ---
 
 **@docubook/flame** is a lightweight runtime for building documentation websites using React, MDX, and filesystem-based routing — all running on Bun.
 
+No heavy abstractions. No complex tooling. Just a minimal layer between your content and the browser.
+
+> **Lightweight** — 📦 ~57 kB packed, ~207 kB unpacked. No bloat, just fire.
+
+## Features
+
+- **Bun-native** — instant startup, native TypeScript, fast builds
+- **React-first** — JSX/TSX, hooks, component composition
+- **MDX content** — write Markdown with embedded React components
+- **Filesystem routing** — auto-detect routes from `docs/` folder
+- **Lightweight SSR** — React server-side rendering without a heavy framework
+- **Client hydration** — interactive islands for sidebar, TOC, and MDX components
+- **HMR** — instant reload on docs changes during development
+- **Static build** — pre-render all pages to static HTML for deployment
+
 ## Quick Start
 
 ```bash
@@ -17,6 +32,8 @@ bun run dev
 
 ## Project Structure
 
+After `flame init`, your project looks like:
+
 ```
 my-docs/
 ├── docs/              # Your MDX content
@@ -24,17 +41,17 @@ my-docs/
 ├── docu.json          # Site configuration (navbar, routes, meta)
 ├── package.json       # Dependencies
 └── .docu/
-    └── dist/          # Build output (after bun run build)
+    └── dist/          # Build output (after `bun run build`)
 ```
 
 ## Commands
 
-|      Command      |           Description            |
-| ----------------- | -------------------------------- |
-| `bun run dev`     | Start dev server with HMR        |
-| `bun run build`   | Static build to `.docu/dist/`    |
-| `bun run preview` | Serve built output locally       |
-| `bun run deploy`  | Build + prepare for GitHub Pages |
+```bash
+bun run dev       # Start dev server with HMR
+bun run build     # Static build to .docu/dist/
+bun run preview   # Serve built output locally
+bun run deploy    # Build + prepare for GitHub Pages
+```
 
 ## Configuration
 
@@ -57,7 +74,34 @@ my-docs/
 }
 ```
 
-When `routes` is empty, navigation is auto-generated from your `docs/` folder structure.
+### Routes
+
+When `routes` is an empty array `[]`, Flame automatically scans your `docs/` folder at build-time and generates the sidebar navigation from the directory structure. Folders become collapsible sections, and `.mdx`/`.md` files become links — sorted alphabetically.
+
+To define navigation manually, populate the `routes` array:
+
+```json
+{
+  "routes": [
+    {
+      "title": "Getting Started",
+      "href": "/getting-started",
+      "noLink": true,
+      "context": {
+        "icon": "BookOpen",
+        "title": "Guides",
+        "description": "Set up your Documentation"
+      },
+      "items": [
+        { "title": "Introduction", "href": "/introduction" },
+        { "title": "Installation", "href": "/installation" }
+      ]
+    }
+  ]
+}
+```
+
+> Manual routes take priority — if `routes` has entries, folder scanning is skipped entirely.
 
 ## Routing
 
@@ -72,6 +116,45 @@ docs/
     └── card.mdx                 → /docs/components/card
 ```
 
+## Assets
+
+Place images and static files in `docs/assets/`. They are copied to the build output and accessible at `/docs/assets/`.
+
+```
+docs/
+├── assets/
+│   └── images/
+│       ├── logo.svg
+│       └── screenshot.png
+└── getting-started/
+    └── introduction.mdx
+```
+
+Reference in MDX:
+
+```markdown
+![Screenshot](/docs/assets/images/screenshot.png)
+```
+
+> The `docs/assets/` directory is excluded from route scanning — files inside it won't appear in the sidebar.
+
+## Architecture
+
+- **Bun** — runtime, bundler, file watcher
+- **React + React DOM** — rendering (SSR + client hydration)
+- **@docubook/core** — MDX compilation, rehype/remark plugins
+- **@docubook/mdx-content** — pre-built MDX components
+- **Tailwind CSS + daisyUI** — styling
+
+## Comparison
+
+|      Framework      | Runtime |    UI     |          Approach           |
+| ------------------- | ------- | --------- | --------------------------- |
+| Docusaurus          | Node.js | React     | Full-featured, plugin-heavy |
+| VitePress           | Node.js | Vue       | Lightweight, Vue-only       |
+| Nextra              | Node.js | React     | Next.js-based               |
+| **@docubook/flame** | **Bun** | **React** | **Minimal, Bun-native SSR** |
+
 ## Deployment
 
 ### GitHub Pages
@@ -80,27 +163,50 @@ docs/
 bun run deploy
 ```
 
-This will run a production build, add `.nojekyll`, and generate `.github/workflows/deploy.yml`.
+This will:
+
+1. Run production build → output to `.docu/dist/`
+2. Add `.nojekyll` file
+3. Generate `.github/workflows/deploy.yml` (first run only)
 
 Then push to GitHub and enable Pages: **Settings → Pages → Source: GitHub Actions**
 
-### Other Hosts
+### Manual / Other Hosts
 
 ```bash
 bun run build
 ```
 
-Upload `.docu/dist/` to any static hosting (Netlify, Cloudflare Pages, Vercel, S3, etc).
+Upload the contents of `.docu/dist/` to any static hosting (Netlify, Cloudflare Pages, Vercel, S3, etc).
 
 ## Environment Variables
 
-Copy `.env.example` to `.env`:
+Copy `.env.example` to `.env` to customize:
 
-```bash
+```
+# Server port (default: 3000)
 PORT=3000
-# SENTRY_DSN=https://your-dsn@sentry.io/project-id
+
+# Error Monitoring (optional)
+SENTRY_DSN=https://your-dsn@sentry.io/project-id
 ```
 
+## Error Monitoring (Optional)
+
+Flame has built-in [Sentry](https://sentry.io) support for error tracking. To enable:
+
+```bash
+bun add @sentry/bun
+```
+
+Then set environment variables:
+
+```
+SENTRY_DSN=https://your-dsn@sentry.io/project-id
+```
+
+Errors during dev server and build will be automatically captured. No configuration needed beyond the DSN.
+
 ## Requirements
 
 - [Bun](https://bun.sh) >= 1.1.0

package/.docu/components/base/breadcrumbs.tsx

@@ -1,64 +0,0 @@
-import { ReactNode } from "react";
-
-export interface BreadcrumbProps {
-  children: ReactNode;
-  className?: string;
-}
-
-export interface BreadcrumbItemProps {
-  children: ReactNode;
-  className?: string;
-}
-
-export interface BreadcrumbLinkProps {
-  href?: string;
-  children: ReactNode;
-  className?: string;
-  onClick?: () => void;
-}
-
-export function Breadcrumb({ children, className = "" }: BreadcrumbProps) {
-  return (
-    <div className={`breadcrumbs text-sm ${className}`}>
-      <ul>{children}</ul>
-    </div>
-  );
-}
-
-export function BreadcrumbItem({ children, className = "" }: BreadcrumbItemProps) {
-  return <li className={className}>{children}</li>;
-}
-
-export function BreadcrumbLink({ href, children, className = "", onClick }: BreadcrumbLinkProps) {
-  const baseClass = "link link-hover";
-
-  if (href) {
-    return (
-      <a href={href} className={`${baseClass} ${className}`}>
-        {children}
-      </a>
-    );
-  }
-
-  if (onClick) {
-    return (
-      <button type="button" onClick={onClick} className={`${baseClass} ${className}`}>
-        {children}
-      </button>
-    );
-  }
-
-  return <span className={className}>{children}</span>;
-}
-
-export function BreadcrumbPage({ children, className = "" }: BreadcrumbItemProps) {
-  return <span className={className}>{children}</span>;
-}
-
-export function BreadcrumbSeparator({ className = "" }: { className?: string }) {
-  return <li className={className}></li>;
-}
-
-export function BreadcrumbList({ children }: BreadcrumbItemProps) {
-  return <>{children}</>;
-}

package/.docu/components/base/collapse.tsx

@@ -1,186 +0,0 @@
-"use client";
-
-import { cn } from "../../node/utils";
-import { ChevronDown, ChevronRight, Plus, Minus } from "lucide-react";
-import { useState, type ReactNode } from "react";
-
-type CollapseVariant = "arrow" | "plus";
-
-interface CollapseProps {
-  title: ReactNode;
-  children: ReactNode;
-  defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  variant?: CollapseVariant;
-  className?: string;
-  titleClassName?: string;
-  contentClassName?: string;
-  disabled?: boolean;
-}
-
-export default function Collapse({
-  title,
-  children,
-  defaultOpen = false,
-  onOpenChange,
-  variant = "arrow",
-  className,
-  titleClassName,
-  contentClassName,
-  disabled = false,
-}: CollapseProps) {
-  const [isOpen, setIsOpen] = useState(defaultOpen);
-
-  const handleToggle = () => {
-    if (disabled) return;
-    const newState = !isOpen;
-    setIsOpen(newState);
-    onOpenChange?.(newState);
-  };
-
-  const Icon = variant === "arrow" ? (isOpen ? ChevronDown : ChevronRight) : isOpen ? Minus : Plus;
-
-  const variantClass = variant === "arrow" ? "collapse-arrow" : "collapse-plus";
-
-  return (
-    <div
-      className={cn(
-        "bg-base-100 border-base-200 collapse rounded-lg border",
-        isOpen && "collapse-open",
-        !isOpen && "collapse-close",
-        variantClass,
-        disabled && "cursor-not-allowed opacity-50",
-        className
-      )}
-    >
-      <input
-        type="checkbox"
-        checked={isOpen}
-        onChange={handleToggle}
-        disabled={disabled}
-        aria-expanded={isOpen}
-      />
-      <div
-        className={cn(
-          "collapse-title text-base-content cursor-pointer font-medium",
-          titleClassName
-        )}
-        onClick={handleToggle}
-        role="button"
-        tabIndex={disabled ? -1 : 0}
-        onKeyDown={(e) => {
-          if (!disabled && (e.key === "Enter" || e.key === " ")) {
-            e.preventDefault();
-            setIsOpen(!isOpen);
-          }
-        }}
-      >
-        <div className="flex items-center justify-between pr-8">
-          <span className="flex-1">{title}</span>
-          <Icon
-            className={cn(
-              "text-base-content/60 h-4 w-4 transition-transform duration-200",
-              isOpen && "rotate-180"
-            )}
-            aria-hidden="true"
-          />
-        </div>
-      </div>
-      <div className={cn("collapse-content text-base-content/80", contentClassName)}>
-        {children}
-      </div>
-    </div>
-  );
-}
-
-interface AccordionItem {
-  id: string;
-  title: ReactNode;
-  content: ReactNode;
-}
-
-interface AccordionProps {
-  items: AccordionItem[];
-  defaultOpen?: string;
-  variant?: CollapseVariant;
-  className?: string;
-  allowMultiple?: boolean;
-}
-
-export function Accordion({
-  items,
-  defaultOpen,
-  variant = "arrow",
-  className,
-  allowMultiple = false,
-}: AccordionProps) {
-  const [openIds, setOpenIds] = useState<Set<string>>(
-    defaultOpen ? new Set([defaultOpen]) : new Set()
-  );
-
-  const toggle = (id: string) => {
-    setOpenIds((prev) => {
-      const next = new Set(prev);
-      if (next.has(id)) {
-        next.delete(id);
-      } else {
-        if (!allowMultiple) {
-          next.clear();
-        }
-        next.add(id);
-      }
-      return next;
-    });
-  };
-
-  return (
-    <div className={cn("flex flex-col gap-3", className)}>
-      {items.map((item) => {
-        const isOpen = openIds.has(item.id);
-        const Icon =
-          variant === "arrow" ? (isOpen ? ChevronDown : ChevronRight) : isOpen ? Minus : Plus;
-
-        return (
-          <div
-            key={item.id}
-            className={cn(
-              "bg-base-100 border-base-200 collapse rounded-lg border",
-              isOpen && "collapse-open",
-              !isOpen && "collapse-close",
-              variant === "arrow" ? "collapse-arrow" : "collapse-plus"
-            )}
-          >
-            <input type="checkbox" checked={isOpen} onChange={() => toggle(item.id)} />
-            <div
-              className="collapse-title text-base-content cursor-pointer pr-8 font-medium"
-              onClick={() => toggle(item.id)}
-              role="button"
-              tabIndex={0}
-              onKeyDown={(e) => {
-                if (e.key === "Enter" || e.key === " ") {
-                  e.preventDefault();
-                  toggle(item.id);
-                }
-              }}
-            >
-              <div className="flex items-center justify-between">
-                <span className="flex-1">{item.title}</span>
-                <Icon
-                  className={cn(
-                    "text-base-content/60 h-4 w-4 transition-transform duration-200",
-                    isOpen && "rotate-180"
-                  )}
-                  aria-hidden="true"
-                />
-              </div>
-            </div>
-            <div className="collapse-content text-base-content/80">{item.content}</div>
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-
-export { Collapse };
-export type { CollapseProps, AccordionItem, AccordionProps };

package/.docu/components/base/drawer.tsx

@@ -1,164 +0,0 @@
-"use client";
-
-import { cn } from "../../node/utils";
-import { X } from "lucide-react";
-import { useState, type ReactNode } from "react";
-
-type DrawerSide = "left" | "right";
-
-interface DrawerProps {
-  id: string;
-  children: ReactNode;
-  defaultOpen?: boolean;
-  side?: DrawerSide;
-  breakpoint?: string;
-  withOverlay?: boolean;
-  overlayClassName?: string;
-  sideClassName?: string;
-  contentClassName?: string;
-  className?: string;
-}
-
-export default function Drawer({
-  id,
-  children,
-  defaultOpen = false,
-  side = "left",
-  breakpoint = "lg",
-  withOverlay = true,
-  overlayClassName,
-  sideClassName,
-  contentClassName,
-  className,
-}: DrawerProps) {
-  const [isOpen, setIsOpen] = useState(defaultOpen);
-
-  const toggleDrawer = () => setIsOpen(!isOpen);
-  const closeDrawer = () => setIsOpen(false);
-
-  const sidePositionClass = side === "right" ? "drawer-end" : "";
-
-  return (
-    <div
-      className={cn(
-        "drawer",
-        breakpoint ? `${breakpoint}:drawer-open` : "",
-        sidePositionClass,
-        className
-      )}
-    >
-      <input
-        id={id}
-        type="checkbox"
-        className="drawer-toggle"
-        checked={isOpen}
-        onChange={toggleDrawer}
-        aria-label="Toggle drawer"
-      />
-
-      <div className={cn("drawer-content flex flex-col", contentClassName)}>
-        {typeof children === "function"
-          ? (
-              children as (props: {
-                open: boolean;
-                toggle: () => void;
-                close: () => void;
-              }) => ReactNode
-            )({ open: isOpen, toggle: toggleDrawer, close: closeDrawer })
-          : children}
-      </div>
-
-      <div className={cn("drawer-side", sideClassName)}>
-        {withOverlay && (
-          <label
-            htmlFor={id}
-            aria-label="Close sidebar"
-            className={cn("drawer-overlay", overlayClassName)}
-            onClick={closeDrawer}
-          />
-        )}
-
-        <div className="bg-base-200 min-h-full w-80 p-4">
-          <div className="mb-4 flex items-center justify-between">
-            <span className="text-lg font-semibold">Menu</span>
-            <button
-              onClick={closeDrawer}
-              className="btn btn-ghost btn-sm btn-circle"
-              aria-label="Close drawer"
-            >
-              <X className="h-5 w-5" />
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-export function useDrawerState(initialState = false) {
-  const [isOpen, setIsOpen] = useState(initialState);
-
-  return {
-    isOpen,
-    open: () => setIsOpen(true),
-    close: () => setIsOpen(false),
-    toggle: () => setIsOpen((prev) => !prev),
-  };
-}
-
-interface DrawerTriggerProps {
-  drawerId: string;
-  children: ReactNode;
-  className?: string;
-}
-
-export function DrawerTrigger({ drawerId, children, className }: DrawerTriggerProps) {
-  return (
-    <label htmlFor={drawerId} className={cn("label cursor-pointer", className)}>
-      {children}
-    </label>
-  );
-}
-
-interface DrawerContentProps {
-  children: ReactNode;
-  className?: string;
-}
-
-export function DrawerContent({ children, className }: DrawerContentProps) {
-  return <div className={cn("drawer-content", className)}>{children}</div>;
-}
-
-interface DrawerSidePanelProps {
-  id: string;
-  children: ReactNode;
-  side?: DrawerSide;
-  withOverlay?: boolean;
-  overlayClassName?: string;
-  className?: string;
-}
-
-export function DrawerSidePanel({
-  id,
-  children,
-  side = "left",
-  withOverlay = true,
-  overlayClassName,
-  className,
-}: DrawerSidePanelProps) {
-  return (
-    <div className={cn("drawer-side", side === "right" ? "drawer-end" : "", className)}>
-      {withOverlay && (
-        <label
-          htmlFor={id}
-          aria-label="Close sidebar"
-          className={cn("drawer-overlay", overlayClassName)}
-        />
-      )}
-      {children}
-    </div>
-  );
-}
-
-export { Drawer };
-export type { DrawerProps, DrawerSide };

package/.docu/components/base/dropdown.tsx

@@ -1,94 +0,0 @@
-"use client";
-
-import { type HTMLAttributes, type ReactNode, forwardRef, useRef, useEffect } from "react";
-import { cn } from "../../node/utils";
-
-export interface DropdownProps extends HTMLAttributes<HTMLDetailsElement> {
-  align?: "start" | "end";
-  disabled?: boolean;
-  trigger?: ReactNode;
-  children?: ReactNode;
-}
-
-export const Dropdown = forwardRef<HTMLDetailsElement, DropdownProps>(
-  ({ className, align = "start", disabled = false, trigger, children, ...props }, ref) => {
-    const detailsRef = useRef<HTMLDetailsElement>(null);
-
-    // Close on click outside
-    useEffect(() => {
-      const handler = (e: MouseEvent) => {
-        if (detailsRef.current && !detailsRef.current.contains(e.target as Node)) {
-          detailsRef.current.open = false;
-        }
-      };
-      document.addEventListener("click", handler);
-      return () => document.removeEventListener("click", handler);
-    }, []);
-
-    return (
-      <details
-        ref={(el) => {
-          (detailsRef as React.MutableRefObject<HTMLDetailsElement | null>).current = el;
-          if (typeof ref === "function") ref(el);
-          else if (ref) ref.current = el;
-        }}
-        className={cn("relative", disabled && "pointer-events-none opacity-50", className)}
-        {...props}
-      >
-        <summary className="cursor-pointer list-none [&::-webkit-details-marker]:hidden">
-          {trigger}
-        </summary>
-        <ul
-          className={cn(
-            "bg-base-100 rounded-box border-base-300 absolute z-50 mt-1 w-full min-w-[200px] space-y-1 border p-2 shadow-lg",
-            align === "end" ? "right-0" : "left-0"
-          )}
-        >
-          {children}
-        </ul>
-      </details>
-    );
-  }
-);
-Dropdown.displayName = "Dropdown";
-
-export interface DropdownItemProps extends HTMLAttributes<HTMLLIElement> {
-  children?: ReactNode;
-}
-
-export const DropdownItem = forwardRef<HTMLLIElement, DropdownItemProps>(
-  ({ className, children, ...props }, ref) => (
-    <li ref={ref} className={cn(className)} role="menuitem" {...props}>
-      {children}
-    </li>
-  )
-);
-DropdownItem.displayName = "DropdownItem";
-
-export const DropdownLink = forwardRef<
-  HTMLAnchorElement,
-  HTMLAttributes<HTMLAnchorElement> & { href?: string }
->(({ className, children, href, ...props }, ref) => (
-  <li role="menuitem">
-    <a ref={ref} href={href} className={cn(className)} {...props}>
-      {children}
-    </a>
-  </li>
-));
-DropdownLink.displayName = "DropdownLink";
-
-export const DropdownLabel = forwardRef<HTMLLIElement, HTMLAttributes<HTMLLIElement>>(
-  ({ className, children, ...props }, ref) => (
-    <li ref={ref} className={cn("menu-title", className)} {...props}>
-      {children}
-    </li>
-  )
-);
-DropdownLabel.displayName = "DropdownLabel";
-
-export const DropdownDivider = forwardRef<HTMLLIElement, HTMLAttributes<HTMLLIElement>>(
-  ({ className, ...props }, ref) => (
-    <li ref={ref} className={cn("border-base-200 my-1 border-t", className)} {...props} />
-  )
-);
-DropdownDivider.displayName = "DropdownDivider";