📘 docbook

Storybook, but for your markdown. A zero-config documentation site for your docs, ADRs, and the agents / skills / rules markdown files that drive Claude and Cursor. Add it to package.json, run a dev server locally, or build a static site anyone can view — no access to the source code required.

• 📂 Auto-discovers docs/, .claude/ and .cursor/ — or point it anywhere.
• 🧭 Folder-tree sidebar, breadcrumb nav, and an on-page table of contents.
• 🔎 Instant full-text search (⌘K).
• 🧩 Frontmatter-aware cards for agents, skills, and rules (name, description, alwaysApply, model, tools, …).
• 📊 Mermaid diagrams and syntax-highlighted code blocks out of the box.
• 🌗 Light / dark / system themes.
• 🚀 docbook build produces a static bundle you can deploy to any static host.

Install

npm install --save-dev @mtayab1994/docbook
# or: pnpm add -D @mtayab1994/docbook

Use

# Start a local dev server (defaults to http://localhost:4400)
npx docbook dev

# Build a static, deployable site into ./docbook-static
npx docbook build

Add scripts to your package.json:

{
  "scripts": {
    "docs": "docbook dev",
    "docs:build": "docbook build"
  }
}

Configuration

docbook works with no config — it auto-detects docs/, .claude/agents, .claude/skills, .claude/rules, and the .cursor/ equivalents.

To customise, run npx docbook init and edit docbook.config.ts:

import { defineConfig } from "@mtayab1994/docbook";

export default defineConfig({
  title: "InSight Platform Docs",
  description: "Architecture, runbooks, agents and skills.",
  theme: "system", // "light" | "dark" | "system"
  editBaseUrl: "https://github.com/org/insight-saas/blob/main/",
  sources: [
    { label: "Docs", path: "docs", icon: "📚" },
    { label: "Claude · Agents", path: ".claude/agents", kind: "agent", icon: "🤖" },
    { label: "Claude · Skills", path: ".claude/skills", kind: "skill", icon: "🧩" },
    { label: "Claude · Rules", path: ".claude/rules", kind: "rule", icon: "📐" },
    { label: "Cursor · Rules", path: ".cursor/rules", kind: "rule", icon: "📐" },
  ],
});

Source options

| Field | Description | | --------- | ------------------------------------------------------------------ | | label | Sidebar group title. | | path | Directory to scan, relative to the project root. | | include | Globs relative to path. Default: **/*.md, **/*.mdx, **/*.mdc. | | exclude | Globs to ignore. | | kind | doc | agent | skill | rule — drives the metadata card. | | icon | Emoji shown beside the group. |

Top-level config

| Field | Default | Description | | ------------- | ---------------- | ------------------------------------------------------ | | title | "Documentation"| Site + tab title. | | description | — | Tagline on the home screen. | | theme | "system" | Default colour theme. | | base | "/" | Public base path for static builds under a sub-path. | | editBaseUrl | — | Prefix for "View source" links (doc path is appended). | | root | cwd | Project root the sources resolve against. |

CLI

| Command | Description | | ---------------- | ------------------------------------------------------- | | docbook dev | Dev server. --port, --host, --open, --config, --root. | | docbook build | Static build. --out (default docbook-static), --config, --root. | | docbook init | Write a starter docbook.config.ts. |

Deploying

docbook build emits a fully static site. Deploy docbook-static/ to GitHub Pages, Netlify, Vercel, S3, or any static host. For a sub-path deploy (e.g. example.com/docs/), set base: "/docs/" in the config.

License

MIT