Blume: Zero-Config Docs Framework That Turns a Markdown Folder into an AI-Ready Website

Blume：零配置文档框架，将 Markdown 文件夹转化为 AI 就绪网站

作者：Daniel Curtis · InfoQ 原文

摘要：Blume 是一个零配置的文档框架，能将 Markdown 文件夹渲染成完整的文档网站，并开源发布。它基于 Astro 和 Vite，具备自动 SEO 与 AEO、30+ 组件，无应用样板代码。其亮点包括 AI 就绪：自动生成 llms.txt、提供原始 Markdown、MCP 服务器支持，以及文档评测功能。与同类框架相比，Blume 强调开源、可任意托管、零客户端框架 JavaScript，并提供迁移工具。

Blume, a zero-config documentation framework that renders a folder of Markdown into a complete docs site, has been released as open source by Hayden Bleasel, pitched as "a world-class docs framework for everything you ship" with zero-config setup, automatic SEO and AEO, 30+ components and no app boilerplate to write.

Blume 是一个零配置的文档框架，能将一个 Markdown 文件夹渲染成完整的文档网站。它由 Hayden Bleasel 开源发布，号称是“适用于你所交付一切的顶级文档框架”，具备零配置、自动 SEO 与 AEO、30 多个组件且无需编写应用样板代码的特点。

Built on Astro and Vite and licensed MIT on GitHub, it has passed 1,300 stars and reached number seven on GitHub's TypeScript trending list.

该项目基于 Astro 和 Vite 构建，在 GitHub 上采用 MIT 许可证，已获得超过 1300 颗星，并跻身 GitHub TypeScript 趋势榜第七位。

The central claim is that the framework is the template, so there is nothing to clone.

核心主张是框架本身就是模板，因此无需克隆任何东西。

The CLI loads blume.config.ts, scans content into a graph and generates a hidden Astro project under .blume/ that it drives for dev and build.

CLI 加载 blume.config.ts，将内容扫描成图，并在 .blume/ 下生成一个隐藏的 Astro 项目，用于驱动开发和构建。

Node.js 22.12 or newer and one Markdown file are the only prerequisites, per the quickstart.

根据快速入门指南，前提条件仅为 Node.js 22.12 或更高版本以及一个 Markdown 文件。

npx blume init blume dev blume build

Configuration is opt-in and type-safe, validated by a schema through defineConfig: import { defineConfig } from "blume"; export default defineConfig({ title: "Acme Docs", deployment: { site: "<https://docs.example.com>" }, });

配置是可选的且类型安全，通过 schema 和 defineConfig 进行验证： import { defineConfig } from "blume"; export default defineConfig({ title: "Acme Docs", deployment: { site: "<https://docs.example.com>" }, });

Sites emit llms.txt and llms-full.txt, serve raw Markdown at any .md URL and can expose a hosted MCP server, while blume eval turns docs into a test suite: an agent answers user questions using only the documentation, a judge grades the answers and CI fails when the docs cannot answer.

网站会生成 llms.txt 和 llms-full.txt，在任何 .md URL 上提供原始 Markdown，并可暴露托管的 MCP 服务器；同时 blume eval 将文档转化为测试套件：一个代理仅使用文档回答用户问题，一个评判者对答案进行评分，当文档无法回答时 CI 会失败。

On GitHub, TimonVS asked for route-based page tabs for design system docs, noting that using Starlight had forced "an ugly component override of the PageTitle component".

在 GitHub 上，TimonVS 请求为设计系统文档提供基于路由的页面标签，并指出使用 Starlight 迫使“对 PageTitle 组件进行丑陋的组件覆盖”。

Bleasel shipped query-parameter tabs within a day: So the query-param version covers "shareable tab URL" and "multiple groups per page," but not "a separate indexed URL per tab."

Bleasel 在一天内交付了查询参数标签：因此，查询参数版本涵盖了“可共享的标签 URL”和“每页多个组”，但不包括“每个标签有单独的索引 URL”。

Other issues reported dark mode elements flickering during client-side navigation and incorrect font fallback for Vietnamese text.

其他报告的问题包括客户端导航期间深色模式元素闪烁，以及越南文字体的后备字体不正确。

Blume's own FAQ documents highlighted a formatting issue in Markdown with oxfmt collapses :::note directives onto a single line so they render as literal text, an upstream bug inherited from Prettier's Markdown printer, with a pinned patch as the workaround.

Blume 自己的 FAQ 文档强调了 Markdown 中的一个格式问题：oxfmt 会将 :::note 指令折叠成一行，导致它们渲染为纯文本，这是从 Prettier 的 Markdown 打印机继承的上游 bug，解决方案是使用固定的补丁。

The changelog describes a bundled blume-migrate skill for Mintlify, Docusaurus, Fumadocs, Nextra and Starlight that translates source config into blume.config.ts, restructures content into filesystem-derived navigation with redirects for every moved route, rewrites callouts to ::: directives, converts icons to Lucide and points generated API references at openapi.sources.

更新日志描述了一个内置的 blume-migrate 技能，适用于 Mintlify、Docusaurus、Fumadocs、Nextra 和 Starlight，它能将源配置转换为 blume.config.ts，将内容重构为基于文件系统的导航并为每个移动的路由提供重定向，将标注重写为 ::: 指令，将图标转换为 Lucide，并将生成的 API 引用指向 openapi.sources。

A third-party account exists too: PunGrumpy has written up moving Logixlysia from Fumadocs to Blume.

还有一个第三方案例：PunGrumpy 写了将 Logixlysia 从 Fumadocs 迁移到 Blume 的经验。

Against rivals, Blume's comparison table frames Mintlify as a hosted platform with a closed core, and Fumadocs, Nextra and Docusaurus as a library plus an app you scaffold and then maintain on a React runtime.

与竞争对手相比，Blume 的比较表将 Mintlify 描述为拥有封闭核心的托管平台，而 Fumadocs、Nextra 和 Docusaurus 则是库加上你需要搭建并在 React 运行时上维护的应用。

Blume claims the middle ground: open source, hostable anywhere, with only Markdown to own and a core theme that ships zero client framework JavaScript.

Blume 声称自己处于中间地带：开源、可任意托管、只需拥有 Markdown，以及一个不包含任何客户端框架 JavaScript 的核心主题。

Escape hatches include component overrides and blume eject, which promotes the generated runtime into a standalone Astro app.

逃生口包括组件覆盖和 blume eject，后者能将生成的运行时代码提升为独立的 Astro 应用。

Blume ranked second of the day on Product Hunt with 304 upvotes shortly after launch, and MarkTechPost covered it in July.

Blume 在发布后不久以 304 个赞在 Product Hunt 上获得当日第二名，MarkTechPost 在 7 月报道了它。

On the Product Hunt launch, someone asked: curious what "AI-ready" means concretely here - is it generating something like an llms.txt under the hood, or is it more about the markdown being cleanly chunked/structured for retrieval.

在 Product Hunt 发布时，有人问道：好奇这里的“AI 就绪”具体是什么意思——它是在底层生成像 llms.txt 这样的东西，还是更多关于将 Markdown 清晰分块/结构化以便检索。

To which Bleasel replied: Means lots of things - llms.txt, raw markdown via negotiation headers, mcp servers, agent readability, skills.

Bleasel 回复道：意味着很多事情——llms.txt、通过协商头的原始 Markdown、MCP 服务器、代理可读性、技能。

Blume is an open-source documentation framework distributed under the MIT license and maintained by Hayden Bleasel, an Australian design engineer whose other projects include Ultracite and Files SDK.

Blume 是一个开源文档框架，根据 MIT 许可证分发，由澳大利亚设计工程师 Hayden Bleasel 维护，他的其他项目包括 Ultracite 和 Files SDK。

It renders static HTML from a folder of Markdown on Astro and Vite, ships a core theme with no client framework JavaScript, and is available on npm, with documentation at useblume.dev.

它使用 Astro 和 Vite 从 Markdown 文件夹渲染静态 HTML，提供一个不含客户端框架 JavaScript 的核心主题，可在 npm 上获取，文档位于 useblume.dev。

阅读理解

1. What does Blume do to make documentation 'AI-ready' according to the article?

2. How does Blume handle the problem of formatting issues with `:::note` directives in Markdown?

3. What advantage does Blume claim over competitors like Mintlify, Fumadocs, and Nextra?

温故复习 →每日一句 →