Blume 中文文档

博客

给页面标记为博客类型，Blume 就会自动为它加上 RSS 订阅源和更完整的文章元数据，落地页则由你自己编排

更新日志

把每次发布写成一个标记为 changelog 类型的内容文件，Blume 就会把它汇入自动生成的索引页和 RSS 订阅源

自定义页面

在 pages 目录下放一个 .astro 文件即可挂载真实路由，从 blume:data 读取站点数据，并在完整文档布局与落地页布局之间选择

技能

Blume 随包提供的 agent 技能：帮你搭脚手架、迁移旧站点、让文档跟上产品，以及为你自己的站点编写技能

命令行

blume 命令行工具的全部子命令与通用选项，以及如何让构建和校验在开发服务器运行时互不干扰

审查

在构建之后审查 dist/ 中的 HTML，报告 SEO 与站点健康问题，并把每条发现指向具体的源文件和 frontmatter 行

doctor

与构建做完全相同的扫描，报告配置、内容、依赖包和密钥上的问题，并给出项目最终解析出的配置摘要

eval

让一个 AI agent 仅凭你的文档回答真实用户问题，以此测试文档是否真的够用

translate

用本地 agent CLI 把文档翻译到已配置的语言，并通过一份随代码提交的台账跟踪哪些译文已经过期

validate

像构建那样读取内容并检查每一处链接，把站内链接、锚点、资源与外链问题按诊断码报告出来

version

把当前文档冻结为一份归档版本快照，重写副本内的站内链接，并在配置中注册版本 id

配置

blume.config.ts 的全部选项：站点信息、内容、frontmatter、GitHub、SEO、部署与功能开关

分析

通过适配器接入 PostHog、Mixpanel、Amplitude、Segment 等二十多种分析服务，也可用 script() 接入任意脚本

助手

页面内聊天助手，由流式服务端端点与 AI SDK 支撑，可切换到 OpenAI、Anthropic、Gemini 等多种模型后端

Cookie 同意

在分析脚本运行前先询问读者，支持 Blume 自带横幅、Osano 与 Ethyca 三种同意管理器

定制

用 components.ts 覆盖组件与布局插槽，接入交互岛、Astro 集成与 eject

导出

在目录下方为读者提供 PDF 与 EPUB 导出能力，完全在客户端完成

朗读

为每个页面加一个「收听本页」播放器，可用读者设备自带的浏览器语音，也可在构建时生成语音

速率限制

按 IP 限制读者调用服务端路由的频率，含 memory、Upstash 与 Cloudflare 三种适配器

搜索

内置本地搜索，无需托管服务和 API key，可在 Orama、Pagefind、Algolia 等适配器间切换

主题

用 token 驱动的主题覆盖亮色与暗色模式，含字体、暗色配色与设计 token

内容

文档就是一个装满 Markdown 和 MDX 文件的文件夹

组件

Blume 内置组件总览，涵盖卡片、步骤、标签页、徽章、类型表格、代码组等

Frontmatter

逐页面的 frontmatter 字段参考，涵盖布局、侧边栏、SEO、搜索以及自定义键。

国际化

用 i18n 配置多语言路由、语言切换器、按语言导航与本地化 SEO

包含片段

用语句在构建时把另一个文件的内容嵌入任意页面，并给片段传入属性。

交互岛

用 islands 目录或 defineComponents 添加只为自身、按需加载 JavaScript 的交互组件

Meta 配置

用 meta.ts 控制每个内容文件夹在侧边栏中的分组外观与子项顺序。

内容来源

从本地文件、远程仓库、CMS 或任意自定义后端拉取文档 —— 并把多个来源混进同一个静态优先的站点，全部在构建期读取

Contentful

通过 Content Delivery API 读取内容类型，无需额外安装任何依赖。

自定义内容源

用 custom() 接入带自定义序列化器或非内置后端的内容源

GitHub Releases

把仓库的 GitHub Release 变成更新日志条目，发布即更新日志。

Notion

导入 Notion 数据库，行变页面、属性变 frontmatter、块树变 MDX。

Obsidian

直接读取 Obsidian vault，wikilink 与图片在构建期解析，无需导出步骤。

Payload

通过 Payload REST API 读取集合，Lexical 正文降级为 Markdown。

远程 MDX

通过 HTTP 从 GitHub 仓库子树或 raw 基础 URL 抓取 Markdown 与 MDX。

Sanity

用 GROQ 查询拉取数据集，字段映射为 frontmatter、Portable Text 转为 Markdown。

Strapi

通过 Strapi REST API 读取 Strapi 4 与 Strapi 5 的内容类型。

语法

Blume 支持的 Markdown 与 MDX 语法参考，每一项都配实时预览和源码。

变量

在配置中定义一次值，即可在所有页面中通过 {{name}} 引用。

版本管理

用 versions 配置为文档站启用版本快照、版本切换器、SEO 与搜索范围控制

部署

部署到任意静态托管平台，或切换到服务端渲染

可发现性

让搜索引擎与 AI agent 都能读懂你的文档 —— 元数据、社交卡片、订阅源、结构化数据、llms.txt、Markdown、JSON API 与 MCP

智能体发现

Blume 用清单、Link 头、well-known 文件与 WebMCP 把文档站点的整片界面广告给智能体

JSON API

站点随附的只读 JSON API，供智能体和函数调用框架通过普通 HTTP 读取文档

llms.txt

为编码智能体和聊天助手生成 llms.txt 与 llms-full.txt 两份机器可读文档

面向智能体的 Markdown

每个页面都提供 .md 与 .mdx 原文、内容协商，以及自定义组件的 Markdown 序列化器

MCP 服务器

托管一个 Model Context Protocol 服务器，让编码智能体直接检索并阅读你的文档

元数据

每个页面自动渲染的 head 标签、Open Graph 卡片与 X 归属，以及逐页面的 SEO 覆盖

Open Graph 图片

在构建时为每个页面生成 1200×630 的社交卡片，并可自定义品牌、图层、字体与缓存

RSS 订阅源

为 blog 和更新日志生成 RSS 订阅源，并输出让阅读器自动发现的 link 标签

Sitemap 与 robots

构建时输出 sitemap.xml 与 robots.txt，并用 Content-Signal 声明内容供 AI 使用的范围

结构化数据

在每个页面的 head 中输出 schema.org JSON-LD，让搜索引擎读懂你的内容

常见问题

关于 Blume 的常见问题解答

Blume 文档

把 Markdown 或 MDX 丢进一个文件夹，就得到一个生产级文档站

迁移到 Blume

用一条命令把现有文档站迁移到 Blume

快速上手

用几条命令，从空文件夹到一个跑起来的文档站

API 页面

用 api frontmatter 手写端点文档，Blume 据此生成 Try it 面板、请求示例和响应示例

AsyncAPI 参考

把 AsyncAPI 规范渲染成原生事件参考，每个操作一个真实页面，带消息 schema 表与 Try it 消息编辑器

GraphQL 参考

从 GraphQL schema 生成原生 API 参考，每个根字段和每个具名类型各占一个页面，带参数、示例与 Try it 演练场

OpenAPI 参考

把 OpenAPI 规范渲染成原生 API 参考，每个接口一个真实页面，带 schema 表、代码示例和 Try it 演练场

Scalar

用 scalar() 适配器把 Scalar 自带的完整 API 参考界面嵌入单个路由，并可透传它的配置

升级到 Blume 2

从 Blume 1 升级到 Blume 2 的完整改动清单