Blume 使用指南：用纯 Markdown 快速构建 AI 就绪的文档站点Blume 使用指南：用纯 Markdown

Blume 使用指南：用纯 Markdown 快速构建 AI 就绪的文档站点

一个文件夹、几行 Markdown，就能生成一个带搜索、主题、SEO、国际化和 AI 检索能力的生产级文档站——这就是 Blume。

一、Blume 是什么？

Blume 是一个开源的、零配置的文档框架，由开发者 Hayden Bleasel 创建并于 2026 年 7 月发布。它的核心理念是：你的 Markdown 文件夹本身就是一个完整的文档项目，不需要克隆模板、不需要维护框架代码、不需要写配置清单。

Blume 在底层基于 Astro 和 Vite 构建，但对你完全透明——它会自动生成一个隐藏的 Astro 项目（放在 .blume/ 目录），你只需要专注于写内容。

核心定位

维度	说明
内容格式	纯 Markdown（`.md`）或 MDX（`.mdx`）
构建产物	静态 HTML（默认），可选服务端渲染
许可证	MIT，永久免费开源
运行环境	Node.js 22.12+
包管理器	npm / pnpm / yarn / bun 均可

它解决了什么问题

传统文档方案（如 Docusaurus、VitePress、Mintlify）往往需要你维护框架代码、配置路由、安装插件。Blume 的思路是反向的：文件系统即路由，目录结构即导航，配置是可选的而非必须的。你写好 Markdown，剩下的它来搞定。

二、功能一览

Blume 开箱即用的能力非常丰富，以下是主要功能矩阵：

内容与写作

Markdown / MDX 双支持：.md 用于纯文本，.mdx 可嵌入组件
30+ 内置组件：Callout、卡片、步骤、标签页、文件树、代码组、Mermaid 图表、KaTeX 公式等，无需 import 直接使用
自动目录：每个页面根据 H2/H3 自动生成"本页目录"侧边栏
草稿模式：draft: true 的页面在开发环境可见，构建时自动排除

搜索

本地全文搜索：默认使用 Orama，开发和生产环境均可用，无需托管服务
多引擎切换：FlexSearch、Pagefind、Algolia、Typesense、Orama Cloud、Mixedbread，改一个配置即可

AI 就绪（AI-Ready）

这是 Blume 最有辨识度的特性：

llms.txt / llms-full.txt：一个开关生成机器可读的文档索引和全文，供 AI 代理读取
原始 Markdown URL：任何页面追加 .md 即可获取原始 Markdown 源码（如 /quickstart.md）
Copy as Markdown：页面一键复制为 Markdown
Open in Chat：一键在 ChatGPT、Claude 等对话工具中打开页面内容
Ask AI（可选）：页面内嵌 AI 问答助手，基于 AI SDK，支持 Vercel AI Gateway、OpenRouter、Inkeep 或任何 OpenAI 兼容端点
MCP 服务器：内置 Model Context Protocol 服务，Claude Code、Cursor、VS Code 等客户端可直接搜索和读取你的文档

SEO

自动生成 <title>、description、canonical、Open Graph、Twitter Card 等 meta 标签
OG 图片自动生成：每个页面构建时渲染 1200×630 社交卡片（基于 Takumi，无需无头浏览器）
RSS 订阅：blog 和 changelog 类型自动生成 feed
结构化数据：自动注入 schema.org JSON-LD（WebSite、Article、BreadcrumbList）
Sitemap：自动生成 sitemap.xml
robots.txt：自动生成，包含 Content-Signal 声明（控制 AI 爬虫的使用权限）

国际化

36 种语言界面翻译
完整 RTL（从右到左）支持
按语言路由、独立导航

API 文档

直接渲染 OpenAPI / AsyncAPI 规范为交互式文档
内置"Try it" playground
由 Scalar 驱动，主题与站点统一

其他

Changelog 时间线：每个版本写一篇 Markdown，自动聚合为 /changelog 时间线
导出：任何页面可导出为 PDF 或 EPUB（纯客户端）
内容源：支持本地文件、远程 MDX、GitHub Releases、Notion、Sanity，或自定义后端
类型安全配置：blume.config.ts 是真实 TypeScript，有 schema 校验
Eject：随时 blume eject 得到独立 Astro 项目，完全可控

三、快速上手

3.1 环境要求

确保安装了 Node.js 22.12 或更高版本：

node --version

如果版本不够，先升级 Node.js。

3.2 初始化项目

在一个空目录中运行：

npx blume init

这会交互式地引导你完成项目初始化。也可以在已有目录中直接运行，Blume 会检测现有内容。

3.3 启动开发服务器

npx blume dev

启动后访问 http://localhost:4321（Astro 默认端口），你会看到一个已经可用的文档站点。支持热重载，修改 Markdown 后页面自动刷新。

3.4 构建生产版本

npx blume build

构建产物输出到 dist/ 目录，包含静态 HTML 和本地搜索索引。

3.5 预览构建结果

npx blume preview

在本地启动一个服务器预览 dist/ 中的构建产物。

四、项目结构

一个典型的 Blume 项目长这样：

my-docs/
├── docs/                    # 内容根目录（默认）
│   ├── index.mdx            # 首页 → /
│   ├── quickstart.mdx       # → /quickstart
│   ├── guides/
│   │   ├── index.mdx        # → /guides
│   │   └── theming.mdx      # → /guides/theming
│   ├── blog/
│   │   └── hello.md         # → /blog/hello（type: blog）
│   └── changelog/
│       └── v1.0.0.md        # → /changelog/v1.0.0（type: changelog）
├── public/                  # 静态资源（图片、字体等）
├── blume.config.ts          # 配置文件（可选）
└── .blume/                  # 自动生成的 Astro 项目（不要手动编辑）

关键约定

内容根目录默认为 docs/，可在配置中通过 content.root 修改
index.mdx 放在文件夹中会成为该文件夹的首页
.blume/ 是自动生成的，每次运行都会重建，不要提交到版本控制，也不要手动编辑

五、内容编写

5.1 Markdown 与 MDX 的选择

格式	适用场景	能力
`.md`	纯文本文章	GFM、frontmatter、智能标点、上下标
`.mdx`	需要组件或高级语法	包含 `.md` 全部能力 + 内置组件 + 指令 + 包安装标签 + 数学公式

切换格式只需重命名文件。

5.2 文件与路由

文件路径直接决定 URL 路由：

文件路径	访问 URL
`docs/index.mdx`	`/`
`docs/quickstart.mdx`	`/quickstart`
`docs/guides/theming.mdx`	`/guides/theming`
`docs/guides/index.mdx`	`/guides`

嵌套文件夹自动成为嵌套路由。

5.3 排序：数字前缀

在文件名前加数字前缀来控制侧边栏顺序，前缀不会出现在 URL 中：

01-introduction.mdx  →  /introduction
02-installation.mdx  →  /installation
03-usage.mdx         →  /usage

这样你可以随时调整顺序而不会破坏已有链接。

5.4 分组文件夹

用括号包裹文件夹名，可以在侧边栏中分组页面，但不增加 URL 层级：

docs/(internal)/security.mdx  →  /security

页面在侧边栏显示在"Internal"分组下，但 URL 保持扁平。

5.5 Frontmatter

每个页面可以通过 YAML frontmatter 配置元数据：

---
title: 快速开始
description: 五分钟内搭建你的第一个 Blume 文档站
draft: false
type: doc
date: 2026-08-01
sidebar:
  label: 快速开始
  order: 2
seo:
  title: 快速开始 — My Docs
  description: 自定义的 SEO 描述
  image: /og/custom.png
  noindex: false
---

这里是正文内容...

常用字段：

字段	类型	说明
`title`	string	页面标题（同时用于 `<title>` 和侧边栏）
`description`	string	页面描述（用于 meta description 和 OG）
`draft`	boolean	是否为草稿（构建时排除）
`type`	string	内容类型：`doc`（默认）、`blog`、`changelog`
`date`	date	发布日期（用于 RSS 排序）
`sidebar.label`	string	侧边栏显示名称（覆盖 title）
`sidebar.order`	number	侧边栏排序
`seo.*`	object	页面级 SEO 覆盖

5.6 内容类型

doc（默认）

普通文档页面，无特殊聚合行为。

blog

博客文章。设置 type: blog 后，文章会被收集到 RSS feed（/blog/rss.xml）。约定放在 blog/ 目录下：

---
title: 介绍 Blume
type: blog
date: 2026-06-22
description: 我们为什么要做一个 Markdown 优先的文档框架
---

changelog

更新日志条目。设置 type: changelog 后，除了 RSS feed 外，还会自动聚合到 /changelog 时间线页面：

---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

5.7 内置组件（MDX）

在 .mdx 文件中可以直接使用以下组件，无需 import：

Callout（提示框）

:::tip
搜索、主题和导航都是开箱即用的。
:::

:::warning
此功能为实验性，API 可能变更。
:::

:::danger
此操作不可逆。
:::

步骤（Steps）

:::steps
1. 安装 Blume
2. 创建配置文件
3. 运行开发服务器
:::

标签页（Tabs）

:::tabs
--- npm
npm install blume
--- pnpm
pnpm add blume
--- yarn
yarn add blume
:::

包安装标签

```package-install
blume
```

会自动渲染为 npm / pnpm / yarn / bun 四个标签页的安装命令。

代码组

多个代码块自动组合为标签页。

Mermaid 图表

```mermaid
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
```

KaTeX 数学公式

行内： $E = mc^2$

块级：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

更多组件（卡片、文件树、表格、Diff 等）参考官方组件文档。

六、配置文件

Blume 的配置文件是 blume.config.ts，使用 TypeScript 编写，有完整的类型提示和 schema 校验。

6.1 最小配置

import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "我的文档站点",
});

6.2 常用配置项

import { defineConfig } from "blume";

export default defineConfig({
  // 站点基本信息
  title: "My Docs",
  description: "一个使用 Blume 构建的文档站",

  // 内容配置
  content: {
    root: "docs", // 内容根目录
    sources: [
      // 多内容源（可选）
      { type: "filesystem", root: "docs" },
      // { type: "mdx-remote", github: { owner: "me", repo: "docs", path: "docs" } },
      // { type: "notion", database: process.env.NOTION_DB },
    ],
  },

  // 主题配置
  theme: {
    accent: "blue", // 主题色：blue, teal, orange 等或自定义色值
    dark: true, // 是否启用暗色模式
  },

  // 搜索配置
  search: {
    provider: "orama", // orama, flexsearch, pagefind, algolia, typesense 等
  },

  // SEO 配置
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
    contentSignals: {
      search: true,
      aiInput: true,
      aiTrain: false, // 选择不参与 AI 训练
    },
  },

  // 部署配置
  deployment: {
    site: "https://docs.example.com", // 站点 URL（用于绝对链接、OG 图片等）
  },

  // GitHub 链接（显示在页面头部）
  github: "https://github.com/me/my-docs",
});

6.3 文件夹级配置（meta.ts）

在任意文件夹中放置 meta.ts，可以配置该文件夹的侧边栏分组：

import { defineMeta } from "blume";

export default defineMeta({
  title: "指南",
  order: 2,
});

七、搜索

默认搜索

Blume 默认使用 Orama 作为本地搜索引擎，在开发和生产环境中均可用，完全在浏览器端运行，无需任何后端服务或 API Key。

切换搜索引擎

在 blume.config.ts 中修改 search.provider：

search: {
  provider: "flexsearch", // 或 pagefind, algolia, typesense, orama-cloud, mixedbread
}

引擎	类型	说明
`orama`	本地（默认）	零配置，浏览器端运行
`flexsearch`	本地	轻量全文搜索
`pagefind`	本地	静态站点搜索，构建时索引
`algolia`	托管	需要 Algolia 账号和 API Key
`typesense`	自托管	需要 Typesense 服务器
`orama-cloud`	托管	Orama 云服务
`mixedbread`	托管	AI 搜索服务

八、AI 就绪功能详解

这是 Blume 区别于其他文档框架的核心能力。

8.1 llms.txt

在配置中启用后，Blume 会生成两个文件：

/llms.txt — 文档的机器可读索引（页面列表 + 摘要）
/llms-full.txt — 所有文档内容的全文聚合

AI 代理（如 Claude、GPT 等）可以读取这些文件来快速了解你的整个文档。

8.2 原始 Markdown 访问

任何页面的 URL 后追加 .md 即可获取原始 Markdown：

/quickstart      → 渲染后的 HTML 页面
/quickstart.md   → 原始 Markdown 源码

这对 AI 工具抓取和"Copy as Markdown"工作流非常友好。

8.3 MCP 服务器

Blume 内置了一个 Model Context Protocol 服务器，暴露四个只读工具：

search_docs — 搜索文档
get_page — 获取单个页面内容
list_pages — 列出所有页面
get_navigation — 获取导航结构

在 Claude Code 中连接：

claude mcp add --transport http comet-docs https://docs.example.com/mcp

连接后，Claude Code 可以直接搜索和读取你的文档，无需网页抓取。

注意：MCP 服务器和 Ask AI 需要服务端渲染模式，需选择一个 adapter（见部署章节）。

8.4 Ask AI 助手

在页面中嵌入一个 AI 问答助手，读者可以直接提问，AI 基于你的文档内容回答。支持多种后端：

Vercel AI Gateway
OpenRouter
Inkeep
任何 OpenAI 兼容端点

8.5 Content-Signal

在 robots.txt 中声明 AI 爬虫的使用权限：

User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /

三个信号：

search — 允许传统和 AI 搜索索引
aiInput — 允许用于 AI 回答时的 grounding / RAG
aiTrain — 允许用于模型训练

九、SEO 配置

9.1 基础 SEO

Blume 自动处理以下内容，无需额外配置：

页面 <title>（站点标题 + 页面标题）
<meta name="description">
<link rel="canonical">
Open Graph 标签（og:title, og:description, og:image, og:url 等）
Twitter Card 标签
结构化数据（JSON-LD）

9.2 设置站点 URL

为了让 canonical、OG 图片、sitemap、RSS 等使用绝对 URL，需要设置：

deployment: {
  site: "https://docs.example.com",
}

9.3 OG 图片自定义

Blume 会为每个页面自动生成 1200×630 的社交分享卡片。可以自定义品牌：

seo: {
  og: {
    enabled: true,
    logo: "/logo/og.svg", // 品牌 logo
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}

单个页面也可以通过 frontmatter 覆盖：

---
title: 定价
seo:
  image: /og/pricing-custom.png
---

9.4 RSS

默认对 blog 和 changelog 类型生成 RSS feed：

seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50, // 每个 feed 最多条目数
  },
}

9.5 页面级 noindex

---
title: 内部页面
seo:
  noindex: true
---

十、国际化

10.1 多语言内容

为每种语言创建对应的内容文件，Blume 会自动生成语言感知的路由和导航。

10.2 支持的语言

内置 36 种语言的界面翻译，包括中文、英文、日文、韩文、法文、德文、西班牙文、阿拉伯文等，并完整支持 RTL（从右到左）布局。

十一、API 文档

如果你有 OpenAPI 或 AsyncAPI 规范文件，Blume 可以直接渲染为交互式 API 文档：

自动生成端点列表、参数说明、响应示例
内置 "Try it" playground，可直接发送请求测试
由 Scalar 驱动，主题与整个站点统一

将规范文件放入项目中并在配置中引用即可。

十二、部署

12.1 静态部署（默认）

blume build 生成纯静态 HTML 到 dist/，可以部署到任何静态托管平台：

Vercel
Netlify
Cloudflare Pages
GitHub Pages
AWS S3 + CloudFront
任何 CDN

12.2 服务端渲染（需要 Ask AI / MCP）

如果要使用 Ask AI 助手或 MCP 服务器，需要切换到服务端输出模式，并选择 adapter：

Adapter	适用平台
`vercel`	Vercel
`netlify`	Netlify Functions
`node`	自托管 Node 服务器、容器
`cloudflare`	Cloudflare Workers / Pages

在 Vercel、Netlify、Cloudflare Pages 上，adapter 和站点 URL 会自动检测，无需手动配置。

12.3 从源码运行

git clone https://github.com/inferock/inferock-bench.git  # 替换为你的仓库
cd your-project
pnpm install
blume build

十三、CLI 命令参考

命令	说明
`blume init [dir]`	初始化项目（默认交互式）
`blume dev`	启动开发服务器，支持热重载
`blume build`	构建静态或服务端站点
`blume preview`	预览构建产物
`blume add <item>`	从注册表安装源组件
`blume sync`	重新拉取远程内容源并重新生成
`blume eject`	将隐藏的 Astro 项目提升为独立项目
`blume check`	使用 `astro check` 进行类型检查
`blume validate`	验证内部链接、锚点、资源和外部链接
`blume doctor`	诊断配置和内容问题
`blume --help`	查看帮助
`blume --version`	查看版本

十四、高级主题

14.1 多内容源

Blume 支持将多个来源的内容混合到一个站点中：

content: {
  sources: [
    { type: "filesystem", root: "docs" },
    {
      type: "mdx-remote",
      github: { owner: "myorg", repo: "docs", path: "docs" },
    },
    { type: "sanity", projectId: "xxx", dataset: "production", query: "*[_type == 'doc']" },
    { type: "notion", database: process.env.NOTION_DB },
  ],
}

所有内容源通过相同的组件渲染，统一的导航和搜索。

14.2 自定义与 Eject

Blume 的设计哲学是"渐进式控制"：

零配置：开箱即用
配置覆盖：通过 blume.config.ts 调整
组件覆盖：覆盖内置组件的外观
React Islands：添加交互式组件
自定义页面：添加 .astro 自定义页面
Tailwind 主题：通过 theme.css 和设计令牌定制
Eject：blume eject 得到完整的独立 Astro 项目，完全可控

14.3 从其他框架迁移

Blume 提供了 blume-migrate 技能，可以帮助从其他文档框架迁移。

十五、常见问题

Q: Blume 和 VitePress / Docusaurus 有什么区别？

A: 核心区别在于零配置和 Markdown 优先。VitePress 和 Docusaurus 需要你维护框架代码、配置路由和导航；Blume 从文件系统推断一切，配置是可选的。此外，Blume 内置了 AI 就绪功能（llms.txt、MCP、原始 Markdown URL），这是其他框架没有的。

Q: 我的 provider key 安全吗？

A: Blume 是纯静态构建工具，不涉及 API key。如果使用 Ask AI 功能，密钥配置在服务端环境变量中，不会暴露给客户端。

Q: 可以用自定义域名吗？

A: 可以。在部署平台配置自定义域名，并在 deployment.site 中设置对应的 URL。

Q: 构建速度怎么样？

A: Blume 基于 Astro 和 Vite，构建速度很快。OG 图片使用 Takumi 渲染（无需无头浏览器），进一步加速构建。

Q: 支持评论系统吗？

A: Blume 本身不内置评论系统，但可以通过自定义组件或 React Islands 集成第三方评论服务（如 Giscus、Disqus 等）。

Q: 如何处理大型文档站的性能？

A: Blume 默认生成静态 HTML，核心主题不加载客户端 JavaScript，Core Web Vitals 表现优秀。搜索在浏览器端运行，不会增加服务器负担。

十六、参考资源

官方网站：useblume.dev/
GitHub 仓库：github.com/haydenbleas…
npm 包：www.npmjs.com/package/blu…
官方文档：useblume.dev/docs
The Inferock Standard（Blume 背后的问责标准）：inferock.opiusai.com/standard/

Blume 采用 MIT 许可证，由 Hayden Bleasel 创建并维护。本文基于 Blume 最新版本编写，部分功能可能随版本更新而变化，请以官方文档为准。