# Blume 中文文档

> 面向人类与智能体的开源文档框架（Blume）的简体中文完整镜像。
> 框架本身即模板：把 Markdown 或 MDX 丢进一个文件夹即可得到生产级文档站点。

英文原文：https://useblume.dev/docs
本翻译由社区维护，以英文原文为准。

## 开始

- [介绍](https://blume.ndjp.net/docs/): 把 Markdown 或 MDX 丢进一个文件夹，就得到一个生产级文档站
- [快速开始](https://blume.ndjp.net/docs/quickstart/): 用几条命令，从空文件夹到一个跑起来的文档站
- [部署](https://blume.ndjp.net/docs/deployment/): 部署到任意静态托管平台，或切换到服务端渲染
- [迁移到 Blume](https://blume.ndjp.net/docs/migrating/): 用一条命令把现有文档站迁移到 Blume
- [升级到 Blume 2](https://blume.ndjp.net/docs/upgrading/): 从 Blume 1 升级到 Blume 2 的完整改动清单
- [常见问题](https://blume.ndjp.net/docs/faq/): 关于 Blume 的常见问题解答

## 内容

- [页面](https://blume.ndjp.net/docs/content/): 文档就是一个装满 Markdown 和 MDX 文件的文件夹
- [导航](https://blume.ndjp.net/docs/content/navigation/): 侧边栏、分组、标签页、面包屑与页面操作，涵盖导航结构的全部可配置项。
- [文件夹元数据](https://blume.ndjp.net/docs/content/meta/): 用 meta.ts 控制每个内容文件夹在侧边栏中的分组外观与子项顺序。
- [Frontmatter](https://blume.ndjp.net/docs/content/frontmatter/): 逐页面的 frontmatter 字段参考，涵盖布局、侧边栏、SEO、搜索以及自定义键。
- [语法](https://blume.ndjp.net/docs/content/syntax/): Blume 支持的 Markdown 与 MDX 语法参考，每一项都配实时预览和源码。
- [引入](https://blume.ndjp.net/docs/content/includes/): 用 <include> 语句在构建时把另一个文件的内容嵌入任意页面，并给片段传入属性。
- [变量](https://blume.ndjp.net/docs/content/variables/): 在配置中定义一次值，即可在所有页面中通过 {{name}} 引用。
- [组件](https://blume.ndjp.net/docs/content/components/): Blume 内置组件总览，涵盖卡片、步骤、标签页、徽章、类型表格、代码组等
- [交互组件](https://blume.ndjp.net/docs/content/islands/): 用 islands 目录或 defineComponents 添加只为自身、按需加载 JavaScript 的交互组件
- [国际化](https://blume.ndjp.net/docs/content/i18n/): 用 i18n 配置多语言路由、语言切换器、按语言导航与本地化 SEO
- [版本控制](https://blume.ndjp.net/docs/content/versioning/): 用 versions 配置为文档站启用版本快照、版本切换器、SEO 与搜索范围控制

## 内容来源

- [内容来源总览](https://blume.ndjp.net/docs/content/sources/): 从本地文件、远程仓库、CMS 或任意自定义后端拉取文档 —— 并把多个来源混进同一个静态优先的站点，全部在构建期读取
- [Obsidian](https://blume.ndjp.net/docs/content/sources/obsidian/): 直接读取 Obsidian vault，wikilink 与图片在构建期解析，无需导出步骤。
- [远程 MDX](https://blume.ndjp.net/docs/content/sources/remote-mdx/): 通过 HTTP 从 GitHub 仓库子树或 raw 基础 URL 抓取 Markdown 与 MDX。
- [GitHub Releases](https://blume.ndjp.net/docs/content/sources/github-releases/): 把仓库的 GitHub Release 变成更新日志条目，发布即更新日志。
- [Sanity](https://blume.ndjp.net/docs/content/sources/sanity/): 用 GROQ 查询拉取数据集，字段映射为 frontmatter、Portable Text 转为 Markdown。
- [Notion](https://blume.ndjp.net/docs/content/sources/notion/): 导入 Notion 数据库，行变页面、属性变 frontmatter、块树变 MDX。
- [Contentful](https://blume.ndjp.net/docs/content/sources/contentful/): 通过 Content Delivery API 读取内容类型，无需额外安装任何依赖。
- [Payload](https://blume.ndjp.net/docs/content/sources/payload/): 通过 Payload REST API 读取集合，Lexical 正文降级为 Markdown。
- [Strapi](https://blume.ndjp.net/docs/content/sources/strapi/): 通过 Strapi REST API 读取 Strapi 4 与 Strapi 5 的内容类型。
- [自定义来源](https://blume.ndjp.net/docs/content/sources/custom/): 用 custom() 接入带自定义序列化器或非内置后端的内容源

## 配置

- [配置文件](https://blume.ndjp.net/docs/configuration/): blume.config.ts 的全部选项：站点信息、内容、frontmatter、GitHub、SEO、部署与功能开关
- [主题](https://blume.ndjp.net/docs/configuration/theming/): 用 token 驱动的主题覆盖亮色与暗色模式，含字体、暗色配色与设计 token
- [自定义](https://blume.ndjp.net/docs/configuration/customization/): 用 components.ts 覆盖组件与布局插槽，接入交互岛、Astro 集成与 eject
- [搜索](https://blume.ndjp.net/docs/configuration/search/): 内置本地搜索，无需托管服务和 API key，可在 Orama、Pagefind、Algolia 等适配器间切换
- [助手](https://blume.ndjp.net/docs/configuration/assistant/): 页面内聊天助手，由流式服务端端点与 AI SDK 支撑，可切换到 OpenAI、Anthropic、Gemini 等多种模型后端
- [速率限制](https://blume.ndjp.net/docs/configuration/rate-limiting/): 按 IP 限制读者调用服务端路由的频率，含 memory、Upstash 与 Cloudflare 三种适配器
- [朗读](https://blume.ndjp.net/docs/configuration/narration/): 为每个页面加一个「收听本页」播放器，可用读者设备自带的浏览器语音，也可在构建时生成语音
- [分析](https://blume.ndjp.net/docs/configuration/analytics/): 通过适配器接入 PostHog、Mixpanel、Amplitude、Segment 等二十多种分析服务，也可用 script() 接入任意脚本
- [Cookie 同意](https://blume.ndjp.net/docs/configuration/consent/): 在分析脚本运行前先询问读者，支持 Blume 自带横幅、Osano 与 Ethyca 三种同意管理器
- [导出](https://blume.ndjp.net/docs/configuration/export/): 在目录下方为读者提供 PDF 与 EPUB 导出能力，完全在客户端完成

## 可发现性

- [SEO 与 GEO](https://blume.ndjp.net/docs/discoverability/): 让搜索引擎与 AI agent 都能读懂你的文档 —— 元数据、社交卡片、订阅源、结构化数据、llms.txt、Markdown、JSON API 与 MCP
- [元数据](https://blume.ndjp.net/docs/discoverability/metadata/): 每个页面自动渲染的 head 标签、Open Graph 卡片与 X 归属，以及逐页面的 SEO 覆盖
- [Open Graph 图片](https://blume.ndjp.net/docs/discoverability/open-graph/): 在构建时为每个页面生成 1200×630 的社交卡片，并可自定义品牌、图层、字体与缓存
- [结构化数据](https://blume.ndjp.net/docs/discoverability/structured-data/): 在每个页面的 head 中输出 schema.org JSON-LD，让搜索引擎读懂你的内容
- [RSS 订阅](https://blume.ndjp.net/docs/discoverability/rss/): 为 blog 和更新日志生成 RSS 订阅源，并输出让阅读器自动发现的 link 标签
- [站点地图与 robots](https://blume.ndjp.net/docs/discoverability/sitemap-and-robots/): 构建时输出 sitemap.xml 与 robots.txt，并用 Content-Signal 声明内容供 AI 使用的范围
- [llms.txt](https://blume.ndjp.net/docs/discoverability/llms-txt/): 为编码智能体和聊天助手生成 llms.txt 与 llms-full.txt 两份机器可读文档
- [面向智能体的 Markdown](https://blume.ndjp.net/docs/discoverability/markdown/): 每个页面都提供 .md 与 .mdx 原文、内容协商，以及自定义组件的 Markdown 序列化器
- [JSON API](https://blume.ndjp.net/docs/discoverability/json-api/): 站点随附的只读 JSON API，供智能体和函数调用框架通过普通 HTTP 读取文档
- [MCP 服务器](https://blume.ndjp.net/docs/discoverability/mcp/): 托管一个 Model Context Protocol 服务器，让编码智能体直接检索并阅读你的文档
- [智能体发现](https://blume.ndjp.net/docs/discoverability/agent-discovery/): Blume 用清单、Link 头、well-known 文件与 WebMCP 把文档站点的整片界面广告给智能体

## API 参考

- [OpenAPI](https://blume.ndjp.net/docs/references/openapi/): 把 OpenAPI 规范渲染成原生 API 参考，每个接口一个真实页面，带 schema 表、代码示例和 Try it 演练场
- [AsyncAPI](https://blume.ndjp.net/docs/references/asyncapi/): 把 AsyncAPI 规范渲染成原生事件参考，每个操作一个真实页面，带消息 schema 表与 Try it 消息编辑器
- [GraphQL](https://blume.ndjp.net/docs/references/graphql/): 从 GraphQL schema 生成原生 API 参考，每个根字段和每个具名类型各占一个页面，带参数、示例与 Try it 演练场
- [Scalar](https://blume.ndjp.net/docs/references/scalar/): 用 scalar() 适配器把 Scalar 自带的完整 API 参考界面嵌入单个路由，并可透传它的配置
- [手写 API 页面](https://blume.ndjp.net/docs/references/api-pages/): 用 api frontmatter 手写端点文档，Blume 据此生成 Try it 面板、请求示例和响应示例

## 命令行

- [概览](https://blume.ndjp.net/docs/cli/): blume 命令行工具的全部子命令与通用选项，以及如何让构建和校验在开发服务器运行时互不干扰
- [doctor](https://blume.ndjp.net/docs/cli/doctor/): 与构建做完全相同的扫描，报告配置、内容、依赖包和密钥上的问题，并给出项目最终解析出的配置摘要
- [validate](https://blume.ndjp.net/docs/cli/validate/): 像构建那样读取内容并检查每一处链接，把站内链接、锚点、资源与外链问题按诊断码报告出来
- [audit](https://blume.ndjp.net/docs/cli/audit/): 在构建之后审查 dist/ 中的 HTML，报告 SEO 与站点健康问题，并把每条发现指向具体的源文件和 frontmatter 行
- [eval](https://blume.ndjp.net/docs/cli/evals/): 让一个 AI agent 仅凭你的文档回答真实用户问题，以此测试文档是否真的够用
- [translate](https://blume.ndjp.net/docs/cli/translate/): 用本地 agent CLI 把文档翻译到已配置的语言，并通过一份随代码提交的台账跟踪哪些译文已经过期
- [version](https://blume.ndjp.net/docs/cli/version/): 把当前文档冻结为一份归档版本快照，重写副本内的站内链接，并在配置中注册版本 id

## 进阶

- [智能体技能](https://blume.ndjp.net/docs/advanced/skills/): Blume 随包提供的 agent 技能：帮你搭脚手架、迁移旧站点、让文档跟上产品，以及为你自己的站点编写技能
- [自定义页面](https://blume.ndjp.net/docs/advanced/custom-pages/): 在 pages 目录下放一个 .astro 文件即可挂载真实路由，从 blume:data 读取站点数据，并在完整文档布局与落地页布局之间选择
- [更新日志](https://blume.ndjp.net/docs/advanced/changelog/): 把每次发布写成一个标记为 changelog 类型的内容文件，Blume 就会把它汇入自动生成的索引页和 RSS 订阅源
- [博客](https://blume.ndjp.net/docs/advanced/blog/): 给页面标记为博客类型，Blume 就会自动为它加上 RSS 订阅源和更完整的文章元数据，落地页则由你自己编排

## 智能体资源

- [llms-full.txt](https://blume.ndjp.net/llms-full.txt): 全部页面的完整 Markdown 语料。
- [RSS 订阅](https://blume.ndjp.net/rss.xml): 文档更新订阅源。
- [JSON API](https://blume.ndjp.net/api/docs/pages.json): 页面索引、导航与搜索接口。

页面总数：64