Hayden Bleasel, an expert developer from OpenAI, released ** Blume**, an open-source documentation framework. Blume shipped to npm as version 1.0.3 the same day. It is as simple as Drop Markdown into a folder and ship a docs site. No app boilerplate is written or maintained afterward. The project is MIT-licensed and open sourced.
What is Blume?
** Blume** is a command-line tool paired with a component library for docs. It reads a folder of Markdown or MDX files. From that folder, it produces a production-grade documentation site. That output ships navigation, search, theming, and Open Graph images. Configuration stays optional and is added one file at a time. The code is a TypeScript monorepo; the published package sits at
packages/blume
. Blume’s own documentation, under apps/docs
, is built with Blume itself. It requires Node.js 22.12 or newer. It runs with Bun, pnpm, npm, or yarn.How Blume Works?
Under the surface, Blume generates and drives a hidden Astro project. First, the CLI loads blume.config.ts
and scans your content into a graph. Next, it writes an Astro project into a .blume/
directory. Astro then renders every page through a single catch-all route. That route imports Blume’s shipped components, the generated data, and your overrides. On each run, .blume/
regenerates, and only changed files are rewritten. As a result, hot reload stays fast during editing. The core theme ships no client framework JavaScript. Consequently, pages score well on Core Web Vitals by default. When you need full control, blume eject
promotes the runtime into a standalone Astro app. That ejected project still depends on the blume
package.
Getting Started
Setup takes a single command, so onboarding is short.
npx blume init
Afterward, blume dev
starts a hot-re server. Meanwhile, blume build
writes static HTML and a local search index into dist/
. The config file is real TypeScript, validated by a schema.
// blume.config.ts
import { defineConfig } from "blume";
export default defineConfig({
content: {
sources: [
{ type: "filesystem", root: "docs" },
{ type: "notion", database: process.env.NOTION_DB },
],
},
});
Because the config is typed, editors catch mistakes before a build runs. The CLI covers the full lifecycle beyond those basics:
| Command | Purpose |
|---|---|
blume init |
Scaffold a project, interactive by default |
blume dev |
Start the dev server with hot reload |
blume build |
Build the static or server site |
blume add |
Install a source component from the registry |
blume sync |
Re-fetch remote content sources |
blume eject |
Promote the runtime into a standalone Astro app |
blume validate |
Check internal, anchor, asset, and external links |
blume doctor |
Diagnose config and content problems |
AI-Ready by Design
Beyond human readers, Blume targets agents too. Every page returns raw Markdown when you append .md
to its URL. A single flag emits llms.txt
and llms-full.txt
for agents. Each page can be copied as Markdown or opened in ChatGPT, Claude, or v0. An optional in-page Ask AI assistant answers reader questions directly. It runs on the AI SDK through the Vercel AI Gateway, OpenRouter, Inkeep, or any OpenAI-compatible endpoint. Blume can also host a Model Context Protocol (MCP) server. Through it, Claude Code, Cursor, and VS Code read docs directly.
claude mcp add --transport http your-docs https://docs.example.com/mcp
That server exposes four read-only tools: search_docs
, get_page
, list_pages
, and get_navigation
.
Use Cases With Examples
Those capabilities map to concrete jobs. For an API product, drop in an OpenAPI or AsyncAPI spec. Blume then renders an interactive reference with schemas, auth, and a request playground via Scalar. For a library, point Blume at your GitHub Releases. Each release rolls up into a generated changelog timeline with an RSS feed. For a global audience, add translated files per locale. Blume supports 36 locales, locale-aware routing, and right-to-left layouts. For mixed content, combine local files with remote MDX, Notion, or Sanity. All sources render through the same components.
How Blume Compares
For context, here is Blume against three common documentation approaches. Features change quickly, so verify current details before you adopt.
| Dimension | Blume | Mintlify | Docusaurus | Astro Starlight |
|---|---|---|---|---|
| Type | Open-source CLI + framework | Hosted commercial platform | Open-source SSG | Open-source Astro theme |
| License | MIT, free | Proprietary; paid Pro tier | MIT, free | MIT, free |
| Setup | Zero-config Markdown folder | Config-driven, managed | Scaffold + React config | Astro project + theme |
| Engine | Hidden Astro + Vite | Proprietary hosted | React | Astro |
| Core-theme client JS | None (static HTML) | — | React runtime | Minimal (islands) |
llms.txt / llms-full.txt |
Built-in flag | Auto-generated | Community plugin | Community plugin |
| Built-in MCP server | Yes (four read-only tools) | Yes (auto-hosted) | Not built-in | Not built-in |
| Eject path | Standalone Astro app | Not applicable (hosted) | — | Already Astro |
Strengths and Weaknesses
Strengths
- Zero-config start: a folder of Markdown becomes a full site.
- Static-first output ships no core client JS, aiding Core Web Vitals.
- Built-in AI surfaces:
llms.txt
, per-page Markdown, MCP server, and Ask AI. - Type-safe config, so editors flag errors before a build runs.
- Eject path to a standalone Astro app reduces long-term lock-in.
Weaknesses
- Version 1.0.3 is new, so the ecosystem is still young.
- It needs Node.js 22.12 or newer, which some environments lack.
- Request-time features like Ask AI and MCP need a server adapter.
- The self-hosted model means you own analytics and assistant wiring.
- It has fewer third-party integrations than mature hosted platforms today.
Key Takeaways
- Blume turns a Markdown folder into a production docs site with zero config.
- It drives a hidden Astro and Vite project and can eject to standalone Astro.
- AI features ship built in:
llms.txt
, per-page Markdown, and an MCP server. - It is MIT-licensed, needs Node.js 22.12+, and reached npm v1.0.3 on launch day.
- Early adopters include Quiver, moving from Mintlify, and Neon’s add-mcp docs.
Check out the ** GitHub Repo. **Also, feel free to follow us on
and don’t forget to join ourTwitter
and Subscribe to
150k+ML SubReddit. Wait! are you on telegram?
now you can join us on telegram as well.Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? Connect with us