Blume: Docs as a folder, with a hidden Astro project underneath

What Blume solves and who it is for

Blume solves a specific pain: setting up a docs site usually means choosing a framework, wiring navigation, adding search, configuring themes, and maintaining boilerplate. Blume removes all of that. You drop Markdown or MDX files into a folder, run blume dev, and get a site with navigation, search, theming, Open Graph images, and a component library. The README says there is nothing else to set up beyond Node.js 22.12 or newer and at least one .md or .mdx file. This is for teams that want documentation without a dedicated frontend engineer, or for open source projects that want a docs site without maintaining a separate app. It is also for people who want AI-ready features like llms.txt and a hosted MCP server without building them. The zero-config claim is strong, but it comes with a cost: the framework is hidden, and you only get control by ejecting.

How the hidden Astro project works

The mechanism is straightforward. The Blume CLI loads a blume.config.ts file, scans your content into a graph, and generates a hidden Astro project under a .blume directory. Astro renders through a catch-all page that imports Blume's shipped components, the generated data, and your overrides. The .blume directory is regenerated on each run, and only changed files are written, which keeps hot reload fast. This design means you never see the Astro config until you run blume eject, which promotes the runtime into a standalone Astro app. The trade-off is clear: you trade control for convenience. If you need to tweak the Astro build pipeline, you must eject, and then you own the generated project. The README notes that .blume is regenerated each run, so any manual edits there would be overwritten. That is a real constraint to know before you start.

Getting started: real commands and config

The quickstart is minimal. Run npx blume init to scaffold a project, then blume dev for a dev server with hot reload, and blume build to output static HTML into dist/. The build includes a local search index. Configuration is opt-in and TypeScript-based: blume.config.ts and every meta.ts file are real TypeScript, validated by a schema, and authored with defineConfig and defineMeta. This means your editor catches mistakes before a build. The CLI has more commands: blume add installs a source component from a registry, blume sync re-fetches remote content sources, blume validate checks internal and external links, blume audit checks the built site for SEO issues, and blume eval tests the docs by having an agent answer questions using only the documentation. There is also blume translate, which uses a local agent CLI to translate docs into configured locales. For a zero-config tool, the CLI surface is surprisingly deep.

Search and AI features: local by default, hosted optional

Search is local by default using Orama, which runs in dev and production with no hosted service. That is a meaningful privacy and cost advantage. If you need different search, the README lists FlexSearch, Pagefind, Algolia, Typesense, Orama Cloud, and Mixedbread as one setting away. The AI-ready features are a major selling point: llms.txt and llms-full.txt files, 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. There are also agent skills that teach a coding agent to scaffold, write, and maintain your docs site. The MCP server is hosted, which means it is not self-contained; if you need to keep everything on your own infrastructure, that is a limitation. The local search index is built at build time, so static builds stay static for the core site, but request-time features like Ask AI require server output.

Content sources and internationalization: mixing local and remote

Blume is not limited to local files. You can mix local files with remote MDX, GitHub Releases, Notion, Sanity, or any custom backend into a single site. That is useful for projects that keep docs in a CMS or pull release notes from GitHub. The sync command re-fetches remote content sources, which suggests a workflow where you update remote content and then run blume sync. Internationalization is handled by dropping translated files into place, with locale-aware routing, per-language navigation, translated UI, and SEO. This is a practical approach, but it relies on your content being organized in a way that supports translation files. The README does not detail the exact file structure for i18n, so you would need to check the docs. The remote content sources add complexity, and the eval and translate commands show that Blume is leaning into agent-driven workflows.

The eject escape hatch and customization limits

The most important design decision is the hidden Astro project. You do not own it until you run blume eject, which produces a standalone Astro app that still uses the blume package. That is a clever middle ground: you get zero-config defaults, but you can take the wheel later. However, the README warns that .blume is regenerated on each run, so any changes you make there before ejecting are lost. That means you cannot safely customize the generated project in place. You must either stay within Blume's customization options (component overrides, React islands, custom pages, Tailwind v4 theme tokens, theme.css, and a source-component registry via blume add) or eject and own the whole thing. For a team that needs a specific Astro plugin or a nonstandard build step, ejecting is the only path, and that means you are now maintaining an Astro project, which defeats the zero-config promise. This is a genuine trade-off to weigh.

Limitations and the wrong tool cases

Blume requires Node.js 22.12 or newer. That is a hard floor; if your CI or local environment is on an older LTS, you cannot run it. The README also lists adapters for Vercel, Netlify, Node, and Cloudflare, but only for server output. If you want a purely static site, you do not need an adapter, but you also cannot use request-time features like Ask AI or the MCP server. Another limitation: the hosted MCP server means your docs content is processed by a third party for that feature, which may be unacceptable for private or sensitive documentation. Blume is the wrong tool if you need a docs site that is deeply integrated into an existing Astro or Tailwind setup from the start, because the zero-config approach hides those details. It is also wrong if you need to support an older Node version or if you want to avoid any generated directory in your repo. The eval command is interesting but it depends on an agent, so it is only as good as the model and the docs content.

Alternatives and how they differ

The most direct alternative is Docusaurus, a React-based docs generator that also uses Markdown and MDX. Docusaurus requires you to set up a project with a config file and a build pipeline, and it does not hide the framework. You own the React app from day one, which gives you full control but also means you maintain more boilerplate. Blume's approach is the opposite: it hides Astro and Vite, and you only see them if you eject. Another alternative is VitePress, which is Vue-based and also zero-config-ish, but it does not generate a hidden project; it uses a config file and a theme system that you can override directly. VitePress also has a local search, but it does not have the same AI-ready features like MCP or agent skills out of the box. The key difference is ownership: Blume offers a generated project that you can eject, while Docusaurus and VitePress give you the project structure immediately. If you want to avoid framework lock-in, Blume's eject path is a different trade-off.

Maintenance, upgrade cost, and license

The project is MIT licensed, which is permissive and allows commercial use without restrictions beyond preserving the copyright notice. The repository is a monorepo with the published package in packages/blume and the docs site in apps/docs, built with Blume itself. That dogfooding is a good sign for maintenance, but it does not guarantee stability. The last push was August 2026, with releases 1.5.1, 1.5.2, and 1.5.3 in the same week, which suggests active development. Upgrade cost is low at the package level: you update the blume package and rerun blume build. However, if you have ejected, you are maintaining a standalone Astro project, and upgrading Blume may require reconciling your ejected code with the new package version. The README does not document a migration path for ejected projects, so you should verify that before relying on eject. The generated .blume directory is meant to be regenerated, so you do not commit it, but you do need to ensure your CI can run blume build with the required Node version. The maintenance burden is on the package itself, and the monorepo structure suggests the author is actively iterating.

Editorial conclusion

Adopt Blume if you want a docs site from a folder of Markdown or MDX with no framework setup, and you are comfortable with Node 22.12+ and a generated .blume directory you do not edit. Do not adopt it if you need to customize the build pipeline before launch, if your team cannot commit to the Node version floor, or if you want full control over the Astro project from day one. Before adopting, verify that blume eject produces a project your team can maintain, that the remote content sources you need (Notion, Sanity, GitHub Releases) work with your authentication model, and that the server adapters for request-time features like Ask AI cover your host. The core promise is real: a folder of docs is a complete project, and you can always run blume eject to take ownership.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes