blume

Blume

Documentation for everything you build. Fast, AI-ready, and zero-config. Free and open source, forever.

Drop Markdown or MDX into a folder, run blume dev, and get a production-grade docs site — navigation, search, theming, Open Graph images, and a rich component library — with no app boilerplate to write or maintain. Blume generates and drives a hidden Astro project for you; run blume eject to get a standalone Astro app whenever you want full control.

Documentation · Quickstart · Components · CLI

Quickstart

Blume needs Node.js 22.12 or newer and a content folder with at least one .md/.mdx file — there's nothing else to set up.

npx blume init

Run the dev server with hot reload:

blume dev

Build static HTML, with a local search index, into dist/:

blume build

Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.

Features

• Zero-config, even the template — a folder of docs is a complete project. No starter to clone, no framework to learn. Configuration is opt-in, one file at a time.
• Fast by default — static HTML on Astro and Vite; the core theme ships no client framework JS so pages score well on Core Web Vitals out of the box.
• Type-safe config — blume.config.ts and every meta.ts are real TypeScript, validated by a schema and authored with defineConfig / defineMeta, so your editor catches mistakes before a build.
• Components, no imports — cards, columns, steps, tabs, accordions, badges, code groups, frames, file trees, type tables, live component previews, diffs, and more, usable in any MDX page.
• Local search — Orama runs in dev and production with no hosted service; FlexSearch, Pagefind, Algolia, Typesense, Orama Cloud, and Mixedbread are one setting away.
• AI-ready — llms.txt / llms-full.txt, raw Markdown at any .md URL, Copy as Markdown, Open in chat, an optional Ask AI assistant, and a hosted MCP server so coding agents can search and read your docs directly.
• Agent skills — Blume ships agent skills that teach a coding agent to scaffold, write, and maintain your docs site.
• Content sources — mix local files with remote MDX, GitHub Releases, Notion, Sanity, or any custom backend into a single site.
• Internationalization — drop translated files into place for locale-aware routing, per-language navigation, translated UI, and SEO.
• SEO — metadata, Open Graph images (rendered at build with Takumi), sitemap, robots.txt, RSS feeds, and JSON-LD, built in.
• API reference — render an OpenAPI or AsyncAPI spec as an interactive reference (schemas, auth, request playground) via Scalar.
• Export — let readers download any page as a PDF or EPUB, entirely client-side, so static builds stay static.
• Customization — component overrides, React islands, custom pages, Tailwind v4 theme tokens and theme.css, and a source-component registry (blume add).
• Eject — blume eject produces a standalone Astro project that still uses the blume package.

CLI

Command	Description
blume init [dir]	Scaffold a project (interactive by default).
blume dev	Start the dev server with hot reload.
blume build	Build the static (or server) site.
blume preview	Preview the last build.
blume add <item>	Install a source component from the registry.
blume sync	Re-fetch remote content sources and regenerate.
blume eject	Promote the runtime into a standalone Astro app.
blume check	Type-check the docs site with astro check.
blume validate	Validate internal, anchor, asset, and external links.
blume doctor	Diagnose config and content problems.
blume audit	Audit the built site for SEO and health issues.
blume eval	Test the docs: an agent answers your questions using only the documentation.
blume translate	Translate docs into the configured locales with a local agent CLI.
blume version [id]	Freeze the current docs as an archived version (no id lists configured versions).

See the CLI reference for every flag.

How it works

The Blume CLI loads blume.config.ts, scans your content into a graph, and generates a hidden Astro project under .blume/ that it drives for dev and build. Astro renders through a catch-all page that imports Blume's shipped components, the generated data, and your overrides. .blume/ is regenerated on each run — only changed files are written, so hot reload stays fast — until you blume eject and own it.

Deployment

blume build outputs static HTML to dist/ — deploy to any static host (Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3 + CloudFront, or any CDN). For request-time features like Ask AI or the MCP server, switch to server output and pick an adapter:

Adapter	Use for
vercel	Vercel
netlify	Netlify Functions
node	Self-hosted Node servers, containers
cloudflare	Cloudflare Workers and Pages

On Vercel, Netlify, and Cloudflare Pages the matching adapter and site URL are detected automatically.

Compatibility

Requirement	Supported
Node	22.12+
Package managers	Bun, pnpm, npm, yarn
Adapters	Vercel, Netlify, Node, Cloudflare

Development

This repository is a monorepo: the published package lives in packages/blume, and apps/docs is Blume's own documentation, built with Blume.

bun install
bun run check       # lint + format (Ultracite)
bun run typecheck
bun run test

See CONTRIBUTING.md for architecture and conventions.

License

MIT © Hayden Bleasel