Blume Hides the Astro Project So a Folder of Markdown Is the Entire Docs Site

The pitch is that a docs site should not be an app you maintain. This is a 19-second screen recording that scrolls the GitHub README for haydenbleasel/blume, then the live docs at useblume.dev, then the feature list. Blume takes a folder of .md or .mdx files and generates a production docs site with navigation, local search, theming, Open Graph images, and typed config, without you owning a framework project. It generates and drives a hidden Astro project on your behalf. The interesting part is not the generator, it is what it exposes to coding agents by default.

One Command, Nothing to Clone

The README's first claim is that a folder of docs is a complete project. No starter template to clone, no upstream to keep in sync with. npx blume init scaffolds, blume dev runs a hot-reloading server, blume build emits static HTML with a local search index into dist/. The only prerequisites are Node 22.12 or newer and at least one Markdown file. Navigation is inferred from the file tree rather than declared in a sidebar config, which removes the most common source of docs-site drift: the nav file that stops matching the files.

Config Is Opt-In and Typed

Configuration exists, it just is not required to start. blume.config.ts and every meta.ts are real TypeScript, validated against a schema and authored with defineConfig and defineMeta, so the editor catches mistakes before a build rather than during one. The README's phrasing is that configuration is opt-in, one file at a time. Search, theming, and OG images are on by default, and you reach for config only when a default is wrong for you.

Search Runs Locally by Default

Orama runs in both dev and production with no hosted service. That means the default install has working full-text search on a static host, which is the step most docs generators leave to the reader. If you outgrow it, FlexSearch, Pagefind, Algolia, Typesense, Orama Cloud, and Mixedbread are each one setting away. The design pattern here is worth noting on its own: ship the zero-dependency option as the default and make the hosted upgrade a config value rather than a migration.

The Agent Surface Is the Real Differentiator

Plenty of tools turn Markdown into a docs site. What separates Blume is that the output is addressed to coding agents as a first-class audience. It emits llms.txt and llms-full.txt, serves raw Markdown at any .md URL, offers Copy as Markdown and Open in chat, includes an optional Ask AI assistant, and runs a hosted MCP server so agents can search and read your docs directly. It also ships agent skills that teach a coding agent to scaffold, write, and maintain the docs site itself. That closes a loop most teams currently run by hand: the agent that writes your code can read your docs and update them in the same session.

Components, API References, and an Escape Hatch

Beyond the basics there are 30-plus accessible components usable in any .mdx page with nothing to import, covering callouts, cards, steps, tabs, file trees, code groups, Mermaid diagrams, and KaTeX math. Drop in an OpenAPI or AsyncAPI spec and it renders an interactive reference with a live playground, powered by Scalar and themed to match. Content can mix local files with remote MDX, GitHub Releases, Notion, or Sanity in one site, and internationalization ships in the box. The escape hatch is blume eject, which converts the hidden Astro project into a standalone Astro app you own outright. That is the answer to the obvious objection about a generator you cannot see into.

Key Takeaways

• Inferring navigation from the file tree kills the most persistent docs-site maintenance task, which is keeping a sidebar config in sync with reality.
• Typed config validated by a schema means config errors surface in the editor rather than at build time, which is a meaningful difference on a docs site nobody builds locally.
• Local search by default with hosted providers as a one-line swap is a good template for any tool with a paid upgrade path: never make the upgrade a migration.
• The llms.txt, raw-Markdown, and hosted-MCP surface treats coding agents as readers, not an afterthought, which is currently rare among docs generators.
• blume eject de-risks adoption, since the hidden Astro project is recoverable rather than a lock-in point.
• The project moves fast. The video captures v1.1.2 at 755 stars in July 2026; the repo now shows 1.6k stars and npm is on 1.6.x, so check the changelog before relying on any specific behavior described here.

Resources

• haydenbleasel/blume — the repository, MIT licensed
• useblume.dev — documentation, quickstart, component reference, and changelog, built with Blume itself
• blume on npm — the published package
• Astro — the framework Blume generates and drives behind the scenes
• Orama — the default local search engine, open source and runs client-side
• Scalar — powers the interactive OpenAPI and AsyncAPI references
• Model Context Protocol — the standard behind Blume's hosted MCP server for coding agents