Blume 2.0
Hayden Bleasel · Writing · Coding
Blume 2.0 is an open-source docs framework that turns a folder of Markdown into a fast Astro documentation site, with local search, API references, and an MCP server for coding agents.
About Blume 2.0
What Is Blume 2.0
Blume 2.0 is a documentation framework built on Astro and Vite. You put Markdown or MDX files in a docs/ folder, run one command, and get a site with navigation, search, syntax highlighting, and Open Graph images already wired. There's no app code to maintain and no dashboard to log into.
The second major version is mostly about configuration. Search, deployment, content sources, API references, analytics, and the assistant backend are now adapters that you import from blume/* subpaths and call in blume.config.ts. Machine-readable settings moved from ai to a new agents key. Your pages don't need edits, so an upgrade is a config job rather than a rewrite.
What separates Blume from other static docs generators is the second audience. Every site ships llms.txt, a Markdown mirror of each page, a read-only JSON docs API, and an optional MCP server, so a coding agent can read the same documentation a person reads. That surface is what turns a docs site into AI-ready docs rather than a static page. The tradeoff is that Blume is developer tooling. Writers who expect a hosted editor and a WYSIWYG panel will find a Git repository instead.
Getting Started
- Run
npx blume initin an empty folder. The CLI installs dependencies and addsdevandbuildscripts topackage.json. - Open
blume.config.tsand set the site name, URL, and any adapters you need for search, deployment, or analytics. - Drop Markdown files into
docs/. Folder structure becomes the URL path, and page order comes from filenames ormeta.tsfiles. - Start
npm run devto preview locally, thennpm run buildto produce the static output. - Optional: run
npx blume migrate <source> --codexto hand an existing Mintlify, Docusaurus, GitBook, or MkDocs site to a coding agent.
Product Information
A quick look at Blume 2.0's pricing, supported platforms, and performance.
Best for
The users, tasks, and scenarios where this tool fits best.
Users
- Developers documenting their own product
- Platform and API teams
- Maintainers of open-source projects
Tasks
- Publishing a Markdown docs site
- Making documentation readable by coding agents
- Migrating a docs platform
Scenarios
- A startup outgrows a README
- A product ships in several languages
- A support team keeps answering the same questions
Key features
Markdown-First Pages and Inferred Navigation
Folders become routes and filenames become slugs, so a new page is a new file. The sidebar builds itself from the directory tree, then takes refinements from frontmatter or a meta.ts file beside the pages. You can reorder a group, set an icon, or hide a page without touching a config file, and breadcrumbs and the right-hand outline follow the same structure.
Agent Surface With llms.txt and MCP
Every Blume site publishes llms.txt and an .md mirror for each route, which lets an agent fetch the source of a page instead of scraping rendered HTML. The optional MCP server exposes search and page reading as tools, and the site also serves a JSON docs API described by an OpenAPI 3.1 document. A /.well-known/ai-catalog.json manifest lets agent registries discover the site.
API References From Specs
Blume works as an API reference generator for OpenAPI, AsyncAPI, or GraphQL schemas, local or remote. Point the reference config at a spec and it renders an overview, per-operation pages, parameters, request bodies, and response tables. Code samples can be generated in 18 languages, from cURL and Python to Go, Ruby, and C#. Because the reference is built at build time, a schema change shows up in the next deploy.
Local Search and an In-Page Assistant
Search works with no API key through a local index, and it matches CJK and Thai text without word spaces. Larger sites can swap in Algolia, Typesense, Orama Cloud, Mixedbread, or Pagefind through an adapter. The assistant panel answers from the site's own pages, with provider adapters for the Vercel AI Gateway, OpenRouter, LLM Gateway, Inkeep, or any OpenAI-compatible endpoint.
Localization and Versioned Docs
Locale folders produce language-prefixed routes, per-language navigation, and translated interface strings, and blume translate fills in missing languages. Versioning freezes a snapshot directory per release, adds a version switcher, and keeps search scoped to the selected version. Both features apply to the agent surface as well, so an agent sees the same routes a reader does.
Checks, Audit, and Eject
blume validate checks links, anchors, and frontmatter before a deploy. blume audit reads the built HTML and reports SEO problems with the source file and line. blume eval runs a reader and a judge agent against the docs to test whether answers are actually findable. If you outgrow the framework, blume eject turns the hidden project into a standalone Astro app you own.
Pros and cons
Pros
- The MIT license covers unlimited editors, pages, and traffic, so cost stays at hosting plus whatever you spend on model tokens.
- Zero-config start: `npx blume init` produces a working site with search, navigation, and OG images before you write any config.
- The agent surface is built in rather than bolted on, which saves the separate `llms.txt` and MCP work most docs teams now need.
- Adapters cover the boring choices, from Algolia and Typesense to Vercel, Netlify, Cloudflare, PostHog, and Plausible.
- CLI checks and `eject` give an exit path, so the framework isn't a lock-in decision.
Cons
- Blume 2.0 is a breaking config release. Projects that set search, deployment, sources, or the assistant must rewrite those blocks as adapter calls, and a large config takes an afternoon.
- There's no hosted editor or dashboard. Writers without Git experience depend on developers or a CMS source, which is a real cost for marketing teams.
- It needs Node.js 22.19 or newer, so older CI images fail until someone updates the runtime.
- AI features bill the model provider directly. The framework is free, but a busy assistant or narration build adds a variable monthly cost.
Frequently asked questions
Blume 2.0 is the second major release of an open-source documentation framework for Astro. It generates a docs site from Markdown or MDX files and adds search, API references, localization, versioning, and an agent-readable surface.
Related content
Explore related tools, skills, and articles for Blume 2.0.
Blume 2.0 Alternatives
Google EmbeddingGemma 2
Google DeepMind · Writing · Image · CodingGoogle EmbeddingGemma 2 is a 740M-parameter open model that turns text, code, images, audio, and video frames into vectors in one 768-dimension space, running on phones and laptops.
MePersona
MePersona, Inc. · Writing · Productivity · MarketingMePersona is an AI unified inbox for creators. It learns your voice, drafts replies to fan messages from 12 platforms, and sends only what you approve.
Fluence
Yay Software (Yannick Huchard) · Writing · Voice & Language · ProductivityFluence is an Android app that reads PDFs, EPUBs, Word files and web articles aloud, follows each sentence as it speaks, and answers questions about the text on the phone itself.