Meet Blume: An Open-Source, Zero-Config Documentation Framework That Ships AI-Ready Docs From a Markdown Folder

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.

#blume-explainer .stage-wrap { position: relative; margin: 20px 0 8px; }
#blume-explainer svg { display: block; width: 100%; height: auto; }
#blume-explainer .node rect { transition: all .35s ease; }
#blume-explainer .node text { font-size: 12px; font-weight: 700; fill: var(–text); }
#blume-explainer .node .desc { font-size: 9.5px; font-weight: 500; fill: var(–muted); }
#blume-explainer .flowpath { stroke: var(–line); stroke-width: 2.5; fill: none; }
#blume-explainer .branchpath { stroke: var(–line); stroke-width: 2; fill: none; stroke-dasharray: 4 4; }
#blume-explainer .token {
fill: url(#flameGrad);
filter: drop-shadow(0 0 8px rgba(255,112,0,.85));
opacity: 0;
}

#blume-explainer .caption {
background: var(–panel);
border: 1px solid var(–line);
border-left: 3px solid var(–accent);
border-radius: 10px;
padding: 14px 16px;
margin-top: 14px;
min-height: 74px;
}
#blume-explainer .caption .step-label {
font-size: 11px; letter-spacing: .1em; text-transform: uppercase;
color: var(–accent); font-weight: 700;
}
#blume-explainer .caption h3 { font-size: 15px; margin: 4px 0 5px; font-weight: 700; }
#blume-explainer .caption p { font-size: 13px; color: var(–muted); line-height: 1.5; }

#blume-explainer .controls { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-top: 14px; }
#blume-explainer button {
font: inherit; font-size: 13px; font-weight: 700;
color: var(–text); background: var(–panel2);
border: 1px solid var(–line); border-radius: 9px;
padding: 9px 14px; cursor: pointer; transition: all .2s ease;
}
#blume-explainer button:hover { border-color: var(–accent); color: #fff; }
#blume-explainer button.primary {
background: linear-gradient(180deg, var(–orange), var(–vermilion));
border: none; color: #1a0d05;
}
#blume-explainer button.primary:hover { filter: brightness(1.08); }
#blume-explainer button:disabled { opacity: .4; cursor: not-allowed; }
#blume-explainer .spacer { flex: 1 1 auto; }

#blume-explainer .toggle {
display: inline-flex; align-items: center; gap: 7px;
font-size: 12.5px; color: var(–muted); cursor: pointer; user-select: none;
}
#blume-explainer .toggle .dot {
width: 34px; height: 19px; border-radius: 20px; background: var(–line);
position: relative; transition: background .2s ease; flex: none;
}
#blume-explainer .toggle .dot::after {
content: ""; position: absolute; top: 2px; left: 2px; width: 15px; height: 15px;
border-radius: 50%; background: var(–muted); transition: all .2s ease;
}
#blume-explainer .toggle.on .dot { background: linear-gradient(90deg, var(–orange), var(–vermilion)); }
#blume-explainer .toggle.on .dot::after { left: 17px; background: #fff; }

#blume-explainer .terminal {
margin-top: 14px; background: #0a0806; border: 1px solid var(–line);
border-radius: 10px; padding: 12px 14px; font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
font-size: 12px; color: #d7cbb8; min-height: 66px; line-height: 1.7;
}
#blume-explainer .terminal .p { color: var(–accent); }
#blume-explainer .terminal .ok { color: #ffb454; }
#blume-explainer .cursor { display: inline-block; width: 8px; background: var(–accent); animation: blink 1s steps(1) infinite; }
@keyframes blink { 50% { opacity: 0; } }

#blume-explainer .foot {
display: flex; justify-content: space-between; align-items: center;
margin-top: 16px; padding-top: 12px; border-top: 1px solid var(–line);
font-size: 11px; color: var(–muted); flex-wrap: wrap; gap: 6px;
}
#blume-explainer .foot b { color: var(–accent); font-weight: 800; }
#blume-explainer a.mtp { color: var(–accent); text-decoration: none; font-weight: 700; }

@media (max-width: 640px) {
#blume-explainer { padding: 16px 14px 12px; border-radius: 12px; }
#blume-explainer h2 { font-size: 18px; }
#blume-explainer .node text { font-size: 11px; }
#blume-explainer .node .desc { font-size: 8.5px; }
}
</style>
</head>
<body>
<div id="blume-explainer">
<div class="eyebrow">Interactive Explainer</div>
<h2>How <span class="flame">Blume</span> turns a Markdown folder into a docs site</h2>
<p class="sub">Follow one file as the Blume CLI scans it, generates a hidden Astro project, and renders static HTML plus AI-ready outputs. Press <b>Run</b>, or step through each stage.</p>

<!– main flow path –>
<path id="mainPath" class="flowpath" d="M 70 90 H 250 H 470 H 690 V 90"/>
<path class="flowpath" d="M 110 90 H 830"/>

<!– branch paths to AI/side outputs –>
<path class="branchpath ai-branch" d="M 560 118 V 210 H 300"/>
<path class="branchpath ai-branch" d="M 560 118 V 210 H 600"/>
<path class="branchpath ai-branch" d="M 560 210 H 820"/>

<!– STAGE NODES –>
<g class="node" data-stage="0">
<rect x="20" y="55" width="130" height="70" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="85" y="85" text-anchor="middle">/docs folder</text>
<text x="85" y="103" text-anchor="middle" class="desc">.md / .mdx files</text>
</g>
<g class="node" data-stage="1">
<rect x="185" y="55" width="130" height="70" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="250" y="85" text-anchor="middle">blume CLI</text>
<text x="250" y="103" text-anchor="middle" class="desc">loads config</text>
</g>
<g class="node" data-stage="2">
<rect x="405" y="55" width="130" height="70" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="470" y="85" text-anchor="middle">content graph</text>
<text x="470" y="103" text-anchor="middle" class="desc">scanned pages</text>
</g>
<g class="node" data-stage="3">
<rect x="625" y="35" width="150" height="70" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="700" y="65" text-anchor="middle">.blume/ (hidden)</text>
<text x="700" y="83" text-anchor="middle" class="desc">generated Astro app</text>
</g>
<g class="node" data-stage="4">
<rect x="625" y="130" width="150" height="66" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="700" y="158" text-anchor="middle">Astro + Vite</text>
<text x="700" y="176" text-anchor="middle" class="desc">catch-all render</text>
</g>
<g class="node" data-stage="5">
<rect x="795" y="55" width="95" height="70" rx="11" fill="#17120e" stroke="#33281f" stroke-width="1.5"/>
<text x="842" y="85" text-anchor="middle">dist/</text>
<text x="842" y="103" text-anchor="middle" class="desc">static HTML</text>
</g>

<!– connector from graph down to Astro –>
<path class="flowpath" d="M 700 105 V 130"/>

<!– AI / side output chips –>
<g class="node ai-node" data-ai="1">
<rect x="230" y="235" width="140" height="42" rx="9" fill="#1f1812" stroke="#33281f" stroke-width="1.5"/>
<text x="300" y="261" text-anchor="middle">llms.txt + .md URLs</text>
</g>
<g class="node ai-node" data-ai="1">
<rect x="530" y="235" width="140" height="42" rx="9" fill="#1f1812" stroke="#33281f" stroke-width="1.5"/>
<text x="600" y="261" text-anchor="middle">MCP server</text>
</g>
<g class="node ai-node" data-ai="1">
<rect x="750" y="235" width="140" height="42" rx="9" fill="#1f1812" stroke="#33281f" stroke-width="1.5"/>
<text x="820" y="261" text-anchor="middle">search · OG · RSS</text>
</g>

<!– travelling token –>
<circle id="token" class="token" r="9" cx="70" cy="90"/>
</svg>
</div>

<div class="caption">
<div class="step-label" id="stepLabel">Ready</div>
<h3 id="stepTitle">Press Run to watch the build</h3>
<p id="stepText">Blume needs only a folder of Markdown. Everything below is generated for you and thrown away on each run, unless you eject.</p>
</div>

<div class="terminal" id="term"><span class="p">$</span> <span id="termText">npx blume init</span><span class="cursor"> </span></div>

<div class="controls">
<button class="primary" id="runBtn"> Run blume dev</button>
<button id="prevBtn" disabled>‹ Prev</button>
<button id="nextBtn">Next ›</button>
<button id="resetBtn">↺ Reset</button>
<div class="spacer"></div>
<label class="toggle on" id="aiToggle"><span class="dot"></span> Show AI outputs</label>
</div>

<div class="foot">
<span>Blume v1.0.3 · MIT · Node.js 22.12+ · Astro + Vite</span>
<span>Interactive explainer by <a class="mtp" href="https://www.marktechpost.com" target="_blank" rel="noopener">Marktechpost</a></span>
</div>
</div>

// token positions per stage (cx, cy)
var pos = [
[85, 90], [250, 90], [470, 90], [700, 70], [700, 163], [842, 90]
];

var steps = [
{ label: "Stage 1 / 6", title: "A folder of Markdown", term: "docs/ index.mdx guide.mdx api.mdx",
text: "You start with .md or .mdx files in a folder. There is no starter to clone and no app boilerplate to maintain." },
{ label: "Stage 2 / 6", title: "The CLI loads your config", term: "blume dev ✓ loaded blume.config.ts",
text: "blume dev loads blume.config.ts. It reads your content sources, theme tokens, and options, all type-checked by a schema." },
{ label: "Stage 3 / 6", title: "Content is scanned into a graph", term: "scanning content … ✓ 3 pages, nav inferred",
text: "Blume scans every page into a content graph. Navigation is inferred from your files, so you rarely hand-write it." },
{ label: "Stage 4 / 6", title: "A hidden Astro project is generated", term: "writing .blume/ ✓ only changed files",
text: "Blume writes a hidden Astro project into .blume/. It regenerates each run, rewriting only changed files, so hot reload stays fast." },
{ label: "Stage 5 / 6", title: "Astro + Vite render the pages", term: "rendering via catch-all route ✓",
text: "Astro renders every page through one catch-all route. It imports Blume’s components, the generated data, and any overrides you add." },
{ label: "Stage 6 / 6", title: "Static HTML ships to dist/", term: "blume build ✓ dist/ + search index",
text: "The build outputs static HTML and a local search index into dist/. The core theme ships no client framework JS, helping Core Web Vitals." }
];

var current = -1;
var playing = false;
var playTimer = null;

function moveToken(i) {
if (i < 0) { token.style.opacity = 0; return; }
token.style.opacity = 1;
token.style.transition = "cx .55s cubic-bezier(.4,0,.2,1), cy .55s cubic-bezier(.4,0,.2,1)";
token.setAttribute("cx", pos[i][0]);
token.setAttribute("cy", pos[i][1]);
}

function next() { if (current < steps.length – 1) render(current + 1); }
function prev() { if (current > 0) render(current – 1); }

runBtn.addEventListener("click", function () {
if (playing) { stop(); }
else { if (current >= steps.length – 1) render(-1); play(); }
});
nextBtn.addEventListener("click", function () { stop(); next(); });
prevBtn.addEventListener("click", function () { stop(); prev(); });
resetBtn.addEventListener("click", function () { stop(); render(-1); });

aiToggle.addEventListener("click", function () {
var on = aiToggle.classList.toggle("on");
aiNodes.forEach(function (n) {
n.style.opacity = on ? 1 : 0.18;
var r = n.querySelector("rect");
r.setAttribute("stroke", on ? "#7a4a1e" : "#33281f");
});
aiBranches.forEach(function (b) {
b.style.opacity = on ? 1 : 0.15;
b.setAttribute("stroke", on ? "#7a4a1e" : "#33281f");
});
reportHeight();
});

// auto-resize for WordPress embed (component offsetHeight + buffer)
function reportHeight() {
try {
var h = root.offsetHeight + 40;
if (window.parent) {
window.parent.postMessage({ type: "blume-explainer-height", height: h }, "*");
}
} catch (e) {}
}
window.addEventListener("load", reportHeight);
window.addEventListener("resize", reportHeight);

render(-1);
})();
</script>
</body>
</html>
“>

Getting Started

Setup takes a single command, so onboarding is short.

Copy Code

npx blume init

Afterward, blume dev starts a hot-reloading server. Meanwhile, blume build writes static HTML and a local search index into dist/. The config file is real TypeScript, validated by a schema.

Copy Code

// 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:

CommandPurposeblume initScaffold a project, interactive by defaultblume devStart the dev server with hot reloadblume buildBuild the static or server siteblume addInstall a source component from the registryblume syncRe-fetch remote content sourcesblume ejectPromote the runtime into a standalone Astro appblume validateCheck internal, anchor, asset, and external linksblume doctorDiagnose 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.

Copy Code

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.

DimensionBlumeMintlifyDocusaurusAstro StarlightTypeOpen-source CLI + frameworkHosted commercial platformOpen-source SSGOpen-source Astro themeLicenseMIT, freeProprietary; paid Pro tierMIT, freeMIT, freeSetupZero-config Markdown folderConfig-driven, managedScaffold + React configAstro project + themeEngineHidden Astro + ViteProprietary hostedReactAstroCore-theme client JSNone (static HTML)—React runtimeMinimal (islands)llms.txt / llms-full.txtBuilt-in flagAuto-generatedCommunity pluginCommunity pluginBuilt-in MCP serverYes (four read-only tools)Yes (auto-hosted)Not built-inNot built-inEject pathStandalone Astro appNot 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 Twitter and don’t forget to join our 150k+ML SubReddit and Subscribe to our Newsletter. 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

The post Meet Blume: An Open-Source, Zero-Config Documentation Framework That Ships AI-Ready Docs From a Markdown Folder appeared first on MarkTechPost.

Source link