Markbook

A lightweight, markdown-first Storybook alternative. Author your docs as plain .md; reference component stories that live in adjacent .tsx files via directives. Markbook builds a static Starlight-style site with full-text search, dark mode, an llms.txt mirror, SEO defaults, a sitemap, and portable embeds of any of your stories.

📖 Read the docs →

Status: pre-1.0. Only the React adapter ships today — Vue and Web Components adapters are on the roadmap. The public API is documented and largely stable, but minor releases may still break things until v1.0 freezes it.

Why Markbook

• 🤖 Agent-first by default. Ships six built-in agent skills (init, add-component-page, bulk-generate, style, layout, bundle-story) for Claude Code, Codex, OpenCode, Cursor, and any auto-discovering agent CLI. One npx markbook skills install and your agent knows the conventions — setup is a one-line conversation.
• 📄 Markdown is the source of truth. Every page is a .md file. HTML and llms.txt are two views of one AST. No MDX, no JSON sidecars, no JS templates.
• 🧩 Component stories, optional. Drop a :::story directive into any page to mount a live React component. Skip it for a pure docs/marketing site. Search, SEO, dark mode, and llms.txt are always on.
• 🎨 Four-layer customization. Token overrides → opt out of base CSS → swap the HTML shell → post-process. Pick the smallest layer that solves your problem.
• ⚡ Fast dev loop. Vite under the hood. ~80 ms regeneration on a small site, full Pagefind re-index included.

Install

pnpm add -D @doidor/markbook @doidor/markbook-core

Works with npm, yarn, and bun too — use whichever your project already uses.

For live React stories, also add the adapter and the framework runtime:

pnpm add -D @doidor/markbook-adapter-react
pnpm add react react-dom

Quick start

A minimal markdown-only site:

my-site/
├─ pages/
│  └─ index.md
└─ markbook.config.ts

// markbook.config.ts
import { defineConfig } from '@doidor/markbook-core';

export default defineConfig({
  title: 'My Project',
  description: 'A short blurb about the site.',
});

<!-- pages/index.md -->
---
title: Welcome
---

# Hello, world

This is **markdown**. It becomes HTML — with search, dark mode, and a TOC.

npx markbook dev      # live dev server  → http://localhost:5173
npx markbook build    # static site in dist/
npx markbook preview  # serve dist/      → http://localhost:4173

Don't open dist/*.html via file:// — Pagefind loads its runtime through dynamic import(), which browsers block on file://. Use markbook preview.

To add a component story, wire up the React adapter and drop a :::story directive — see the adding component stories guide.

Documentation

Guide	What it covers
Getting started	Install, scaffold, first page, dev server
Agent skills	The six shipped skills + how to install them
Adding component stories	React adapter, :::story / :::stories, CSF v3, decorators
Customization	Tokens, disableBaseCss, layouts, transformHtml
Custom directives	Register your own :::name handlers
Search & SEO	Pagefind, canonical URLs, sitemap, llms.txt
CLI reference	build / dev / preview / bundle / skills
Config reference	Every MarkbookConfig field

Packages

Package	Purpose
@doidor/markbook	The markbook CLI
@doidor/markbook-core	Markdown parser, builder, dev server, embed bundler, directive registry
@doidor/markbook-adapter-react	Mount React stories (+ controls + decorators)
@doidor/markbook-adapter-shared	Shared browser runtime for adapters (internal; see ADR-0026)

Repository layout

packages/
  core/             — markdown + builder + dev server + embed bundler + directives
  cli/              — markbook binary
  adapter-react/    — React mount + controls + decorators
  adapter-shared/   — shared pure-DOM runtime for adapters
examples/
  react-demo/       — Pixie component library — the canonical dogfood
  static-demo/      — Skyline: markdown-only docs site, no adapter
  marketing-demo/   — Cumulus: marketing site with a fully custom layout
  markbook-site/    — the official Markbook website
  embed-host/       — external consumer of the React demo's embed bundles

Contributing

pnpm install        # bootstrap the workspace
pnpm build          # compile every @doidor/markbook-* package
pnpm test           # @doidor/markbook-core + CLI Vitest suites
pnpm typecheck      # tsc --noEmit across packages
pnpm lint           # biome check

pnpm examples:dev   # every example dev server in parallel

Conventions live in AGENTS.md; architectural decisions in DECISIONS.md; the development journal in PROGRESS.md; planned work in ROADMAP.md.

License

Personal project — license TBD before v1.0.