Blume: a zero-config docs generator that hides its Astro project

The problem Blume solves, and who it is actually for

Documentation sites have a recurring cost problem. You pick a generator, then spend the next year maintaining the app around it: navigation config, theme tokens, search indexing, Open Graph images, sitemap generation. The generator is the easy part. The plumbing is what rots.

Blume's answer is to remove the app from your repository entirely. The README states that you drop Markdown or MDX into a folder, run `blume dev`, and get navigation, search, theming, Open Graph images and a component library with no app boilerplate to write or maintain. Configuration is opt-in, one file at a time.

The audience is narrow and specific. This is for teams whose docs are the product surface but not the product: SDK vendors, API platforms, internal tooling groups. It is not for people who want to write Astro components as their primary job. The README is explicit that Blume works with any package manager and never requires you to set up Astro or Tailwind yourself, which is only a benefit if you did not want to in the first place.

How the hidden .blume/ project is generated and driven

The mechanism matters more than the feature list, because it determines what you can debug.

According to the README's How it works section, the 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, with only changed files written, so hot reload stays reasonably fast. That last detail is the interesting design choice: the generator is incremental, not a full rewrite, which is why dev feels like a normal dev server rather than a build loop.

The escape hatch is `blume eject`, which the README describes as producing a standalone Astro project that still uses the `blume` package. Note the qualifier. Eject gives you ownership of the app directory, not independence from the library. If your reason for ejecting is to remove Blume from the dependency tree, this does not do that.

Config is real TypeScript. `blume.config.ts` and every `meta.ts` are validated by a schema and authored with `defineConfig` and `defineMeta`, so type errors surface in the editor rather than at build time. For a tool that generates code you do not read, that type checking is the main safety net you get.

Installing Blume and building a first site

Blume requires Node.js 22.12 or newer and a content folder with at least one `.md` or `.mdx` file. The README presents that as the whole prerequisite list.

The scaffold command is interactive by default. Run it in an empty directory and answer the prompts:

npx blume init

You should end up with a project directory containing your content folder and, if you accepted the defaults, a config file. Start the dev server with hot reload:

blume dev

The README does not state the default dev port, so check the terminal output rather than assuming one.

When you are ready to ship, build static HTML with a local search index into `dist/`:

blume build

Deployment depends on whether you need request-time features. A static build goes to any static host, and the README names Vercel, Netlify, Cloudflare Pages, GitHub Pages, and S3 with CloudFront. Ask AI and the hosted MCP server are request-time features, so they require switching to server output and selecting an adapter. The README lists four: `vercel`, `netlify`, `node`, and `cloudflare`. On Vercel, Netlify, and Cloudflare Pages the matching adapter and site URL are detected automatically.

Before you commit content, two diagnostic commands are worth knowing. `blume doctor` diagnoses config and content problems, and `blume validate` validates internal, anchor, asset, and external links. Run both against real content, not the scaffold, because the scaffold has nothing to break.

Search backends, content sources, and what the abstraction costs

Blume ships Orama as the default search backend, running in both dev and production with no hosted service. That is a genuine deployment simplification: no index API keys, no per-query billing, no third-party availability in your critical path. The README lists FlexSearch, Pagefind, Algolia, Typesense, Orama Cloud, and Mixedbread as one setting away, which covers the case where local search stops being enough.

Content sources are where the design gets ambitious. The README says you can mix local files with remote MDX, GitHub Releases, Notion, Sanity, or any custom backend into a single site. `blume sync` re-fetches remote content sources and regenerates. That is a real capability, but it is also the point where a zero-config tool stops being zero-config. Remote sources introduce credentials, rate limits, and network failures into what was previously a local build. The README does not document rollback behaviour when a remote source is unreachable, and it does not describe caching semantics for `blume sync`. If your build depends on Notion being up, you should establish that behaviour yourself before you rely on it.

The AI surface is similarly broad: `llms.txt` and `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 that the README says lets coding agents search and read your docs directly. Blume also ships agent skills that teach a coding agent to scaffold, write, and maintain the site. Whether that is valuable depends entirely on whether your team already uses coding agents against documentation. If it does not, these are features you will not exercise.

Where Blume is the wrong tool

The hidden `.blume/` directory is the central trade-off, and it cuts both ways. Because the directory is regenerated on each run, hand-editing anything inside it is pointless. The README does not document what happens to manual changes in `.blume/` across runs, but given the regeneration model, the safe reading is that they are lost. Everything you want to keep must live in your content, your config, or your overrides.

That makes Blume a poor fit for teams that treat the docs site as an application. If you need custom routing, a bespoke data layer, or components that reach into build internals, you will spend more time fighting the generated project than you would have spent writing an Astro app. The README's own framing acknowledges this: eject exists precisely for the moment you want full control, and the fact that it exists is an admission that the default path has a ceiling.

The second limitation is versioning. `blume version [id]` freezes the current docs as an archived version, and running it without an id lists configured versions. That is a snapshot mechanism, not a branching or maintenance model for old releases. Teams that maintain several live documentation versions with backported fixes should check how the archived versions are stored and updated, because the README describes freezing, not ongoing maintenance of frozen versions.

The third is Node 22.12 or newer. That is a hard floor stated in both the README and the repository's `engines` field. If your CI images or build containers are pinned below it, this is a migration before it is a docs tool.

Blume against writing your own Astro docs site

The honest alternative is not another generator. It is Astro itself, which Blume already uses underneath.

The difference in approach is ownership. With a hand-written Astro project you choose the routing, the search integration, the theme layer, and the upgrade cadence, and you pay for that with the work of building and maintaining all of it. Blume inverts the arrangement: it generates the Astro project for you, ships the components, and regenerates the runtime on each run so you never have to reconcile your copy with upstream changes. The README's claim that the core theme ships no client framework JavaScript and that pages score well on Core Web Vitals out of the box is a direct consequence of that control. You get the performance defaults without having configured them.

A second alternative is to stay with your existing generator and add only the pieces Blume provides that you lack. If you already have search, SEO metadata, and a component library you like, the migration cost is real and the gain is mostly the removal of configuration you have already written.

The comparison that decides it is upgrade cost. With a hand-written Astro app, an Astro major version is your problem. With Blume, it is the maintainer's problem, and you take the fix on the next release. The repository shows a Changesets setup and a release workflow, with three releases in August 2026, the most recent on 2026-08-20. That cadence is the thing you are buying.

Maintenance, licence, and what to verify before adopting

The repository is not archived, and the last push was on 2026-08-20. Recent releases are `[email protected]`, `[email protected]`, and `[email protected]`, all in August 2026. The project is published to npm and the repository is a Turborepo monorepo with the package in `packages/blume` and Blume's own documentation in `apps/docs`, built with Blume. That self-hosting is a useful signal: the maintainer runs the tool on its own docs.

The licence is MIT, with copyright held by Hayden Bleasel. In practical terms that permits commercial use, modification, and redistribution provided the licence and copyright notice are retained. It does not include a patent grant, which some organisations require. That is a fact about MIT, not legal advice, and your own counsel should make the call.

Upgrade cost is the part most teams underestimate. Because `.blume/` is regenerated, minor and patch upgrades should be low-friction: you pull the new package version and the generated project changes with it. The friction arrives at major versions of the underlying Astro dependency, which the repository pins at `^7.3.2` in devDependencies. If you have ejected, you own that upgrade path yourself, and the README's note that an ejected project still uses the `blume` package means you are tracking both the package and the Astro version it expects.

Verify three things before you commit. First, run `blume doctor` and `blume validate` on your actual content, not a scaffold, since link validation is where real documentation usually fails. Second, run `blume build` and inspect `dist/` to confirm the search index and `llms.txt` files are generated the way you need. Third, if you plan to use remote content sources, test `blume sync` with a source deliberately made unreachable, because the README does not describe what happens then.

Editorial conclusion

Adopt Blume if you want a Markdown folder to become a docs site without maintaining an Astro app, and if you are willing to run Node 22.12 or newer. Do not adopt it if you need a framework you can read and patch from day one, or if you cannot accept that .blume/ is regenerated on every run. Before committing, run blume doctor and blume validate against your real content, then blume build and inspect dist/ for the search index and llms.txt output. The MIT licence lets you modify and redistribute the package, but the ejected project still depends on blume, so check that arrangement against your own policy rather than assuming the eject is a clean break.

Frequently asked questions

Official sources

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