# 博客
Source: https://blume.ndjp.net/docs/advanced/blog/
English: https://useblume.dev/docs/advanced/blog

在 Blume 里，博客不过是带了一个类型的内容。把某个页面标记为 `type: blog`，Blume 就会自动为它生成 RSS 订阅源和更完整的文章元数据。与[更新日志](/docs/advanced/changelog/)不同，这里没有自动生成的索引页 —— 落地页由你自己编排，设计完全握在你手里。

## 写一篇文章

一篇文章就是一个 frontmatter 里带 `type: blog` 的普通 `.md` 或 `.mdx` 页面。按惯例文章放在 `blog/` 下，但真正起作用的是类型，而不是文件夹：

```mdx blog/introducing-blume.mdx lineNumbers
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Documentation should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Here's the thinking behind Blume.
```

每篇文章都给一个 `date`，这样订阅源条目才能按最新在前排序并带上 `pubDate`；再给一个 `description` —— 它同时用于订阅源摘要和 SEO。

## RSS 订阅源

Blume 会在 **`/blog/rss.xml`** 处构建博客订阅源，按 `date` 以最新在前排序。订阅源需要一个绝对的站点 URL，所以请设置 [`deployment.site`](/docs/deployment/)；随后 Blume 会在每个页面上注入一个 `<link rel="alternate">` 标签，让读者自动发现它。

订阅源默认开启。可在 [`seo.rss`](/docs/discoverability/rss/) 下调整：

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

从 `rss.types` 中去掉 `"blog"` 即可不生成该订阅源。

## 结构化数据

开启[结构化数据](/docs/discoverability/structured-data/)后，每篇文章都会以 schema.org **`BlogPosting`** 的形式输出，带上它的描述和发布日期 —— 这是搜索引擎对博客内容所期待的那种更丰富的文章类型。

## 搭建索引

Blume 不会生成 `/blog` 落地页，所以要自己搭一个。最简单的做法是一个内容页面，手工链到每篇文章：

```mdx blog/index.mdx lineNumbers
---
title: Blog
description: News and writing from the team.
---

<CardGroup cols={2}>
  <Card title="Introducing Blume" href="/blog/introducing-blume">
    Why we built a markdown-first docs framework.
  </Card>
</CardGroup>
```

若想自动列出文章，则在 `pages/blog/index.astro` 添加一个[自定义页面](/docs/advanced/custom-pages/)，它从 Astro 的 `docs` 内容集合读取数据，并按路由的 `entryId` 把每个条目与它在 `blume:data` 中的路由配对：

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

// 自定义页面只在它自己的路径上渲染，因此这里只列出默认语言下的文章。
// getBlumeCollection 会排除草稿、隐藏页面，以及 i18n 为未翻译页面提供的副本，
// 所以每篇文章只会被列出一次。
const routes = getBlumeCollection(data, {
  locale: data.config.i18n?.defaultLocale,
});
const routeByEntry = new Map(routes.map((route) => [route.entryId, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && routeByEntry.has(entry.id))
  .map((entry) => ({
    date: entry.data.date,
    description: entry.data.description,
    href: routeByEntry.get(entry.id),
    title: entry.data.title,
  }))
  .toSorted((a, b) => Number(new Date(b.date)) - Number(new Date(a.date)));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

要把它包进完整的站点布局，参见[自定义页面](/docs/advanced/custom-pages/)。

**[自定义页面](/docs/advanced/custom-pages/)**

挂载博客索引，并从 `blume:data` 读取数据。

**[可发现性](/docs/discoverability/)**

订阅源、Open Graph 图片和结构化数据。

---

# 更新日志
Source: https://blume.ndjp.net/docs/advanced/changelog/
English: https://useblume.dev/docs/advanced/changelog

Blume 开箱即带更新日志。把每次发布写成一个普通内容文件、标记为 `type: changelog`，Blume 就会把每一条都汇入一个自动生成的索引页和一个 RSS 订阅源 —— 不用搭布局、不用维护列表。或者干脆不写这些文件，直接[从 GitHub Releases 引入更新日志](#from-github-releases)。

## 写一条记录

一条更新日志记录就是一个 frontmatter 里带 `type: changelog` 的普通 `.md` 或 `.mdx` 页面。按惯例它们放在 `changelog/` 下，但真正起作用的是类型，而不是文件夹：

```mdx changelog/v1-2-0.mdx lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks
```

每条记录都给一个 `date`，这样索引和订阅源才能以最新在前排序。YAML 日期不加引号也没关系 —— Blume 会做归一化。

### `changelog` 对象

可选的 `changelog` 对象为索引和订阅源补充更丰富的元数据：

| 属性 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `changelog.version?` | `string` | - | 发布版本。没有 title 时回退为一个带 v 前缀的标签。 |
| `changelog.category?` | `string` | - | 显示在记录旁的标签，例如 Release、Features、Fixes。 |
| `changelog.date?` | `string` | - | 发布日期。可以写在这里，也可以写在顶层 —— 两者都会进入索引和 RSS 订阅源。 |

## 索引页

一旦有了至少一条 `type: changelog` 记录，Blume 就会自动生成一个 **`/changelog`** 页面。那是一个专注的全宽索引 —— 没有侧边栏，也没有目录 —— 它把每次发布列成一行，最新在前并按年份分组，于是一段很长的历史仍然只是一个很短的页面（远小于 agent 能在单个上下文窗口内读完的体量）：

- 该条记录的 **title** 就是这一行的标签 —— 没有 title 时则用 `v{version}`。它链到该记录自己的页面，更新说明全文就在那里渲染。
- `category` 会作为标签渲染在 title 旁边，读者一眼就能分清正式版与预发布版，或者功能与修复。
- 日期遵循配置的 [`dateFormat`](/docs/configuration/)，但会去掉这一行所属分组里已经显示过的年份。
- 草稿以及标记了 `sidebar.hidden` 的条目会被跳过。

只有当 `/changelog` 路由上还没有别的东西占据时，这个页面才会出现。要用自己的设计替换它，在 `pages/changelog.astro` 添加一个[自定义页面](/docs/advanced/custom-pages/) —— 它会接管该路由，Blume 也就停止生成默认索引。旧时间线所基于的 `<Update>` 组件仍然随包提供，供想在自定义页面里内联渲染更新说明时使用。它不是 MDX 组件之一，所以要在 `.astro` 页面里自行导入：`import Update from "blume/components/content/Update.astro";`。指向 `/changelog` 的头部[标签页](/docs/content/navigation/)会打开这个索引 —— 不需要 `href`。

## 从 GitHub Releases 引入 [#from-github-releases]

与其手写记录，不如把内置的 [`githubReleases()` 源](/docs/content/sources/github-releases/)指向一个仓库，于是每次发布都会变成一条 `type: changelog` 记录 —— 同样的时间线和订阅源，内容直接来自你已经在发布的那些 release。Blume 自己的[更新日志](/docs/advanced/changelog/)就是这么搭起来的：

```ts blume.config.ts
import { filesystem, githubReleases } from "blume/sources";

content: {
  sources: [
    filesystem({ root: "content" }),
    githubReleases({
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    }),
  ],
}
```

release 的名字成为 title，它的 tag 成为 `changelog.version`，发布日期则决定时间线的排序。每个发布页还会得到一段独特的 meta description，由它的更新说明概括而来 —— 去掉 markdown、去掉小节标题和 changeset 的提交哈希前缀、裁剪到 [`blume audit`](/docs/cli/audit/) 检查的搜索摘要长度 —— 而不是回退到站点描述。私有仓库通过 `GITHUB_TOKEN` 环境变量认证。全部选项见 [GitHub Releases](/docs/content/sources/github-releases/)。

## RSS 订阅源

Blume 还会在 **`/changelog/rss.xml`** 处构建更新日志订阅源，按 `date` 以最新在前排序。订阅源需要一个绝对的站点 URL，所以请设置 [`deployment.site`](/docs/deployment/)；随后 Blume 会在每个页面上注入一个 `<link rel="alternate">` 标签，让读者自动发现它。

订阅源默认开启。可在 [`seo.rss`](/docs/discoverability/rss/) 下调整：

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

从 `rss.types` 中去掉 `"changelog"` 即可不生成该订阅源，同时保留时间线。

## 结构化数据

开启[结构化数据](/docs/discoverability/structured-data/)后，每条更新日志记录都会以 schema.org **`TechArticle`** 的形式输出，带上它的描述和发布日期，于是搜索引擎可以把各个发布当作带日期的文章来索引。

**[Frontmatter](/docs/content/frontmatter/)**

完整的更新日志 frontmatter schema。

**[自定义页面](/docs/advanced/custom-pages/)**

用你自己的布局替换生成的时间线。

---

# 自定义页面
Source: https://blume.ndjp.net/docs/advanced/custom-pages/
English: https://useblume.dev/docs/advanced/custom-pages

Blume 站点的大部分内容是 Markdown，但有时你需要一条*不是*文档的路由 —— 落地页、定价页、手工搭的博客或更新日志索引，或者一个交互式仪表盘。在你的 **pages** 目录下放一个 `.astro` 文件，Blume 就会把它挂载成一条真正的路由，与你的内容并列。

## 添加页面

在项目根目录创建一个 `pages/` 文件夹，并加入一个 `.astro` 文件：

```astro pages/pricing.astro lineNumbers
---
import data from "blume:data";
---

<h1>Pricing for {data.config.title}</h1>
```

`blume dev` 会立刻认出它，`blume build` 则会把它预渲染成静态 HTML。文件夹名可通过 [`content.pages`](/docs/configuration/) 配置（默认 `"pages"`）。

自定义页面在磁盘上保留原来的位置，因此相对导入、组件导入以及 [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) 的行为都与普通 Astro 项目完全一致 —— Blume 把每个文件原地挂载，而不是复制一份。

## 文件与路由

每个文件在 pages 目录下的路径就是它的路由。`index` 映射到上级目录，动态的 `[param]` 段会被保留：

| 文件 | 路由 |
| --- | --- |
| `pages/pricing.astro` | `/pricing` |
| `pages/blog/index.astro` | `/blog` |
| `pages/blog/[slug].astro` | `/blog/:slug` |
| `pages/changelog.astro` | `/changelog` |

自定义页面在同一路径上会**胜出**于自动生成的路由。比如加上 `pages/changelog.astro`，就把 Blume 的[更新日志时间线](/docs/advanced/changelog/)换成了你自己的。

Blume 无法枚举一条动态 `[param]` 路由会服务哪些路径，因此这类页面不会进入[站点地图](/docs/discoverability/sitemap-and-robots/)、不会生成 [Open Graph 卡片](/docs/discoverability/open-graph/)，[`blume validate`](/docs/cli/validate/) 也不认识它们 —— 链到它们的链接会被报成失效。要让它们拥有分享图，可以给 `PageLayout` 传 `ogImage`；或者为每条路径各配一个静态文件（用 `pages/compare/mintlify.astro` 而不是 `pages/compare/[tool].astro`），这样三样都能拿到。

## 读取站点数据

导入 `blume:data`，即可读到与站点其它部分相同的已解析配置、导航、路由和订阅源：

```astro pages/all-pages.astro lineNumbers
---
import data from "blume:data";
---

<h1>All pages</h1>
<ul>
  {
    data.routes
      .filter((route) => route.indexable)
      .map((route) => (
        <li>
          <a href={route.path}>{route.title}</a>
        </li>
      ))
  }
</ul>
```

在 Blume 项目里这个模块的类型是自动的。你也可以显式引入它的类型定义 —— 用于带类型的辅助函数、props 或你自己的 tsconfig —— 即 `import type { BlumeData } from "blume"`：

```ts
import type { BlumeData, BlumeRoute } from "blume";

const indexable = (data: BlumeData): BlumeRoute[] =>
  data.routes.filter((route) => route.indexable);
```

该模块暴露以下内容：

| 属性 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `config` | `BlumeDataConfig` | - | 已解析的站点设置：title、description、logo、favicon、appleIcon、banner、theme、site、repoUrl、github（owner、repo、host 以及 REST API 基础地址 —— 未设置时为 null）、search、i18n、mcp、assistant、og、analytics、feedback、structuredData、toc、codeThemes、codeWrap 和 imageZoom。 |
| `navigation` | `Navigation` | - | 从你的内容（默认语言）推导出来的侧边栏、标签页和选择器。 |
| `navigationByLocale` | `Record<string, Navigation>` | - | 按语言代码索引的各语言导航树。没有配置 i18n 时为空。 |
| `routes` | `BlumeRoute[]` | - | 每一个内容页面：`{ id, path, title, locale, indexable, hidden, draft, fallback, editUrl, lastModified, alternates, collection, entryId }`。 |
| `feeds` | `BlumeFeed[]` | - | 生成的 RSS 订阅源：`{ href, title }`。 |
| `fontCssVars` | `FontHead[]` | - | 供 Astro 的 `<Font>` 组件在 head 中使用的已配置字体，每个字族一项：`{ cssVariable, preloadWeights, preloadSubsets? }`。 |
| `ui` | `UIStrings` | - | 默认语言的已解析 UI 文案（搜索、侧边栏和页脚标签）。 |
| `uiByLocale` | `Record<string, UIStrings>` | - | 按语言代码索引的各语言 UI 文案。没有配置 i18n 时为空。 |

`routes` 带有页面元数据，但不含 `type`、`date` 这类 frontmatter。要按内容类型过滤出一份列表 —— 比如博客或更新日志索引 —— 把它与 Astro 的 `docs` 内容集合搭配使用，后者保存着 frontmatter：

```astro pages/blog/index.astro lineNumbers
---
import { getCollection } from "astro:content";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

// 在 i18n 下，每个语言都会为每个条目提供一条路由（它的译文，或未翻译页面
// 的副本），它们共享同一个条目 id。这里只用默认语言的路由做键，这样每篇
// 文章只会在一种语言里出现一次链接。
const routes = getBlumeCollection(data, {
  locale: data.config.i18n?.defaultLocale,
});
const routeByEntry = new Map(routes.map((route) => [route.entryId, route.path]));

const posts = (await getCollection("docs"))
  .filter((entry) => entry.data.type === "blog" && routeByEntry.has(entry.id))
  .map((entry) => ({
    description: entry.data.description,
    href: routeByEntry.get(entry.id),
    title: entry.data.title,
  }));
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <p>{post.description}</p>
      </li>
    ))
  }
</ul>
```

## 运行时辅助函数

`blume/runtime` 打包了常用的数据模式，你不必去碰 `blume:data` 的内部实现。

**`getBlumeCollection(data, query?)`** 用来挑选内容路由 —— 可按集合、语言或路径前缀过滤，排除草稿、隐藏页面和 i18n 回退副本，并按路径排序 —— 这正是一个自定义索引所需要的：

```astro pages/blog/index.astro lineNumbers
---
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const posts = getBlumeCollection(data, { prefix: "/blog" });
---

<ul>
  {posts.map((post) => (
    <li><a href={post.path}>{post.title}</a></li>
  ))}
</ul>
```

**`<BlumePage>`** 在自定义页面里渲染某个内容条目的正文，Blume 内置的 MDX 组件（callout 提示框、卡片、步骤……）已经接好 —— 适合在落地页上重点展示某篇文档，或搭建一个展示真实内容的定制索引：

```astro pages/index.astro lineNumbers
---
import BlumePage from "blume/components/BlumePage.astro";
import data from "blume:data";
import { getBlumeCollection } from "blume/runtime";

const [intro] = getBlumeCollection(data, { prefix: "/docs" });
---

{intro && <BlumePage id={intro.entryId} />}
```

传入 `components` 可以加入你自己的覆盖项或交互岛（它们位于生成的运行时中，默认不会导入），传入 `collection` 则可以从 `"docs"` 以外的集合读取。

## 使用站点布局 [#using-the-site-layout]

`RootLayout` 通过把自定义页面包进与生成页面相同的三栏网格，为它提供完整的文档外壳 —— 头部、侧边栏、搜索、目录和主题。但对落地页或营销页来说，那个网格是累赘，所以这时该用 **`PageLayout`**：它提供文档骨架、头部、主题和字体，然后是一个全宽的 `<slot />`（没有侧边栏、没有正文排版、没有目录）。可选的 `footer` 插槽会渲染在 `<main>` 之后：

```astro pages/index.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
import Footer from "./_home/Footer.astro";

const { config } = data;
---

<PageLayout
  site={{ title: config.title, description: config.description }}
  logo={config.logo}
  banner={config.banner}
  analytics={config.analytics}
  navigation={data.navigation}
  favicon={config.favicon}
  fontCssVars={data.fontCssVars}
  themeMode={config.theme.mode}
  searchEnabled={config.search.enabled}
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  page={{ title: "Acme — the fastest docs", description: config.description }}
>
  <section class="mx-auto max-w-5xl px-6 py-24">
    <h1>Build docs that fly</h1>
  </section>
  <Footer slot="footer" />
</PageLayout>
```

自定义页面拿到的头部与文档页面拿到的是同一个，因此住在里面的那些外壳也都跟了过来：搜索、主题切换，以及在配置了[助手](/docs/configuration/assistant/)时的助手入口。它们都不需要逐页接线。传 `assistantEnabled={false}` 可以在保留其它页面助手入口的同时，只让某一个页面不显示它。

语言切换器是例外。自定义页面只在自己的路由上提供服务，因此 Blume 无法知道其它哪些语言也有它的版本，除非你显式传入，否则头部不会显示切换器：`localeSwitch` 为每种语言接收一个条目 —— `{ code, label, dir, href, current, untranslated }` —— 指向你为那种语言构建的页面。

[面向 agent 发现的 head 链接](/docs/discoverability/agent-discovery/)同样会带上：布局会读取已解析的配置，因此自定义页面无需传 prop 就带有与文档页面相同的 `describedby`、`ai-catalog` 和 `ard` 链接。首页还会把自己的 `/index.md` Markdown 镜像作为 `text/markdown` 备选链接公布出去，因为这个镜像总是存在；其它自定义页面没有镜像，因此也不会公布。传 `discovery={null}` 可以让某一个页面不带这些链接。

传 `transparentHeader` 可以让头部起始时是透明的、外壳部分为白色，这样它能压在页面顶部的深色 hero 之上；页面一滚动它就变回常见的毛玻璃条，搜索对话框也始终保持页面自己的配色。要看出这个效果，hero 必须延伸到头部下方 —— 用头部的高度（`-mt-16`）把它提上去，并相应补上顶部内边距。

传入 `siteUrl`（以及 `ogEnabled`）会自动推导出页面的 `canonical` 和一张生成的 `og:image`：Blume 会为每个静态自定义页面渲染一张 Open Graph 卡片（动态 `[param]` 页面除外）—— 包括首页这个最常被分享的 URL —— 它在 `/og/<route>.png` 处提供（`/` 对应 `/og/index.png`）。首页卡片的标题是站点标题，副标题是站点描述；层级更深的页面则用路径的最后一段作为标题。显式设置 `ogImage` 或 `canonical` 即可覆盖其中任意一项。`ogImage` 接受一个相对于根的路径 —— `public/` 里的文件，会依据 [`deployment.site`](/docs/deployment/) 解析成爬虫所需的绝对 URL —— 或者一个外部 URL，后者会原样透传：

```astro pages/index.astro lineNumbers
<PageLayout
  siteUrl={config.site}
  ogEnabled={config.og.enabled}
  ogImage="/opengraph-image.png"
  ogImageAlt="Acme — the fastest docs"
  ogImageSize={{ width: 1200, height: 630 }}
  page={{ title: config.title }}
>
  <!-- 页面内容 -->
</PageLayout>
```

只有这一个页面会变 —— 其它每条路由都保留自己生成的卡片 —— 因此这是给首页单独配一张定制分享图的办法。生成的卡片会自行向爬虫声明尺寸和替代文字；换成你自己的 `ogImage` 时，请一并传入 `ogImageAlt` 和 `ogImageSize`，让分享卡得到同样的待遇。

页面还会输出 schema.org JSON-LD —— 与文档页面所带的是同一份 `WebSite` 图谱 —— 这样首页（通常就是一个自定义页面）就不会成为唯一缺少结构化数据的 URL。传 `structuredDataEnabled={config.structuredData}` 可以让它与 [`structuredData`](/docs/discoverability/structured-data/) 配置保持一致，或传 `structuredDataEnabled={false}` 为某一个页面关掉它。

`page.title` 会被逐字用作文档标题（不会追加 `- siteTitle` 后缀），因为营销页通常有自己的标题。若想让自定义页面拥有完整的文档外壳 —— 侧边栏、目录等等 —— 就把它包进生成页面所用的 `RootLayout`。所需 props 可以直接从 `blume:data` 取：

```astro pages/pricing.astro lineNumbers
---
import RootLayout from "blume/components/layout/RootLayout.astro";
import data from "blume:data";
---

<RootLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  banner={data.config.banner}
  navigation={data.navigation}
  page={{ title: "Pricing", route: "/pricing" }}
  headings={[]}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  indexable={true}
>
  <h1>Pricing</h1>
</RootLayout>
```

:::note
`RootLayout` 属于生成的运行时，因此它的 props 可能随版本变化。当你想要一个完全属于自己的布局时，[`blume eject`](/docs/configuration/customization/) 会把 `.blume/` 变成一个完全归你所有的标准 Astro 项目。
:::

## 404 页面 [#404-page]

Blume 开箱即带一个默认的**未找到**页面：一条居中的 "404" 信息，外面裹着站点外壳（头部、搜索、主题），任何未匹配的 URL 都会得到它。`blume build` 把它写成 `404.html`，静态托管会自动提供这个文件，`blume dev` 则在遇到未知路由时显示它。信息下方有一个 **接下来可以看看** 列表，链到每个顶层板块，以及存在时的 `sitemap.xml` 和 [`llms.txt`](/docs/discoverability/llms-txt/) 索引，这样读者 —— 或者跟着过期 URL 而来的 agent —— 总有条回来的路。

这个页面还有一对孪生页面：`/404.md` 的 Markdown 版和 `/404.json` 的 JSON 版（[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 的 problem details），带着同样的恢复链接（设置了 [`deployment.site`](/docs/deployment/) 之后就是绝对 URL），开启 JSON API 时还会带上 [`openapi.json`](/docs/discoverability/json-api/) 的描述。在 [Vercel 或 Cloudflare 的服务端构建](/docs/deployment/)上，对一个缺失页面的请求如果带上 [`Accept: text/markdown`](/docs/discoverability/markdown/)，会得到 Markdown 正文和 `404` 状态码，而不是 HTML 外壳；带上 `Accept: application/json` 则会得到 problem document —— 于是 agent 永远不必去解析一整页外壳才知道该往哪儿走。在 Vercel 上，没有任何文件支撑的 `.md` 或 `.json` URL 同理。

要换成自己的页面，添加一个 `pages/404.astro`。它拥有 `/404` 路由的方式与 `pages/changelog.astro` 接管更新日志一样 —— 你的页面胜出，默认页面连同它的 `/404.md` 和 `/404.json` 孪生页面一起被丢弃。像构建任何其它自定义页面那样构建它，用 `PageLayout` 或 `RootLayout`：

```astro pages/404.astro lineNumbers
---
import PageLayout from "blume/components/layout/PageLayout.astro";
import data from "blume:data";
---

<PageLayout
  site={{ title: data.config.title, description: data.config.description }}
  logo={data.config.logo}
  navigation={data.navigation}
  themeMode={data.config.theme.mode}
  searchEnabled={data.config.search.enabled}
  page={{ title: "Page not found", route: "/404" }}
  noindex={true}
>
  <section class="mx-auto max-w-2xl px-6 py-24 text-center">
    <h1>This page took a wrong turn</h1>
    <a href="/">Back to home</a>
  </section>
</PageLayout>
```

想保留默认设计、只换文案 —— 包括为其它语言换文案 —— 可以通过 `i18n.ui` 覆盖 `notFound` 的 [UI 文案](/docs/content/i18n/)（`title`、`description`、`home`）。

## 交互式页面

自定义页面就是普通的 Astro，因此你可以用一条 hydration 指令放进 React（或任何框架）的[交互岛](/docs/configuration/customization/)。项目里一旦出现 `.tsx` 或 `.jsx` 文件，React 就会自动启用。

**[自定义](/docs/configuration/customization/)**

组件覆盖、React 交互岛、registry 和导出。

**[博客](/docs/advanced/blog/)**

撰写文章并搭建自定义博客索引。

---

# 技能
Source: https://blume.ndjp.net/docs/advanced/skills/
English: https://useblume.dev/docs/advanced/skills

Blume 随包提供[agent 技能](https://docs.claude.com/en/docs/claude-code/skills) —— 一套操作手册，教编码 agent（Claude Code、Codex、Cursor）如何完成 Blume 式的活儿，而你不必逐条解释。它们在 GitHub 上位于仓库的 `skills/` 目录，同时也打包在已安装的包的 `skills/` 下，因此任何 agent 都可以直接指向某个 `SKILL.md`。

## Blume

核心技能。它教会 agent Blume 是什么，以及如何生成脚手架、编写和配置一个站点 —— 从文件系统推导出来的导航、配置 schema、内容组件 —— 并把 agent 指向随安装包一起分发的完整文档（`blume` 包内的 `docs/` 目录，路径取决于你的包管理器把它装到了哪里 —— 在 pnpm monorepo 中是依赖它的那个 workspace 的 `node_modules`，而不是仓库根目录）。在任何由 agent 帮你编写文档的项目里都可以安装它：

```bash
npx skills add haydenbleasel/blume
```

## 迁移

`blume-migrate` 把一个已有的文档站迁移到 Blume：Mintlify、Fumadocs、Docusaurus、Starlight、Nextra，或任何其它框架。它以地道的 Blume 为目标，而不是逐行照搬：为每个具名框架提供一份映射参考，为每一个会变动的 URL 配一个重定向，并报告它丢弃了什么。运行它最省事的方式是 [`blume migrate`](/docs/migrating/)，它会检测你的框架，并针对随包分发的那份打开 Codex 或 Claude Code。想在别的 agent 里使用它，请安装：

```bash
npx skills add haydenbleasel/blume --skill blume-migrate
```

## 让文档自我更新

`blume-update-docs` 让你的文档与它们所描述的产品保持同步。每次运行 —— 通常由你在 agent 运行器里配置的定时任务触发 —— 它会把最近合并的 PR、更新日志、配置 schema 和 CLI 帮助与文档内容逐一比对，只更新那些事实上已经过时的页面（feature flag 后面的工作会被忽略），用 `blume build` 验证，然后开启或更新一个 `blume/*` pull request。如果什么都没有过时，它会报告一次干净的空操作，而不是开一个吵闹的 PR。

```bash
npx skills add haydenbleasel/blume --skill blume-update-docs
```

Blume 不托管这套自动化 —— 把这个技能接进 Claude Code 的定时任务、Codex 或 Cursor 的自动化，或者干脆用 cron，并授予它读取仓库历史和开 PR 的权限。一个典型的每周提示词：

```text
使用 blume-update-docs 技能。审阅过去 7 天内合并的 PR，把它们与文档内容对比。忽略 feature flag 后面的工作。如果文档需要更新，就更新它、验证文档能构建，并开一个 blume/* 的 PR。如果不需要，就报告你检查了哪些内容，不要开 PR。
```

## 为你自己的站点编写技能 [#writing-your-sites-skill]

`blume-write-skill` 会为你自己的文档编写 [agent 技能](/docs/discoverability/agent-discovery/)：一份以文档为依据的 `SKILL.md`，教编码 agent 使用你的产品 —— 安装配置、核心概念、常见任务和坑 —— 并把每个主题链接到它所在的页面。它取代了 Blume 在 `/skill.md` 处生成的页面地图。运行它最省事的方式是 `blume skill`，它会算出这个技能该放在哪里，并针对随包分发的那份打开 Codex 或 Claude Code：

```bash
blume skill --claude   # 或 --codex
```

想在别的 agent 里使用它，请安装：

```bash
npx skills add haydenbleasel/blume --skill blume-write-skill
```

---

# 命令行
Source: https://blume.ndjp.net/docs/cli/
English: https://useblume.dev/docs/cli

```bash
blume <command> [options]
```

## 命令

| 命令 | 说明 |
| --- | --- |
| `blume init [dir]` | 生成项目脚手架（默认交互式）。 |
| `blume dev` | 启动带热重载的开发服务器。 |
| `blume build` | 构建静态（或服务端）站点。 |
| `blume preview` | 预览上一次构建。 |
| `blume add [item]` | 从 registry 安装一个源组件（不带 item 时列出可用项）。 |
| `blume sync` | 重新拉取远程内容源并重新生成。 |
| `blume eject` | 把运行时导出为一个独立的 Astro 应用。 |
| `blume check` | 用 `astro check` 对站点做类型检查。 |
| [`blume doctor`](/docs/cli/doctor/) | 诊断配置与内容问题。 |
| [`blume validate`](/docs/cli/validate/) | 校验内容中的所有链接。 |
| [`blume audit`](/docs/cli/audit/) | 审查构建产物中的 SEO 与站点健康问题。 |
| [`blume eval`](/docs/cli/evals/) | 测试文档：让一个 agent 仅凭文档回答你的问题。 |
| [`blume translate`](/docs/cli/translate/) | 用本地 agent CLI 把文档翻译到已配置的语言。 |
| [`blume version [id]`](/docs/cli/version/) | 把当前文档冻结为一个归档版本（不带 id 时列出已配置的版本）。 |
| [`blume skill`](/docs/discoverability/agent-discovery/) | 用 Codex 或 Claude Code 为你的文档编写 agent skill，替代自动生成的那一份。 |
| [`blume migrate [source]`](/docs/migrating/) | 用 Codex 或 Claude Code 把 Mintlify、Fumadocs、Docusaurus、Starlight 或 Nextra 站点迁移到 Blume。 |
| [`blume upgrade`](/docs/upgrading/) | 升级到新的主版本：先升级 `blume`，再列出剩余的配置改动，或把它们交给 Codex 或 Claude Code。 |

## 通用选项 [#common-flags]

- `blume init` — 在终端里，它会引导你回答几个问题（项目建在哪里、站点名称、模板、内容源）；下面的每个选项都预先回答了其中一个问题。
- `blume init --yes` — 跳过所有提问，用默认值生成脚手架（在 CI 中或 stdin 不是终端时也是这个行为）。
- `blume init --content-dir <dir>` — 设置内容目录（默认 `docs`）。
- `blume init --template docs|api|sdk|changelog` — 从一个起始模板生成脚手架（用 API 参考、SDK 或更新日志，替代普通的文档种子）。
- `blume init --package-manager npm|pnpm|yarn|bun` — 用指定的包管理器安装依赖，并打印对应的后续步骤（默认：运行 `blume init` 的那个）。
- `blume init --no-install` — 只写文件、跳过依赖安装，适用于 CI 或自定义的依赖流程。默认情况下 `blume init` 会运行包管理器的安装命令，让项目开箱即可运行；如果安装失败，脚手架会被保留、重试命令会被打印出来，退出码非零。
- `blume init --eject` — 先生成脚手架，再导出为一个独立的 Astro 项目（配合 `--no-install` 时，依赖装好后会改为引导你执行 `blume eject`）。
- `blume dev --host --port <n> --open`
- `blume dev --content-dir <dir>` — 扫描另一个内容目录，无需改动 `blume.config.ts`。
- `blume dev --debug` — 输出详细的 Astro/Vite 日志，便于排查问题。
- `blume dev --preview` / `blume build --preview` — 包含草稿和未发布的 CMS 内容。
- `blume build --no-strict` — 即使有诊断错误也照常构建。默认情况下 `blume build` 只要遇到任何错误级诊断就失败（退出码 1），因为 frontmatter 校验未通过的页面会被从产物中丢弃；加上 `--no-strict` 后构建会成功，并报告有多少页面被丢弃。`blume dev --strict` 让开发模式采用同样的快速失败行为。
- `blume build --analyze` — 构建后打印客户端 JavaScript 各包的体积（从大到小）。
- `blume build --budget-js <kb> --budget-css <kb>` — 当客户端 JavaScript/CSS 总量超出预算时让构建失败，把性能目标变成一道 CI 关卡。
- `blume build --isolated` — 构建到一个一次性的 `.blume-verify/` 运行时（以及它自己的 `dist/`）中，而不是 `.blume/`，这样正在运行的 `blume dev` 服务器和你真正的 `dist/` 都不会被影响。参见[开发服务器运行时如何校验](#verifying-while-the-dev-server-runs)。
- `blume preview --host --port <n>` — 绑定预览服务器。
- `blume sync --force` — 先丢弃缓存快照，再重新拉取远程源。
- `blume sync --preview` — 包含草稿和未发布的 CMS 内容。
- `blume sync --strict` — 遇到诊断即失败。
- `blume add <item> --force` — 覆盖已存在的文件。
- `blume check --preview` — 检查时包含草稿和未发布的 CMS 内容。
- `blume check --strict` — 内容诊断与类型错误都导致失败。
- `blume check --isolated` — 在一次性的 `.blume-verify/` 运行时中做类型检查，使正在运行的 `blume dev` 服务器不受影响。参见[开发服务器运行时如何校验](#verifying-while-the-dev-server-runs)。
- `blume eject --yes` — 跳过确认提示。
- `blume eject --force` — 在已经导出的应用上再次导出，覆盖其 `astro.config.mjs` 和 `src/`。

有独立页面的命令会把自己的全部选项都列在那一页：[`blume doctor`](/docs/cli/doctor/)、[`blume validate`](/docs/cli/validate/)、[`blume audit`](/docs/cli/audit/)、[`blume eval`](/docs/cli/evals/)、[`blume translate`](/docs/cli/translate/) 和 [`blume version`](/docs/cli/version/)。`blume validate`、`blume doctor`、`blume audit`、`blume eval` 和 `blume translate` 接受 `--json`，把机器可读的结果打印到 stdout，供 CI 和编辑器集成使用（诊断的数据结构见 [validate](/docs/cli/validate/)）；`build`、`check` 和 `dev` 只向终端输出。每个命令都会拒绝自己不接受的选项，并给出最接近的那一个作为建议、同时列出它真正接受的选项，因此像 `--isolatd` 这样的拼写错误会直接失败，而不会被悄悄忽略。

## 开发服务器运行时如何校验 [#verifying-while-the-dev-server-runs]

`blume dev` 提供的是一个以生成的 `.blume/` 运行时为根的实时 Astro 服务器，并在每次改动后重新生成它。`blume build` 和 `blume check` 重新生成的是*同一个* `.blume/`，因此在开发服务器运行时执行其中任何一个都会把它弄坏——两者都会报错并以非零码退出：

```
A `blume dev` server is running at http://localhost:4321; building would
corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
--isolated to build/verify against .blume-verify without touching it.
```

`--isolated` 就是那个逃生舱。它把整个生成的运行时（对 `build` 来说还有它输出的 `dist/`）挪到同级的 `.blume-verify/` 目录，因此校验过程绝不会写入开发服务器（或你真正的 `dist/`）所依赖的任何东西：

```bash
# 在第二个终端里，`blume dev` 正在运行时：
blume check --isolated   # 快：只对 .astro/config 的改动做类型检查
blume build --isolated   # 彻底：把生产构建完整渲染到 .blume-verify/dist
```

`check --isolated` 是快捷路径（Astro 类型与模板诊断，不产出 `dist/`）；`build --isolated` 更重，还会捕捉运行时渲染错误。隔离构建会跳过部署后的步骤（搜索索引、托管服务同步、`llms.txt`、sitemap/robots、重定向）——一次校验只需要确认站点能编译、能渲染，不需要把它发布出去。`--analyze` 以及 `--budget-js`/`--budget-css` 两道关卡仍然会跑，只是以隔离产物为基准。Blume 会自动把 `.blume-verify/` 加进你的 `.gitignore`。

当你想让开发服务器一直开着、同时又需要编码 agent 校验改动时，这一点尤其有用。要让普通的 `blume build`/`blume check` 不加这个选项也能自动隔离——比如在 agent 的 shell 里——把 `BLUME_RUNTIME_DIR` 设成要使用的运行时目录：

```bash
export BLUME_RUNTIME_DIR=.blume-verify
```

## 类型检查

`blume check` 会对你的项目运行 [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check)。它会重新生成 `.blume` 运行时、同步 Astro 的内容类型，然后报告所有 TypeScript 错误——无论是在你的 `blume.config.ts` 里、在自定义的 `.astro` 页面里，还是在这些页面导入的组件中。有错误时它以非零码退出，因此可以直接当作 CI 中的 `typecheck` 步骤：

```json title="package.json"
{
  "scripts": {
    "typecheck": "blume check"
  }
}
```

在项目根目录添加一个继承 Astro 配置的 `tsconfig.json`，这样手写的页面才能解析 `blume/*` 导入以及 `blume:data` 这类虚拟模块：

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "include": [".blume/.astro/types.d.ts", "**/*"]
}
```

没有项目级 `tsconfig.json` 时，只会检查生成的运行时。

---

# 审查
Source: https://blume.ndjp.net/docs/cli/audit/
English: https://useblume.dev/docs/cli/audit

[`blume validate`](/docs/cli/validate/) 读的是你的*内容*；`blume audit` 读的是*构建产物*。它在构建之后遍历 `dist/` 中的 HTML，报告 SEO 与站点健康方面的问题——标题、meta description、canonical、Open Graph 与 X 卡片、标题层级、hreflang、图片、站点地图、`robots.txt` 和结构化数据。

由于站点是 Blume 构建的，每条发现都会指明源文件**以及能修复它的那一行 frontmatter**，而不只是爬虫能看到的 URL：

```
⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.
```

在构建之后运行它：

```bash
blume build
blume audit
```

发现按检查项分组，而不是逐页罗列，因此这份报告读起来就像一份待办清单。用 `--verbose` 可以把每个受影响的页面连同完整细节一起展开，用 `--only`/`--skip` 则可以一次只处理一个类别。`blume audit --list-checks` 会打印完整的检查项目录，它与本页末尾的[检查项目录](#check-catalog)是同一份——每条发现的 `docsUrl` 都链接到那里对应的条目。

## 选项

- `--fail-on error|warning|info` — CI 关卡：达到该级别或更高级别时以非零码退出。默认为 `error`；`--strict` 是 `--fail-on warning` 的别名。
- `--url <origin>` — 同时探测一个线上部署的状态码、响应头和重定向链。
- `--external` — 通过网络探测出站链接。
- `--only <check|category>` / `--skip <check|category>` — 把报告限定在这些检查项或类别之内（或把它们排除），逗号分隔。如果某个词既不对应检查项也不对应类别，就会报错并给出最接近的那一个，因此拼写错误不会悄悄把报告清空。
- `--list-checks` — 打印审查能报告的每一个检查项，然后退出。
- `--verbose` — 列出每一个受影响的页面及每条发现的完整细节，而不只是前几条。
- `--json` — 把报告以 JSON 输出到 stdout。
- `--codex` / `--claude` — 把发现交给 Codex 或 Claude Code 交互式地修复。

## 让 CI 失败

退出码就是约定。默认情况下 `blume audit` 只在 error 上失败——也就是那些确定坏掉的问题，比如链到一个从未构建出来的页面、重定向成环、站点地图无效。仅供参考的发现（描述过短、title 重复）属于 warning，不会让构建失败：

```bash
blume audit                      # 在 error 上失败
blume audit --fail-on warning    # 在 warning 上也失败
```

## 检查线上部署

有些事只有真实服务器才能告诉你：`dist/` 中确实存在的页面会不会因为一条错误的重写规则而真的返回 404、响应有没有被压缩，以及某个 `X-Robots-Tag` 响应头是否正在悄悄地把一个 HTML 看起来完全正常的页面排除在索引之外。把审查指向一个部署即可加上这些检查：

```bash
blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # 同时探测出站链接
```

出站链接是分级判定而不是一律判失败：404 是你可以修好的失效链接，而 403 或 5xx 通常是限流或别人的服务故障，因此只报为警告。

## 用 agent 修复发现的问题

如果你在用 [Codex](https://developers.openai.com/codex/cli) 或 [Claude Code](https://claude.com/claude-code)，审查可以把发现直接交给它：

```bash
blume audit --codex   # 或 --claude
```

它会把完整的 JSON 报告——包含每一个受影响的页面，而不只是终端里那三页预览——写到一个文件，然后交互式打开 agent，并附上一段提示，逐条引导它处理发现：编辑每条发现指明的源文件、采用它建议的修复，然后重新运行 `blume build` 和 `blume audit`，直到报告干净。这个会话是有意设计成交互式的：你通过 agent 自己的权限流程审阅它的修改，而且 agent 会被明确告知，绝不能靠删掉内容来"修好"一条发现。

`--only` 和 `--skip` 收窄交接内容的方式与收窄报告完全一样，因此你可以一次只交给它一个类别。

## 它检查什么、不检查什么

这套检查项有意比通用 SEO 爬虫更窄。这类爬虫报告的很多东西根本不会发生在 Blume 站点上——它从不输出 `rel=nofollow`，Vite 按内容哈希生成的包也不会缺失或重定向——把它们永远报成 0 只会教会你忽略这份报告。

值得明说的局限：

- **结构化数据**只做格式合法性校验（有效的 JSON、有 `@context`、每个节点都有 `@type`）。Blume 不会对照完整的 schema.org 词表或 Google 的富媒体结果规则做校验。
- **对比度**只针对你的主题配置所设置的颜色来检查，而不是逐个元素检查。审查不会渲染页面，因此你在 MDX 或 `theme.css` 里手写的颜色不会被测量。
- **Core Web Vitals**不在检查范围内。它们需要真实浏览器，而一个悄悄什么都没测出来的指标比没有这个指标更糟——因此 `blume audit` 只报告它*能*离线看到的布局偏移原因（没有 `width`/`height` 的图片、过大的资源），其余部分暂时不碰。

审查没有运行的任何检查都会被报为跳过，而不是悄悄判定通过：

```
⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)
```

## 检查项目录 [#check-catalog]

`blume audit` 能报告的每一个检查项，按类别分组，并列出它的默认级别、所属的运行层级以及报告建议的修复方式。`--only` 和 `--skip` 接受这些 id（不写 `BLUME_AUDIT_` 前缀也行）或某个类别的键。键名并不总是分类标题本身，所以请用这张表：`blume audit --only i18n`，而不是 `--only Internationalization`。

| 类别 | 键 |
| --- | --- |
| 无障碍 | `accessibility` |
| 内容 | `content` |
| 重复内容 | `duplicates` |
| 可索引性 | `indexability` |
| 链接 | `links` |
| 重定向 | `redirects` |
| 社交卡片 | `social` |
| 国际化 | `i18n` |
| 资源 | `assets` |
| 站点地图 | `sitemap` |
| robots.txt | `robots` |
| AI 可发现性 | `ai` |
| 结构化数据 | `structured-data` |
| 线上部署 | `network` |

### 内容

#### 缺少 title 标签或为空 [#title-missing]

`BLUME_AUDIT_TITLE_MISSING` · error · 来自构建后的 HTML

修复：在该页面的 frontmatter 中添加 `title`。

#### 存在多个 title 标签 [#title-multiple]

`BLUME_AUDIT_TITLE_MULTIPLE` · error · 来自构建后的 HTML

修复：从页面的布局或 MDX 中删掉多余的 `<title>`。

#### title 过长或过短 [#title-length]

`BLUME_AUDIT_TITLE_LENGTH` · warning · 来自构建后的 HTML

修复：重写 frontmatter 中的 `title`，使其符合长度范围。

#### 缺少 meta description 或为空 [#description-missing]

`BLUME_AUDIT_DESCRIPTION_MISSING` · warning · 来自构建后的 HTML

修复：在该页面的 frontmatter 中添加 `description`。

#### 存在多个 meta description 标签 [#description-multiple]

`BLUME_AUDIT_DESCRIPTION_MULTIPLE` · error · 来自构建后的 HTML

修复：从页面的布局或 MDX 中删掉多余的 description `<meta>`。

#### meta description 过长或过短 [#description-length]

`BLUME_AUDIT_DESCRIPTION_LENGTH` · warning · 来自构建后的 HTML

修复：重写 frontmatter 中的 `description`，使其符合长度范围。

#### 缺少 H1 标签或为空 [#h1-missing]

`BLUME_AUDIT_H1_MISSING` · warning · 来自构建后的 HTML

修复：给该页面一个 `title`——Blume 会把它渲染成页面的 `<h1>`。

#### 存在多个 H1 标签 [#h1-multiple]

`BLUME_AUDIT_H1_MULTIPLE` · warning · 来自构建后的 HTML

修复：把正文中多余的 `# 标题` 降为 `##`——Blume 已经把 `title` 渲染成 h1 了。

#### 字数过少 [#low-word-count]

`BLUME_AUDIT_LOW_WORD_COUNT` · info · 来自构建后的 HTML

修复：扩充该页面，或把它并入一个更大的页面。

#### 标题层级跳级（例如 h2 跳到 h4）[#heading-skip]

`BLUME_AUDIT_HEADING_SKIP` · info · 来自构建后的 HTML

修复：把标题下调一级——跳过的层级会破坏目录的嵌套和屏幕阅读器的大纲。

#### 页面日期落在未来 [#future-dated-page]

`BLUME_AUDIT_FUTURE_DATED_PAGE` · info · 来自构建后的 HTML

修复：改正 `date`，或者把这个页面压后到它本该上线的时候。

#### 未设置 viewport [#viewport-missing]

`BLUME_AUDIT_VIEWPORT_MISSING` · error · 来自构建后的 HTML

修复：在你导出的布局中恢复 viewport `<meta>`。

### 重复内容

#### 重复的 title [#duplicate-title]

`BLUME_AUDIT_DUPLICATE_TITLE` · warning · 来自构建后的 HTML

修复：给每个页面一个各不相同的 `title`——搜索引擎会把它当作结果标题展示。

#### 重复的 meta description [#duplicate-description]

`BLUME_AUDIT_DUPLICATE_DESCRIPTION` · warning · 来自构建后的 HTML

修复：给每个页面一个各不相同的 `description`。

#### 重复页面且没有 canonical [#duplicate-content]

`BLUME_AUDIT_DUPLICATE_CONTENT` · warning · 来自构建后的 HTML

修复：合并这些页面，或在其中除一个之外都设置 `seo.canonical`。

### 可索引性

#### 未设置 deployment.site [#site-not-set]

`BLUME_AUDIT_SITE_NOT_SET` · warning · 来自构建后的 HTML

修复：在 blume.config.ts 中把 `deployment.site` 设为站点的公开 URL。

#### deployment.site 在部署时推断得出 [#site-inferred-at-deploy]

`BLUME_AUDIT_SITE_INFERRED_AT_DEPLOY` · info · 来自构建后的 HTML

修复：审查一次接近生产的构建（例如 `VERCEL=1 VERCEL_PROJECT_PRODUCTION_URL=<host> blume build`），或用 `--url <origin>` 直接审查部署本身。不要把 `deployment.site` 写死——平台会在每次部署时设置它。

#### 页面是 noindex 却声明了 canonical [#canonical-on-noindex]

`BLUME_AUDIT_CANONICAL_ON_NOINDEX` · warning · 来自构建后的 HTML

修复：从 noindex 页面上删掉 canonical——Google 认为这种组合自相矛盾，可能两个都不采纳。

#### 构建产物中包含草稿页面 [#draft-page-published]

`BLUME_AUDIT_DRAFT_PAGE_PUBLISHED` · warning · 来自构建后的 HTML

修复：部署前不带 `--preview` 重新构建；如果该页面已经可以发布，就删掉 `draft: true`。

#### 缺少 canonical URL [#canonical-missing]

`BLUME_AUDIT_CANONICAL_MISSING` · warning · 来自构建后的 HTML

修复：设置 `deployment.site`，让 Blume 能输出绝对的 canonical URL。

#### 页面自身的 canonical 不指向自己 [#canonical-not-self]

`BLUME_AUDIT_CANONICAL_NOT_SELF` · info · 来自构建后的 HTML

修复：把 `seo.canonical` 指向该页面自身，或删掉它以使用默认的自指 canonical。

#### canonical 指向了失效或会重定向的页面 [#canonical-bad-target]

`BLUME_AUDIT_CANONICAL_BAD_TARGET` · error · 来自构建后的 HTML

修复：把 `seo.canonical` 指向一个确实存在且不会重定向的页面。

#### canonical 的协议与站点不一致 [#canonical-protocol-mismatch]

`BLUME_AUDIT_CANONICAL_PROTOCOL_MISMATCH` · error · 来自构建后的 HTML

修复：让 `seo.canonical` 使用与 `deployment.site` 相同的协议。

#### 页面不可索引 [#robots-meta-unexpected]

`BLUME_AUDIT_ROBOTS_META_UNEXPECTED` · info · 来自构建后的 HTML

修复：如果该页面本应被索引，就从它的 frontmatter 中删掉 `noindex`。

#### 页面超出 Googlebot 的 2 MB 抓取上限 [#html-too-large]

`BLUME_AUDIT_HTML_TOO_LARGE` · error · 来自构建后的 HTML

修复：拆分该页面——Googlebot 读取一个 HTML 文档到 2 MB 就停。

#### X-Robots-Tag 响应头与页面的 robots meta 冲突 [#robots-header-conflict]

`BLUME_AUDIT_ROBOTS_HEADER_CONFLICT` · error · 需要 `--url`

修复：删掉 X-Robots-Tag 响应头，或让它与页面的 robots meta 保持一致。

### 链接

#### 页面链到了失效页面 [#link-to-broken]

`BLUME_AUDIT_LINK_TO_BROKEN` · error · 来自构建后的 HTML

修复：修好链接目标，或把它指向的页面创建出来。

#### 页面链到了重定向 [#link-to-redirect]

`BLUME_AUDIT_LINK_TO_REDIRECT` · warning · 来自构建后的 HTML

修复：直接链到最终目标，而不是经过重定向。

#### 孤立页面（只能从导航到达）[#orphan-page]

`BLUME_AUDIT_ORPHAN_PAGE` · warning · 来自构建后的 HTML

修复：从某个相关页面的正文中链到这个页面。

#### 站内链接写死了站点自己的 origin [#internal-link-absolute]

`BLUME_AUDIT_INTERNAL_LINK_ABSOLUTE` · warning · 来自构建后的 HTML

修复：使用相对于根的路径（`/docs/x`），这样链接在预览环境和 `basePath` 下都有效。

#### 页面的出站站内链接带有 nofollow [#internal-link-nofollow]

`BLUME_AUDIT_INTERNAL_LINK_NOFOLLOW` · info · 来自构建后的 HTML

修复：去掉 `rel="nofollow"`——它会阻止该页面在站内传递权重。

#### URL 中出现双斜杠 [#double-slash-url]

`BLUME_AUDIT_DOUBLE_SLASH_URL` · error · 来自构建后的 HTML

修复：检查 `basePath` / `deployment.base`——那里多一个结尾斜杠就会产生 `//`。

#### 链接片段在目标页面上找不到对应 id [#anchor-broken]

`BLUME_AUDIT_ANCHOR_BROKEN` · warning · 来自构建后的 HTML

修复：把片段指向目标页面上确实存在的标题，或修正它本该指向的那个标题。

#### URL 中含有大写字母、下划线或空格 [#url-style]

`BLUME_AUDIT_URL_STYLE` · info · 来自构建后的 HTML

修复：把源文件重命名为全小写、用连字符连接的 slug——如果旧 URL 已经发布过，还要为它添加一个重定向。

### 重定向

#### 失效的重定向 [#redirect-broken]

`BLUME_AUDIT_REDIRECT_BROKEN` · error · 来自构建后的 HTML

修复：把重定向指向一个确实存在的页面。

#### 重定向成环 [#redirect-loop]

`BLUME_AUDIT_REDIRECT_LOOP` · error · 来自构建后的 HTML

修复：打断 `redirects` 里的环——它永远无法收敛。

#### 重定向链 [#redirect-chain]

`BLUME_AUDIT_REDIRECT_CHAIN` · warning · 来自构建后的 HTML

修复：让每一跳都直接指向最终目标。

#### meta refresh 重定向 [#meta-refresh]

`BLUME_AUDIT_META_REFRESH` · warning · 来自构建后的 HTML

修复：在 `blume.config.ts` 里用真正的重定向代替 meta refresh。

#### 重定向的来源同时也是一个真实页面 [#redirect-source-is-page]

`BLUME_AUDIT_REDIRECT_SOURCE_IS_PAGE` · error · 来自构建后的 HTML

修复：删掉这个重定向，或删掉被它遮蔽的那个页面——页面会胜出，重定向永远不会触发。

#### 从 HTTPS 重定向到 HTTP [#redirect-to-http]

`BLUME_AUDIT_REDIRECT_TO_HTTP` · error · 需要 `--url`

修复：重定向到 HTTPS 的 URL。

### 社交卡片

#### 缺少 Open Graph 标签或标签不完整 [#og-incomplete]

`BLUME_AUDIT_OG_INCOMPLETE` · warning · 来自构建后的 HTML

修复：添加一个 `description`——其余 Open Graph 标签 Blume 会替你补齐。

#### 缺少 Open Graph 图片 [#og-image-missing]

`BLUME_AUDIT_OG_IMAGE_MISSING` · warning · 来自构建后的 HTML

修复：设置 `deployment.site` 以启用生成的 OG 图片，或在该页面上设置 `seo.image`。

#### Open Graph 图片不在构建产物中 [#og-image-broken]

`BLUME_AUDIT_OG_IMAGE_BROKEN` · warning · 来自构建后的 HTML

修复：把 `seo.image` 指向一个确实存在的文件，或者重新构建——失效的 og:image 会让这个页面在各处被分享时都渲染成一张空白卡片。

#### Open Graph 图片对大卡片来说太小 [#og-image-small]

`BLUME_AUDIT_OG_IMAGE_SMALL` · warning · 来自构建后的 HTML

修复：使用至少 1200×630 的图片——更小的会渲染模糊，或被裁成小卡片版式。

#### Open Graph URL 与 canonical 不匹配 [#og-url-mismatch]

`BLUME_AUDIT_OG_URL_MISMATCH` · warning · 来自构建后的 HTML

修复：让 `og:url` 与页面的 canonical URL 保持一致。

#### 缺少 X（Twitter）卡片或卡片不完整 [#twitter-card-incomplete]

`BLUME_AUDIT_TWITTER_CARD_INCOMPLETE` · warning · 来自构建后的 HTML

修复：在 blume.config.ts 中设置 `seo.x.handle`，让 X 能够归属这张卡片。

### 国际化

#### 缺少 HTML lang 属性 [#html-lang-missing]

`BLUME_AUDIT_HTML_LANG_MISSING` · error · 来自构建后的 HTML

修复：在你导出的布局中恢复 `<html>` 上的 `lang` 属性。

#### HTML lang 属性无效 [#html-lang-invalid]

`BLUME_AUDIT_HTML_LANG_INVALID` · error · 来自构建后的 HTML

修复：为该语言使用合法的 BCP 47 标签（例如 `en`、`en-GB`）。

#### hreflang 与 HTML lang 不一致 [#hreflang-lang-mismatch]

`BLUME_AUDIT_HREFLANG_LANG_MISMATCH` · error · 来自构建后的 HTML

修复：该页面的 `<html lang>` 必须与它自己的 hreflang 标注一致。

#### hreflang 标注无效 [#hreflang-invalid]

`BLUME_AUDIT_HREFLANG_INVALID` · error · 来自构建后的 HTML

修复：在 hreflang 标注中使用合法的 BCP 47 标签。

#### 缺少自引用的 hreflang 标注 [#hreflang-self-missing]

`BLUME_AUDIT_HREFLANG_SELF_MISSING` · warning · 来自构建后的 HTML

修复：一个页面的 hreflang 集合必须包含一条自引用。

#### 缺少 x-default 的 hreflang 标注 [#hreflang-xdefault-missing]

`BLUME_AUDIT_HREFLANG_XDEFAULT_MISSING` · info · 来自构建后的 HTML

修复：添加一个 `x-default` 备选项，指向默认语言下的页面。

#### hreflang 缺少互指（没有回指标签）[#hreflang-no-return-tag]

`BLUME_AUDIT_HREFLANG_NO_RETURN_TAG` · error · 来自构建后的 HTML

修复：hreflang 组中的每个页面都必须链回组内的其它每一个页面。

#### hreflang 指向了失效、会重定向或非 canonical 的页面 [#hreflang-bad-target]

`BLUME_AUDIT_HREFLANG_BAD_TARGET` · error · 来自构建后的 HTML

修复：把 hreflang 备选项指向一个确实存在且为 canonical 的页面。

#### hreflang 组存在语言冲突 [#hreflang-conflict]

`BLUME_AUDIT_HREFLANG_CONFLICT` · error · 来自构建后的 HTML

修复：hreflang 组中的每种语言必须恰好对应一个页面。

### 无障碍

这些检查跑在你的主题配置上，而不是逐页进行：一个主题色是整个站点的统一选择。检查会像构建那样解析颜色（每种模式取预设的色阶，填充色上配白色或深色标签），并把主题绘制的每一种文字颜色与 WCAG AA 对正文的对比度要求 4.5:1 相比，在浅色和深色模式下都会测量。

#### 主题颜色未达到 WCAG AA 对比度 [#theme-contrast-low]

`BLUME_AUDIT_THEME_CONTRAST_LOW` · warning · 来自主题配置

修复：用 `theme.accent: { light, dark }` 为每种模式分别挑选——浅色模式选更深的色阶，深色模式选更浅的。

它检查页面上的强调色文字、强调色与 `action` 填充上的标签，以及自定义 `background` 上的正文与次要文字。每条发现都会指明那一对颜色、所属模式以及它们的比值。

#### 主题颜色无法检查对比度 [#theme-color-unchecked]

`BLUME_AUDIT_THEME_COLOR_UNCHECKED` · info · 来自主题配置

修复：把颜色写成十六进制、`rgb()`、`hsl()`、`hwb()`、`lab()`、`lch()`、`oklab()`、`oklch()` 或一个具名颜色，这样它的对比度才能被检查。

### 资源

#### 缺少 alt 文本 [#image-alt-missing]

`BLUME_AUDIT_IMAGE_ALT_MISSING` · warning · 来自构建后的 HTML

修复：添加有描述性的 `alt` 文本；如果图片是纯装饰性的，则写 `alt=""`。

#### 图片失效 [#image-broken]

`BLUME_AUDIT_IMAGE_BROKEN` · error · 来自构建后的 HTML

修复：修好图片路径，或把该文件加入 public/。

#### 资源文件过大 [#asset-too-large]

`BLUME_AUDIT_ASSET_TOO_LARGE` · warning · 来自构建后的 HTML

修复：压缩该资源，或改用现代格式（WebP/AVIF）提供。

#### 图片没有 width/height [#image-missing-dimensions]

`BLUME_AUDIT_IMAGE_MISSING_DIMENSIONS` · warning · 来自构建后的 HTML

修复：设置 `width` 和 `height`，让浏览器能预留空间（避免布局偏移）。

#### 引用的脚本、样式或资源不在构建产物中 [#subresource-missing]

`BLUME_AUDIT_SUBRESOURCE_MISSING` · error · 来自构建后的 HTML

修复：修好这处引用，或把缺失的文件补回来。

#### HTTPS/HTTP 混合内容 [#mixed-content]

`BLUME_AUDIT_MIXED_CONTENT` · error · 来自构建后的 HTML

修复：通过 HTTPS 加载该子资源——浏览器会拦截混合内容。

### 站点地图

#### 可索引页面不在站点地图中 [#indexable-page-not-in-sitemap]

`BLUME_AUDIT_INDEXABLE_PAGE_NOT_IN_SITEMAP` · warning · 来自构建后的 HTML

修复：如果该页面本应被索引，就从它的 frontmatter 中删掉 `draft`/`hidden`/`noindex`。

#### noindex 页面出现在站点地图中 [#noindex-in-sitemap]

`BLUME_AUDIT_NOINDEX_IN_SITEMAP` · error · 来自构建后的 HTML

修复：noindex 页面不应该在站点地图中被公布。

#### 非 canonical 页面出现在站点地图中 [#non-canonical-in-sitemap]

`BLUME_AUDIT_NON_CANONICAL_IN_SITEMAP` · error · 来自构建后的 HTML

修复：站点地图中只列出 canonical URL。

#### 站点地图列出了不存在或会重定向的页面 [#sitemap-bad-url]

`BLUME_AUDIT_SITEMAP_BAD_URL` · error · 来自构建后的 HTML

修复：从站点地图中删掉该 URL，或把它指名的页面构建出来。

#### 站点地图有语法错误或格式不对 [#sitemap-invalid]

`BLUME_AUDIT_SITEMAP_INVALID` · error · 来自构建后的 HTML

修复：站点地图必须是 sitemaps.org 的 urlset 或 sitemap index 格式的有效 XML。

#### 站点地图超过 50 MB 或 50,000 个 URL [#sitemap-too-large]

`BLUME_AUDIT_SITEMAP_TOO_LARGE` · error · 来自构建后的 HTML

修复：拆分站点地图——上限是 50 MB 和 50,000 个 URL。

#### 站点地图的 lastmod 无效或落在未来 [#sitemap-lastmod-invalid]

`BLUME_AUDIT_SITEMAP_LASTMOD_INVALID` · warning · 来自构建后的 HTML

修复：使用一个不在未来的、合规的 W3C 日期——一旦发现站点地图在新鲜度上撒谎，搜索引擎就会彻底不再信任它的 lastmod。

#### 站点地图中包含超出其范围的 URL [#sitemap-out-of-scope]

`BLUME_AUDIT_SITEMAP_OUT_OF_SCOPE` · warning · 来自构建后的 HTML

修复：站点地图只能列出与它自身 origin 相同的 URL。

#### 站点地图无法访问 [#sitemap-not-accessible]

`BLUME_AUDIT_SITEMAP_NOT_ACCESSIBLE` · error · 需要 `--url`

修复：让 sitemap.xml 可以在站点根路径下访问。

### robots.txt

#### 缺少 robots.txt [#robots-missing]

`BLUME_AUDIT_ROBOTS_MISSING` · warning · 来自构建后的 HTML

修复：设置 `seo.robots: true` 以生成 robots.txt。

#### robots.txt 有语法错误 [#robots-invalid]

`BLUME_AUDIT_ROBOTS_INVALID` · error · 来自构建后的 HTML

修复：robots.txt 的每一行都必须是 `Field: value` 形式的指令或一条注释。

#### robots.txt 禁止了一个在站点地图中的页面 [#robots-disallows-indexable]

`BLUME_AUDIT_ROBOTS_DISALLOWS_INDEXABLE` · error · 来自构建后的 HTML

修复：一个页面不能既在 robots.txt 中被禁止、又在站点地图中被公布。

#### robots.txt 没有引用站点地图 [#robots-sitemap-missing]

`BLUME_AUDIT_ROBOTS_SITEMAP_MISSING` · info · 来自构建后的 HTML

修复：设置 `deployment.site`，让 robots.txt 能引用站点地图。

#### robots.txt 无法访问 [#robots-not-accessible]

`BLUME_AUDIT_ROBOTS_NOT_ACCESSIBLE` · error · 需要 `--url`

修复：让 robots.txt 可以在站点根路径下访问。

### AI 可发现性

#### 构建产物中缺少 llms.txt [#llms-txt-missing]

`BLUME_AUDIT_LLMS_TXT_MISSING` · warning · 来自构建后的 HTML

修复：重新构建——`agents.llmsTxt` 已启用，但构建中没有 llms.txt。如果这是有意为之，请设置 `agents.llmsTxt: false`。

#### llms.txt 列出了构建并不提供的页面 [#llms-txt-stale-entry]

`BLUME_AUDIT_LLMS_TXT_STALE_ENTRY` · warning · 来自构建后的 HTML

修复：重新构建，让 llms.txt 与站点一致——一条过时的条目会把 AI agent 送到一个并不存在的页面。

#### 可索引页面在 llms.txt 中缺失 [#llms-txt-page-missing]

`BLUME_AUDIT_LLMS_TXT_PAGE_MISSING` · warning · 来自构建后的 HTML

修复：重新构建，让 llms.txt 与站点一致；如果该页面是有意排除的，就在它的 frontmatter 中设置 `ai.exclude: true`。

#### 没有 DNS-AID 的 agent 发现记录 [#dns-aid-missing]

`BLUME_AUDIT_DNS_AID_MISSING` · info · 需要 `--url`

修复：在你的 DNS 服务商处为 `_index._agents.<host>` 发布一条 ServiceMode SVCB 或 HTTPS 记录，让 agent 能通过 DNS（DNS-AID）发现该站点。

#### DNS-AID 记录没有 DNSSEC 认证 [#dns-aid-unsigned]

`BLUME_AUDIT_DNS_AID_UNSIGNED` · info · 需要 `--url`

修复：为该区域启用 DNSSEC，让带验证的解析器返回经过认证的 DNS-AID 应答；如果你的 DNS 服务商不支持 DNSSEC，这些记录在未签名的情况下仍然有效。

### 结构化数据

#### 结构化数据不是有效的 JSON [#jsonld-invalid]

`BLUME_AUDIT_JSONLD_INVALID` · error · 来自构建后的 HTML

修复：JSON-LD 块必须是有效的 JSON。

#### 结构化数据缺少必需属性 [#jsonld-incomplete]

`BLUME_AUDIT_JSONLD_INCOMPLETE` · warning · 来自构建后的 HTML

修复：每个 JSON-LD 节点都需要 `@context` 和 `@type`。

### 线上部署

#### 4XX 页面 [#http-4xx]

`BLUME_AUDIT_HTTP_4XX` · error · 需要 `--url`

修复：该页面被链接或在站点地图中，但部署后访问它得到 404。

#### 5XX 页面 [#http-5xx]

`BLUME_AUDIT_HTTP_5XX` · error · 需要 `--url`

修复：部署后访问该页面时报错。

#### 请求超时 [#http-timeout]

`BLUME_AUDIT_HTTP_TIMEOUT` · error · 需要 `--url`

修复：该页面没有及时响应。

#### 未压缩 [#not-compressed]

`BLUME_AUDIT_NOT_COMPRESSED` · warning · 需要 `--url`

修复：在主机上启用 gzip 或 brotli。

#### 页面响应缓慢 [#slow-response]

`BLUME_AUDIT_SLOW_RESPONSE` · warning · 需要 `--url`

修复：该页面响应很慢。

#### 外链失效 [#external-link-broken]

`BLUME_AUDIT_EXTERNAL_LINK_BROKEN` · error · 需要 `--external`

修复：修好或删掉这个出站链接。

#### 外链发生重定向 [#external-link-redirect]

`BLUME_AUDIT_EXTERNAL_LINK_REDIRECT` · info · 需要 `--external`

修复：直接链到最终目标。

---

# doctor
Source: https://blume.ndjp.net/docs/cli/doctor/
English: https://useblume.dev/docs/cli/doctor

`blume doctor` 与 `blume build` 完全一样地扫描项目并报告发现的问题，不生成也不构建任何东西。当构建因为某个不明显的原因失败时，第一个该运行的就是它；它也是一道放进 CI 的廉价关卡：

```bash
blume doctor
```

## 检查内容

- **Node 版本**与已安装的 `blume` 包所支持的版本范围是否吻合，这个范围读自它自己的 `engines` 字段。超出该范围是一个警告：可能照样能跑，但它不属于 Blume 测试过的组合。
- **`blume.config.ts`**，执行与构建完全相同的校验。被移除或改名的键会带着指明替代项的提示而失败，而不是只丢一句"无法识别的键"。
- **每一个内容页面和文件夹元数据**：`blume dev` 与 `blume build` 在加载项目时会打印的那些诊断——frontmatter 无效、导航问题、include 目标缺失等等——全部汇总成一份报告。
- **需要服务端的功能**出现在一个配置为静态输出的站点上——助手、MCP 服务器、Try it playground 内置的代理，或服务端模式的搜索（Mixedbread）：给出一个指明该功能的错误，并说明应当切换到哪个部署适配器（如果宿主适配器被设成了 `output: "static"`，则提示你去掉这个选项）。
- **配置需要却没有安装的包**——某个搜索、内容源或助手适配器所导入的 SDK，某个部署适配器的 `@astrojs/*` 包，或 Vue、Svelte 交互岛所需的渲染器：逐个给出指明包的错误，并附上适合你所用包管理器的安装命令。`blume build` 在同一项检查上会直接停下。
- **Blume 无法预先分析的 `components.ts` 覆盖项**——内联的或计算得来的条目，或者指向一个并不存在的文件的 import：每一处都给出一个错误，并标明它所在的行。
- 在没有配置 `versions` 的站点上出现**形似版本的目录**（`v1.0/`）——否则它会被当作普通内容构建：给出一个指向 [`blume version`](/docs/cli/version/) 的警告。
- **已启用的功能会读取、却并未设置的密钥**，例如 `MIXEDBREAD_API_KEY` 或 `OPENROUTER_API_KEY`：给出一个指明变量名的警告。和 `blume dev`、`blume build` 一样，doctor 会先加载 `.env` 和 `.env.local`。

## 摘要

诊断之后，doctor 会打印项目最终解析出的配置，这样你以为自己配好的东西与 Blume 实际看到的东西之间的落差就一目了然：页面数量、输出模式与部署适配器、搜索服务、已配置的参考文档、分析、内容源适配器，以及助手是否开启、它用的是哪个后端。

## 退出码与 JSON

存在 error 级诊断时 doctor 以非零码退出，因此凡是会卡住构建的问题它都会卡住 CI；警告只作报告，不会失败。`--json` 会把诊断以 JSON 输出到 stdout，替代终端报告，结构与 [`blume validate --json`](/docs/cli/validate/) 相同。

---

# eval
Source: https://blume.ndjp.net/docs/cli/evals/
English: https://useblume.dev/docs/cli/evals

`blume audit` 告诉你爬虫能否找到你的文档。`blume eval` 告诉你别人是否真的*用得动*它：一个 AI agent 会像陌生人那样读你的文档，并试着从中回答真实用户提出的问题。当文档里没有写明答案时，这次运行会失败，并指出本该写明它的那个页面。

```bash
blume eval
```

```
blume eval  4 question(s) · Codex

  ✔ install-node-version         pass  1.00  14.2s
  ✔ custom-domain                pass  0.92  21.3s
  ✖ deploy-vercel                fail  0.40  38.9s
      missing: deployment: vercel() from blume/deploy
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: deployment: vercel() from blume/deploy

  2 passed · 1 failed · 1 skipped · 1m 42s
```

## 工作方式

每个问题会经过两轮 agent 会话，使用你已经装好的某个 agent CLI——默认是 [Codex](https://developers.openai.com/codex/cli)，或者用 `--agent claude` 换成 [Claude Code](https://claude.com/claude-code)。Blume 不保存任何 API 密钥，也不自己调用任何模型。使用 Codex 时，两轮会话都不会拿到 Codex 的 shell、命令和图像工具，也不会继承你任何环境变量。

1. **读者**只*依靠*你的文档来回答问题。它在一个空目录中运行，文件、shell 和网络工具都被禁用，连接到一个为你提供文档的私有 [MCP 服务器](/docs/discoverability/mcp/)——与真实 agent 对着已部署站点所用的是同一组 `search_docs`/`get_page` 工具。它读不到你的仓库，因此它体验文档的方式与一个全新用户完全相同：没写下来的东西就等于不存在。
2. **评判者**完全不带任何工具，按你列出的事实给答案打分。换一种说法照样通过；漏掉或与之相悖则不通过——"文档里没写"同样算不通过。

这份 MCP 快照直接由你的内容源构建，因此无需先运行 `blume build`，也不会把任何东西部署或上传到别处。

文档*无法*支撑的答案，即便碰巧与 agent 的先验知识相符也判为失败——这正是重点所在。只有你的文档会随产品一起发布。

## 编写 eval

问题写在项目根目录的 `evals.yaml` 里。让一个 agent 根据你现有的文档起草一份起始文件：

```bash
blume eval init
```

或者手写：

```yaml
questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - "server features need deployment: vercel() from blume/deploy"
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - Orama is the default, with no hosted service
    severity: warning # 未答中只警告，不让 CI 失败
    skip: true # 暂时排除，报告为 skipped
```

- `expected` 列出正确答案必须在实质上说明的事实——评判者接受换一种说法，拒绝相互矛盾。
- `routes` 指明本该回答该问题的页面。这样一来，失败在报告里就会锚定到那个页面的源文件；某个提示如果已经对不上任何页面，会给出警告，而不是被悄悄丢弃。
- `severity: warning` 让某个问题仍留在报告里，但不会让 CI 失败；`skip: true` 则把某个问题整个排除在外。

就写你的用户真正会问的问题——来自支持会话、GitHub issue 和上手通话里的那些。最好的 eval 会把文档作出的一项承诺（"零配置部署"）编码成一个问题，当某个 PR 违背这份承诺时它就会失败。

## 让 CI 失败

退出码就是约定：任何一道问题失败都会返回非零，`severity: warning` 的除外——它的缺失只报为警告，永远不计入这道关卡或 `--threshold`。当 agent 运行本身失败时——读者或评判者直接报错、根本没给出评分——报告里会写 `run failed:`，并指向你 eval 文件里的那道问题，而不会指出某个要去修的文档页面，因为文档压根没被评分。当你想从积压的问题里慢慢清理时，可以用 `--threshold` 把关卡放宽为一个通过比例：

```bash
blume eval                    # 每个问题都必须通过
blume eval --threshold 0.8    # 至少 80% 必须通过
blume eval --json             # 在 stdout 上输出机器可读的报告
```

JSON 报告的结构与 `blume validate --json` 和 `blume audit --json` 相同，都是 `diagnostics` + `summary`，另外还并列给出每道问题的结果（答案、得分、缺失的事实、成本）。

由于每道问题都要两轮模型会话，一次 eval 运行会实实在在地花掉时间和金钱——单道问题的开销会在运行过程中打印出来。合理的 CI 配置是在文档发生变化时运行 `blume eval`，而不是每次 push 都跑一遍。

## 修复发现的问题

每次失败都会指出缺失的事实，以及本该写明它们的页面。想把整份报告交给 agent 处理：

```bash
blume eval --fix
```

它会把完整的 JSON 报告写到一个文件，然后交互式打开 agent，并附上一段提示，逐道失败问题引导它：读那个指明的页面，用该页面的语气补上缺失的事实，然后重新运行 `blume eval` 直到全部通过。这个会话是有意设计成交互式的——你通过 agent 自己的权限流程审阅它的修改——而且 agent 会被明确告知：绝不能靠删掉问题或削弱预期事实来把结果刷绿。

## 选项

- `--agent codex|claude` — 由哪个 agent CLI 扮演读者和评判者。默认为 `codex`。
- `--file <path>` — eval 文件，相对于项目根目录或使用绝对路径。默认为 `evals.yaml`。
- `--threshold <0..1>` — 通过比例低于该值时，本次运行以非零码退出，其中 `severity: warning` 的缺失算作通过。默认为 `1`。空值属于错误，因此 `--threshold "$EVAL_THRESHOLD"` 在变量未设置时无法把关卡关掉。
- `--timeout <seconds>` — 每道问题中读者阶段的时间上限。默认为 `180`，最大为 `2147483`（约 24 天），这已是定时器所能等待的最长时间。
- `--json` — 把报告以 JSON 输出到 stdout。
- `--fix` — 运行失败后，把报告交给 agent 交互式地修复文档。
- `--verbose` — 在每条失败下面附上读者的完整回答。

---

# translate
Source: https://blume.ndjp.net/docs/cli/translate/
English: https://useblume.dev/docs/cli/translate

一旦[国际化](/docs/content/i18n/)开启，对源页面的每一次编辑都会悄悄地让它已有的翻译过时。`blume translate` 补上了这个闭环：它精确算出每种语言下哪些页面缺失或过时，用本地 agent CLI 以无头方式翻译它们，并把做过的事记录进一份随代码提交的台账，好让下一次运行——以及 CI——知道哪些是最新的。

```bash
blume translate --codex
```

```
blume translate  3 item(s) · 2 locale(s) · Codex

  ✔ docs/guides/install.mdx → fr 24.2s
  ✔ docs/guides/install.mdx → de 22.8s
  ✔ meta titles (2) → de 4.1s

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s
```

## 工作方式

整条流水线由 Blume 掌控，agent 只负责翻译文本。对每个需要处理的文件，Blume 会构建一段翻译提示，在禁用文件、shell 和网络工具的情况下无头运行 agent CLI，校验回复的结构，然后自己写出目标文件——`--codex` 用 [Codex](https://developers.openai.com/codex/cli)，`--claude` 用 [Claude Code](https://claude.com/claude-code)。Blume 不保存任何 API 密钥，也不自己调用任何模型。

每一次通过校验的写入都会记录在项目根目录的 `blume.translations.json` 中：按源文件与语言，记录下翻译那一刻源文件的哈希。**请提交这个文件。** 重跑时正是靠它区分"已经翻译过"和"翻译过，但源文件此后又变了"——也是它让 CI 关卡得以成立。

每处理完一个文件台账就会落盘，因此中途停下一次长时间运行（Ctrl+C）最多只会丢掉正在处理中的那几个翻译——下一次运行会从你停下的地方接着来。文件默认每次并行处理 4 个；如果你的机器和 agent 的速率限制吃得消，可以用 `--concurrency` 调高。

重跑是增量的：自上次翻译以来没有变化的源文件会被跳过，因此改完一个页面再运行 `blume translate`，每种语言只会翻译这一个页面。过时的页面被重新翻译时，agent 会看到已有的译文，并被要求对齐它的语体、方言和术语——源文件改了一段，译文 diff 就只该是一段，而不是从头重写。

首次翻译没有先例可循，所以要提前用[语言上的 `style`](/docs/content/i18n/)（`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`）把选择钉死。这条指引会随每一段翻译提示一起送过去；已有译文若与之不一致，以 `style` 为准——因此一次重新翻译也会把较早的页面往所配置的语体上带一带。

## 会被翻译的内容

- **页面**——默认语言下的 `.md`/`.mdx` 文件。agent 会翻译正文，只翻译人眼可见的 frontmatter 值（`title`、`description`、`sidebar.label`、`sidebar.badge`、`seo.title`、`seo.description`）。目标路径遵循你的解析器：在 `dir` 下是 `fr/guides/install.mdx`，在 `dot` 下是 `guides/install.fr.mdx`。已经存在的译文会在它所在的位置被重写，即便用的是另一个名字（手写的 `fr/guides/install.md`），因此重新翻译绝不会给同一个页面添上第二份副本。
- **文件夹导航标题**——在 `dir` 解析器下，每种语言所需的 [`meta.ts`](/docs/content/meta/)标题会在一次批量调用中翻译完成，而生成的各语言 `meta.ts` 会逐字复制其余每个键（`order`、`pages`、`icon`、`collapsed`），使该语言的侧边栏保持原有排序。它会写进磁盘上该语言已存在的目录里（配置为 `pt-BR` 时就是 `pt-br/`），如果那里已经有一个 `meta.js` 或 `meta.mjs`，它会被重写，而不是在旁边多出一个 `meta.ts`。

你手写的翻译会被**采纳，绝不覆盖**：已存在却没有台账条目的译文会被标记为最新并原样保留，只有 `--force` 才会重新翻译它。

## 校验

结构从来不会被托付给 agent。写入之前，Blume 会检查每一份回复，并根据源文件重建目标文件：

- frontmatter 由源文件的数据重建，只把六个可翻译的值覆盖上去——agent 凭空发明的键会被丢掉，它删掉的键会被恢复，而 `slug`、`icon`、`order` 和日期从构造上就与源文件逐字一致。
- 代码围栏的数量必须与源文件一致，正文不能为空，frontmatter 必须能解析。
- 除非译文里已经固定了自己的锚点，否则每个标题都会用一个结尾的 [`[#id]` 标记](/docs/content/syntax/)钉在源标题的锚点 id 上，这样 `#fragment` 链接在任何语言里都解析到同一处。标题按位置一一配对，因此标题结构与源文件不匹配的译文不会得到任何锚点。

校验未通过的回复不会写入任何内容——该项会被报为失败，本次运行继续往下走。所有成功的条目仍留在台账里，因此重跑时只会重试那些失败项。

## 让 CI 失败

`blume translate --check` 是只读的关卡：它报告每一对缺失或过时的内容，一旦存在偏差就以非零码退出，全程不运行 agent、不写任何东西。

```bash
blume translate --check           # 翻译缺失或过时则以 1 退出
blume translate --check --json    # 在 stdout 上输出机器可读的偏差报告
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

JSON 报告的结构与 `blume validate --json`、`blume audit --json` 和 `blume eval --json` 相同，都是 `diagnostics` + `summary`，偏差按语言分组。每一个缺失或过时的翻译都是一条 error 级诊断（`BLUME_TRANSLATE_MISSING`、`BLUME_TRANSLATE_STALE`），因此 `summary.error` 与退出码一致。手工撰写（未登记）的翻译永远不会让这道关卡失败。

## 限制

- 元数据标题的翻译只支持 `dir` 解析器——`dot` 解析器没有按语言生成 `meta.ts` 的机制。默认导出函数的 `meta.ts` 会被跳过并给出警告；该语言的那份请手写。
- 远程源和由 CMS 支撑的源会被跳过：没有本地文件可以把译文写进去。
- 头部标签页的文字位于 `blume.config.ts` 而非内容里——用[按语言的标签映射](/docs/content/navigation/)在那里做本地化。
- 译文质量取决于 agent。要像审阅其它任何贡献那样审阅它的输出——台账只保证新鲜度，不保证地道。

## 选项

- `--codex` / `--claude` — 用哪个 agent CLI 来翻译。必须恰好指定一个；`--check` 例外，它不运行 agent，两者都不需要。
- `--check` — 报告偏差并以非零码退出，不写入任何内容。
- `--concurrency <n>` — 并行的 agent 会话数。默认为 `4`，最大 `16`。
- `--locale <codes>` — 目标语言，逗号分隔（默认为每一个非默认语言）。
- `--force` — 重新翻译所有内容，包括已经最新和手写的文件。
- `--timeout <seconds>` — 每个文件的 agent 时间上限。默认为 `600`；设这个上限是为了抓住卡死的 agent，好让大页面有足够的时间跑完。最大为 `2147483`（约 24 天），这已是定时器所能等待的最长时间。
- `--json` — 在两种模式下都把报告以 JSON 输出到 stdout。

---

# validate
Source: https://blume.ndjp.net/docs/cli/validate/
English: https://useblume.dev/docs/cli/validate

`blume validate` 像构建那样读取你的内容，并检查它发现的每一处链接。它不生成也不构建任何东西，因此是摆在 `blume build` 之前的那道快速关卡：

```bash
blume validate
```

- **站内页面链接**（`/guides/intro`、`./sibling`）必须能解析到一个真实页面——失效的会被报为错误。组件里的字符串 `href`（`<Card href="./install">`）以同样的方式检查；`href={…}` 这类表达式则不会。
- **锚点链接**（`#section`、`/guides/intro#setup`）必须匹配目标页面上的某个锚点——标题的 id（自动生成或[手动固定](/docs/content/syntax/)），或者原始 HTML 元素的 `id` 属性——对不上的会报为警告。代码块内、行内代码里、HTML 注释里以及 `<Prompt>` 块中的 id 不算数。
- **资源链接**按文件实际所在的位置来检查：绝对路径（`/logo.png`）对照 `public/` 目录，相对的图片嵌入（`![](./diagram.png)`）对照页面自己的目录。对相对路径的普通链接仍会作为站点路由来解析——只有图片嵌入才会走图片处理流程。
- **外链**只有加上 [`--external`](#flags) 才会检查（默认关闭，因为它需要联网）；失效的链接（404/410/无法访问）是错误，而被限流或临时性的响应（403/429/5xx/超时）则是警告。

## 什么算作一个页面

链接是针对构建后站点所能提供的一切来解析的，而不只是 Markdown 页面：自定义的 [`.astro` 页面](/docs/advanced/custom-pages/)、生成的[更新日志](/docs/advanced/changelog/)索引、每一个配置过的[重定向](/docs/deployment/)，以及在[多语言站点](/docs/content/i18n/)上未翻译页面在各语言下的回退 URL。解析失败的页面会与链接问题一并报告，因为一个永远加载不出来的页面是链接校验的盲区，而不是一个干净的结果。

## 选项 [#flags]

- `--external` — 同时通过网络检查外部 `http(s)` 链接。
- `--strict` — 警告同样以非零码退出。info 级别的说明仍然只是提示。
- `--json` — 把诊断以 JSON 输出到 stdout，替代终端报告。

## 诊断

| 代码 | 级别 | 含义 |
| --- | --- | --- |
| `BLUME_BROKEN_LINK` | error | 某个站内链接指向了没有任何页面提供的路由。 |
| `BLUME_BROKEN_ANCHOR` | warning | 页面存在，但没有与该片段匹配的锚点。 |
| `BLUME_BROKEN_ASSET` | warning | 某个绝对路径不在 `public/` 中，或某个相对图片嵌入不在页面旁边。 |
| `BLUME_ASSETS_UNCHECKED` | info | 不存在 `public/` 目录，因此没有检查绝对资源路径。 |
| `BLUME_DEAD_LINK` | error 或 warning | 某个外链（使用 `--external` 时）返回了 404/410 或无法访问（error），或者出现临时性的 403/429/5xx/超时（warning）。 |

退出码就是约定：error 级别会返回非零，而 `--strict` 让 warning 级别同样如此。

## JSON 输出 [#json-output]

加上 `--json` 后，`blume validate`（以及 [`blume doctor`](/docs/cli/doctor/)）会向 stdout 写出一个对象：一个 `diagnostics` 列表，每一项都带着自己的 `code`、`severity`、`message`、相对于项目根目录的 `file`（当这条发现带有位置时还包括 `line` 和 `column`）、一个 `suggestion`，以及一个指向解释该代码的页面的 `docsUrl`，此外还有一个按级别计数汇总的 `summary`。退出码不变，因此同一条命令既能为 CI 把关，也能给编辑器集成提供数据。

---

# version
Source: https://blume.ndjp.net/docs/cli/version/
English: https://useblume.dev/docs/cli/version

`blume version` 是你切出[文档版本](/docs/content/versioning/)的方式。给它一个 id，它就会把当前的内容目录树冻结成一份快照，并按文档当时的样子继续对外提供：

```bash
blume version v1.0
```

它会做四件事：

1. **把内容目录树复制**进一个以该 id 命名的目录（`docs/v1.0/`），已有的快照不参与复制。
2. **重写副本内部以根路径开头的链接**，让它们留在快照之内：`/guides/x` 变成 `/v1.0/guides/x`。这涵盖行内链接与图片、引用式定义（`[x]: /guides/x`），以及任意引号写法的 HTML `href` 和 `src` 属性；写明了你的 [`basePath`](/docs/deployment/) 的链接则保留它（`/docs/guides/x` 变成 `/docs/v1.0/guides/x`）。围栏代码和行内代码原样不动，而指向快照里没有副本的页面的链接——生成的 API 参考、像更新日志这样的远程源——仍然指向线上页面。
3. **在 `blume.config.ts` 的 `versions.archived` 中注册这个 id**。首次切出版本会顺带开启版本管理，补上一个 `versions` 块，把该 id 归档，并把线上文档标注为 "Latest"。如果配置的写法它不会去改动，它会给出警告并打印出可供粘贴的条目。
4. **报告它做了什么**：复制了哪些文件、重写了哪些页面的链接，并提醒你归档版本是冻结的，而且 `blume dev` 需要重启才能识别这份快照。

像对待其他内容一样审阅并提交这个新目录。版本如何呈现的每一个细节——切换器、归档页面上的提示、每个版本的标签与徽章——都属于配置，参见[版本管理](/docs/content/versioning/)页。

## 列出版本

不带 id 运行它即可列出已配置的版本：先是当前版本及其标签和徽章，然后是每个归档 id 及其目录。在首次切出版本之前，也就是还没有配置 `versions` 时，它会改为告诉你如何切出一个版本。

```bash
blume version
```

## 选项

- `--force` — 覆盖已经存在的快照目录。不加它时，已存在的目录直接报错，因此一次误触发的重跑不会毁掉某个归档版本。

## 何时拒绝执行

在下列情况下，该命令会以非零码退出且不改动任何东西：

- id 没有以字母开头，或含有字母、数字、点、连字符与下划线之外的字符（要 `v1.0` 而不是 `1.0`，这样一个 id 就永远不会与[数字排序前缀](/docs/content/navigation/)冲突）；
- 项目存在 error 级诊断，因为给一棵坏掉的目录树拍快照等于把这份损坏一起冻结——请先修好它们（`blume doctor` 会列出这些问题）；
- 该 id 已经注册在 `versions.archived` 中；
- 快照目录已存在，而又没有传入 `--force`。

---

# 配置
Source: https://blume.ndjp.net/docs/configuration/
English: https://useblume.dev/docs/configuration

Blume 会从项目根目录读取 `blume.config.ts`。用 `defineConfig` 包裹你的配置即可获得自动补全和类型检查 —— 每个字段都是可选的，且都有合理的默认值。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});
```

## 一个完整示例

下面是一个更全面的示例，涵盖最常用的选项（其余部分参见各功能的指南）：

```ts blume.config.ts lineNumbers
import partytown from "@astrojs/partytown";
import { defineConfig } from "blume";
import { orama } from "blume/search";

export default defineConfig({
  // 站点
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro 集成 —— 由本站点安装并锁定版本
  integrations: [partytown()],

  // 内容
  content: {
    root: "docs",
  },

  // 主题 —— 参见主题指南
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // 搜索 —— 来自 "blume/search" 的适配器；参见搜索指南
  search: orama(),

  // Markdown 功能
  markdown: {
    imageZoom: true,
    externalLinks: false, // 在新标签页中打开 https:// 链接
    code: {
      icons: true, // 代码块头部显示语言图标
      wrap: false, // 折行显示长行而不是横向滚动
      theme: {
        light: "github-light", // 内置名称或自定义 Shiki 主题对象
        dark: "github-dark",
      },
    },
  },

  // Agents —— llms.txt、MCP、AI 目录；参见可发现性章节
  agents: {
    llmsTxt: true,
    // 位于 /.well-known/ai-catalog.json 的 AI Catalog / ARD 清单（需要 deployment.site）
    catalog: true,
    // 你站点的 agent skill，位于 /skill.md（需要 deployment.site）
    skillMd: true,
    // MCP server（需要服务端输出）
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO —— OG 图片、订阅源、站点地图、结构化数据；参见可发现性章节
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // 部署 —— 这里做静态构建；主机适配器参见部署指南
  deployment: {
    site: "https://docs.example.com",
  },
});
```

## 站点

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `title` | `"Documentation"` | 站点名称 —— 显示在页头、页面标题和 OG 卡片中。 |
| `description` | — | 默认 meta 描述，用于 SEO 和 OG。 |
| `logo` | — | 显示在页头的品牌标识和/或文字标。 |
| `banner` | — | 页头上方的全站公告栏。 |
| `footer` | — | 内容下方的一行链接和社交资料图标。 |

### Logo

把 `logo` 指向一个 SVG，Blume 会把它内联，因此使用 `currentColor` 的 logo 会自动跟随亮色与暗色主题：

```ts blume.config.ts
logo: "/logo.svg",
```

SVG 可以放在项目根目录或 `public/` 中。品牌由标识（`image`）加文字标（`text`）组成；对象形式让你能分别设置它们：

```ts blume.config.ts lineNumbers
logo: {
  image: "/logo.svg", // 字符串，或用于主题化位图素材的 { light, dark, alt }
  text: "Acme",       // 标识旁的文字标
  href: "/",          // 覆盖品牌链接（默认为 "/"）
},
```

`image` 接受与简写形式相同的值 —— 单个路径，或用于分别指定亮色/暗色素材的 `{ light, dark, alt }`（位图必须放在 `public/` 中）。

`href` 是一个像标签页路径那样的默认 locale 路径：在[多 locale 站点](/docs/content/i18n/)上，只要对应 locale 提供该路由，品牌链接就会切换到读者所在的 locale（在 `/en/…` 下 `/` 会变成 `/en`），因此点击 logo 不会让读者离开正在阅读的语言。只有默认 locale 提供路由的页面 —— [自定义页面](/docs/advanced/custom-pages/)或生成的更新日志索引 —— 会保留自身路径，而不是指向一个会 404 的本地化 URL。绝对 URL 则原样使用。

`text` 独立于标识控制文字标：

- **省略 `text`** 时，品牌使用你的站点 `title`（默认行为）。
- **设置 `text: ""`** 只显示标识 —— 当 logo 图片里已经含有文字标时很方便。此时屏幕阅读器会用图片的 `alt` 播报品牌链接，若没有 `alt` 则用你的站点 `title`。
- **设置 `text` 而不设 `image`** 得到纯文字 logo。

### Favicon

没有 favicon 选项 —— Blume 会像 Next.js 那样按文件名自动探测。在项目根目录或 `public/` 目录下放一个 `icon` 或 `favicon` 文件（`.svg`、`.png` 或 `.ico`），它就会成为浏览器标签页图标：

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← 自动识别
└─ docs/
```

同时存在多个时，SVG 优先于 PNG，PNG 优先于 ICO；`public/` 中的文件优先于根目录中的文件。如果 Blume 找不到图标，它会回退到自带的标识。

深色标识在深色浏览器界面中会消失，因此你可以为暗色模式额外提供一个文件。在图标文件旁添加一个 `-dark` 同名文件 —— 同名同目录，`-dark` 在扩展名之前（`icon.png` → `icon-dark.png`）—— Blume 会在一个 `prefers-color-scheme` media query 后面同时输出两个图标，并额外为那些在图标上忽略 media query 的浏览器和爬虫提供一个普通的亮色标签：

```
my-docs/
├─ blume.config.ts
├─ icon.png          ← 亮色模式
├─ icon-dark.png     ← 暗色模式
└─ docs/
```

只有与 Blume 选中的那个图标同名的兄弟文件才会被使用 —— 名字不同的 `-dark` 文件会被忽略，这样无关文件就不会意外与你的标识配对。暗色文件是可选的；只有一个图标时，Blume 会像以前一样输出单个标签。Blume 自带的兜底标识本身就提供两个变体。

### Apple touch icon

iOS 在有人把你的站点添加到主屏幕时使用的图标，探测方式完全相同。在项目根目录或 `public/` 目录下放一个 `apple-icon` 文件（`.png`、`.jpg` 或 `.jpeg`）—— 或者 `apple-touch-icon.png`，也就是大多数 favicon 生成器输出的文件名 —— Blume 会自动接好 `<link rel="apple-touch-icon">`。它没有默认图标；找不到文件时不会输出标签。

```
my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← 自动识别
└─ docs/
```

请把文件放在 `public/` 而不是项目根目录：iOS 会忽略 Blume 为根目录图标所用的内联 data URI，因此只有 `public/` 中的文件（在 `/apple-icon.png` 提供）才能可靠地到达主屏幕。与 favicon 不同，这里没有 `-dark` 兄弟文件 —— iOS 在主屏幕图标上会忽略 media query，因此深色变体永远不会被用到。

### Banner [#banner]

在页头上方显示一条全站公告栏。传一个字符串，或一个带链接和关闭按钮的对象：

```ts blume.config.ts
banner: "Docs are in beta — expect changes.",
```

```ts blume.config.ts lineNumbers
banner: {
  content: "Version 2.0 is here!",
  link: { text: "Read the release notes", href: "/changelog" },
  dismissible: true,
  id: "v2",
},
```

开启 `dismissible` 后，公告栏会显示一个关闭按钮，此后对该访客保持隐藏。关闭状态的键默认为正文文字，因此修改文案会让公告栏重新出现；设置一个稳定的 `id` 可以让它在多次修改后仍保持关闭。

在[多语言](/docs/content/i18n/)站点上，`content` 和链接的 `text` 还可以接受一个从 locale 代码到文字的映射。每个页面显示自己 locale 的条目，回退到默认 locale 的条目；只要对应 locale 提供该页面，链接就会切换到读者所在的 locale：

```ts blume.config.ts lineNumbers
banner: {
  content: { en: "Version 2.0 is here!", fr: "La version 2.0 est là !" },
  link: {
    text: { en: "Read the release notes", fr: "Lire les notes de version" },
    href: "/changelog",
  },
},
```

翻译过的公告栏以默认 locale 的文字作为关闭状态的键，因此一次关闭会在所有语言中同时生效。

### 页脚 [#footer]

每个页面都以页脚结束：一行内容，高度与页头相同，一侧放你的链接，另一侧放社交资料图标。页脚是 Blume 唯一链接你的社交资料和仓库的地方，因此只要 [`github`](#github) 有设置，仓库就会排在图标中的第一位。`footer` 负责补充其余部分：

```ts blume.config.ts lineNumbers
footer: {
  links: [
    { label: "Pricing", href: "https://acme.dev/pricing" },
    { label: "Changelog", href: "/changelog" },
    { label: "Blog", href: "https://acme.dev/blog" },
  ],
  socials: {
    x: "https://x.com/acme",
    discord: "https://discord.gg/acme",
  },
},
```

`links` 按你书写的顺序显示。站内链接按挂在根路径来写；外部链接在新标签页打开。在[多语言](/docs/content/i18n/)站点上，`label` 可以是从 locale 代码到文字的映射；只要对应 locale 提供该页面，站内链接就会切换到读者所在的 locale。`socials` 把平台映射到它的资料 URL，图标按你书写的顺序出现。可用平台为 `bluesky`、`discord`、`facebook`、`github`、`hacker-news`、`instagram`、`linkedin`、`medium`、`podcast`、`reddit`、`slack`、`telegram`、`threads`、`website`、`x` 和 `youtube`。一个 `github` 社交项会取代仓库链接；要隐藏该链接请用 [`navigation.repo`](/docs/content/navigation/)。

没有链接、资料或仓库的站点不会有页脚。基于 `PageLayout` 构建的自定义页面也会显示它，除非它们填充了布局自己的 `footer` 插槽。要完全替换页脚，请覆盖 [`Footer` 布局插槽](/docs/configuration/customization/)。

## 内容 [#content]

你的内容放在哪里，以及 Blume 如何发现它。文件如何变成路由，参见 [Pages](/docs/content/)。

```ts blume.config.ts lineNumbers
content: {
  root: "docs",
}
```

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `root` | `"docs"` | Blume 扫描内容的文件夹。单个 `filesystem()` 源的简写；不能与 `sources` 并用。 |
| `include` | `["**/*.{md,mdx}"]` | 匹配内容文件的 glob。简写形式，与 `root` 相同。 |
| `exclude` | `["**/_*", "**/.*"]` | 要忽略的 glob（下划线和点号文件）。简写形式，与 `root` 相同。 |
| `sources` | 一个 `filesystem()` | 来自 `blume/sources` 的内容源适配器，取代简写形式。参见[内容源](/docs/content/sources/)。 |
| `pages` | `"pages"` | 自定义 `.astro` 页面所在的文件夹。 |
| `defaultType` | `"doc"` | frontmatter 省略 `type` 时页面使用的 `type`。 |
| `types` | `{}` | 按类型的内容定义 —— 作用于某个 `type` 页面的自定义 frontmatter 键。参见 [Frontmatter](#frontmatter)。 |

静态资源放在 `public/` 中 —— `public/logo.png` 会在 `/logo.png` 提供，因此像 `![](/images/create.png)` 这样的引用会解析到 `public/images/create.png`。**相对路径**引用的图片（`![](./diagram.png)`）则与你的内容放在一起，并会在[构建时优化](/docs/content/syntax/)。

## 图片 [#images]

相对路径引用的本地图片会在构建时自动优化 —— 压缩、转换为 WebP，并补上内在的 `width`/`height` 属性，这样加载时布局不会位移。无需任何配置；撰写指南参见 [Links and images](/docs/content/syntax/)。

远程图片默认原样提供。若想让 Blume 也在构建时下载并优化它们，需要授权其主机：

```ts blume.config.ts lineNumbers
image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}
```

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `domains` | `[]` | 允许优化其远程图片的主机名。 |
| `remotePatterns` | `[]` | 基于模式的授权（`protocol`、`hostname`、`port`、`pathname`）；主机名接受 `*.`（一层）和 `**.`（任意层级）通配符。 |

## Frontmatter [#frontmatter]

页面 frontmatter 会被严格校验 —— 未知键会导致构建失败，因此拼写错误能很早被发现。若要承载项目特定的元数据（负责人、评审日期），请在 `frontmatter.extend` 下声明额外的键，每个键映射到你提供的 schema：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

任何 [Standard Schema](https://standardschema.dev) 库都可以 —— Zod（你的项目安装的任意版本）、Valibot、ArkType。扩展之外的键仍会被严格校验，因此查错拼写的能力不变。校验语义参见[自定义键](/docs/content/frontmatter/)。

`extend` 下的键在全站生效。若只想要求某种内容类型的页面带上某些键 —— RFC 的 `status`、runbook 的 `service` —— 请改为在 `content.types` 下按类型声明：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

一个键要么全站声明，要么按类型声明，不能两者兼有。作用域如何解析，参见[按类型的键](/docs/content/frontmatter/)。

`facets` 列出自定义键中那些其值会成为可筛选元数据的键：它们会随搜索文档（`blume-search.json` 和 MCP 索引）一起流转，而 [MCP 工具](/docs/discoverability/mcp/)接受一个 `filters` 输入与之匹配，因此 agent 可以只取回例如 `architecture` 领域中状态为 `enforced` 的 RFC。每个分面都必须是一个已声明的自定义键 —— 按类型或全站均可 —— 并且只有字符串（或字符串化的数字/布尔值）才能作为分面。

## GitHub [#github]

用 `github` 指向你的仓库。它驱动页脚的[仓库链接](/docs/content/navigation/)和 **Edit on GitHub** [页面操作](/docs/content/navigation/)：

```ts blume.config.ts lineNumbers
github: {
  owner: "acme",
  repo: "docs",
}
```

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `owner` | — | 拥有该仓库的 GitHub 账户或组织。 |
| `repo` | — | 仓库名称。 |
| `branch` | `"main"` | 编辑链接所指向的分支。 |
| `dir` | — | 从仓库根目录到项目根目录的路径（用于 monorepo）。 |
| `host` | `"https://github.com"` | GitHub 实例的源地址，用于 Enterprise 安装。必须是 HTTP(S)；会被规范化为其 origin。 |
| `api` | 由 `host` 推导 | REST API 基地址，用于针对 Enterprise 实例的 `<GithubInfo>`。必须是 HTTP(S)；会被规范化为 origin 加路径。 |

### GitHub Enterprise [#github-enterprise]

仓库位于 GitHub Enterprise 实例上的文档需要设置 `host`，此后每个由仓库推导出的链接 —— 页头标识、编辑链接、agent 清单 —— 都会指向该实例而不是公开站点：

```ts blume.config.ts lineNumbers
github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}
```

[`<GithubInfo>`](/docs/content/components/) 查询所用的 REST API 基地址由 `host` 推导：带数据驻留的 Enterprise Cloud 租户（`acme.ghe.com`）由其 `api.` 子域提供服务，其他任何主机则按 Enterprise Server 处理（`/api/v3`）。当你的实例在其他位置时，请显式设置 `api`。

:::warning
只能通过明文 HTTP 访问的实例仍会渲染其计数，但 `GITHUB_TOKEN` 不会随请求明文发送，而是被扣住不发 —— 因此私有仓库的卡片返回时就不带这些计数。
:::

:::note
`host` 涵盖 Blume 从 `github` 推导出的所有链接。若只想把页头标识指向别处 —— 比如文档仓库本身是私有的，想指向某个组织 —— 请用带绝对 URL 的 [`navigation.repo`](/docs/content/navigation/)。
:::

## 最后更新 [#last-modified]

在每个页面底部显示一行“最后更新于 …”。默认关闭；把 `lastModified` 设为 `"git"` 即可从 git 历史推导每个页面的日期：

```ts blume.config.ts
lastModified: "git",
```

| 值 | 说明 |
| --- | --- |
| `false` | 禁用（默认）。 |
| `"git"` | 从 git 历史（提交日期）读取日期。 |
| `"frontmatter"` | 完全不运行 git —— 只使用 `lastModified` frontmatter 字段。 |

git 来源会读取触碰每个文件的最近一次提交，因此它在任何 git 仓库中都能工作 —— 包括 monorepo —— 但需要构建时具备仓库历史。CI 平台通常检出的是浅克隆，这会悄悄丢掉大部分日期（发生时构建会给出 `BLUME_SHALLOW_GIT_HISTORY` 警告）：在 Vercel 上请设置环境变量 `VERCEL_DEEP_CLONE=true`；使用 `actions/checkout` 时设置 `fetch-depth: 0`。页面自身的 `lastModified` frontmatter 始终优先，这对固定某个日期或尚未提交的文件很方便：

```mdx page.mdx
---
title: My page
lastModified: 2026-06-20
---
```

启用后，该日期还会作为 schema.org 的 `dateModified` 输出到页面的结构化数据中。

## 日期格式 [#date-format]

“最后更新”时间戳和[更新日志](/docs/advanced/changelog/)时间线都通过同一个 `dateFormat` 渲染日期，因此两者读起来风格一致。日期总是按站点 locale 渲染；`dateFormat` 控制的是_形状_。它默认为长格式（`July 21, 2026`、`2026年7月21日`）：

```ts blume.config.ts
dateFormat: { dateStyle: "long" },
```

`dateFormat` 会透传给 [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) 选项。用一个 `dateStyle` 预设来指定长度：

```ts blume.config.ts
dateFormat: { dateStyle: "medium" },
```

或者用各个组件字段来做出 `2026/07/21` 这样的数字风格：

```ts blume.config.ts
dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
```

| 选项 | 说明 |
| --- | --- |
| `dateStyle` | 预设长度：`"full"`、`"long"`、`"medium"` 或 `"short"`。不能与组件字段同时使用。 |
| `weekday`、`era`、`year`、`month`、`day` | 单个组件，例如 `year: "numeric"`、`month: "2-digit"`。 |
| `timeZone` | IANA 时区。默认为 `UTC`，因此无论站点在哪里构建，日期读起来都一样。 |
| `calendar`、`numberingSystem` | 日历系统（例如 `"japanese"`）和数字系统（例如 `"arab"`）。 |

`timeZone`、`calendar` 和 `numberingSystem` 不改变形状：只设置了这几项的 `dateFormat` 仍然是长格式。

## SEO 与 agents

元数据、Open Graph 图片、RSS 订阅源、JSON-LD、站点地图和 `robots.txt` 位于 `seo` 之下；`llms.txt`、原始 Markdown、JSON API、MCP server 和探测清单位于 `agents` 之下。两者在[可发现性](/docs/discoverability/)章节中逐页讲解，该章节把搜索引擎和 AI agent 当作同一层机器可读内容的两个受众。面向读者的模型功能 —— assistant 和 Open in chat 操作 —— 位于 `ai` 之下。

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}
```

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `og.enabled` | 自动 | 每页的 Open Graph 图片 —— 设置了站点 URL 时开启。 |
| `rss.enabled` | `true` | 为 blog 和 changelog 内容构建订阅源（需要 deployment.site）。 |
| `rss.types` | `["blog", "changelog"]` | 各自生成订阅源的内容类型。 |
| `rss.limit` | `50` | 每个订阅源的最大条目数。 |
| `sitemap` | `true` | 生成 sitemap.xml（需要 deployment.site）。 |
| `robots` | `true` | 生成带 Sitemap 链接的 robots.txt。 |
| `structuredData` | `true` | 在每个页面的 head 中输出 schema.org JSON-LD。 |

这些功能配上绝对的 [`deployment.site`](/docs/deployment/)效果最好，这样才能得到完整 URL。

## 目录 [#table-of-contents]

本页大纲默认开启，列出 `H2`–`H3` 标题。用 `toc` 关闭它，或改变标题范围：

```ts blume.config.ts
export default defineConfig({
  toc: false, // 在所有页面隐藏
});
```

或者改为收窄标题范围：

```ts blume.config.ts
export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});
```

## 页面反馈 [#page-feedback]

每个文档页面都以“这个页面有帮助吗？”评分结束。它默认开启；把 `feedback` 设为 `false` 可在所有页面隐藏：

```ts blume.config.ts
export default defineConfig({
  feedback: false,
});
```

读者的回答会作为一个 `feedback` [自定义事件](/docs/configuration/analytics/)发送 —— 包含 `helpful`（`"yes"` 或 `"no"`）、`path` 和 `title` —— 走遍每一个配置了事件 API 的 analytics 适配器，同时也会作为 `window` 上的 `blume:track` 事件发出。没有 analytics 适配器时，回答不会被记录在任何地方；开启 [cookie consent](/docs/configuration/consent/)后，评分只对允许 analytics 的读者显示，因为对其他人来说回答本来也无处可去。问题和致谢文字都是 UI 字符串，可以用 [`i18n.ui`](/docs/content/i18n/) 翻译。

### 文字反馈 [#written-feedback]

想听到「是」或「否」以外的反馈，就开启评论。读者给页面评分后，会得到一个输入框来说明什么有效、还缺什么：

```ts blume.config.ts
export default defineConfig({
  feedback: { comments: true },
});
```

一条评论会作为 `feedback_comment` 事件发送，包含与评分相同的 `helpful`、`path` 和 `title`，外加读者的 `comment`（最多 1,000 个字符）。它走与评分相同的适配器，因此在你查看事件的地方就能读到评论。各提供方都会限制属性值的长度，因此长评论可能在到达时被截断：Google Analytics 保留 100 个字符，Mixpanel 保留 255 个，而 PostHog 和 Segment 会完整传递评论。Plausible 会把相同的值归为一组而不是逐条列出，因此它更适合评分而不是评论。读者可以在输入框里写任何内容，所以请把评论当作可能包含个人隐私信息来处理。

输入框的标签和按钮同样也是 UI 字符串（`feedback.comment` 和 `feedback.send`）。

## 功能选项

下面每一项都有自己的指南。配置字段就是入口：

| 字段 | 配置内容 | 指南 |
| --- | --- | --- |
| `theme` | 强调色、圆角、字体、亮色/暗色模式 | [主题](/docs/configuration/theming/) |
| `navigation` | 显式的侧边栏和页头标签页 | [导航](/docs/content/navigation/) |
| `search` | 提供方（Orama、Pagefind、Algolia 等）和索引 | [搜索](/docs/configuration/search/) |
| `markdown` | Markdown 渲染选项 —— 代码块、标题锚点、图片缩放 | [语法](/docs/content/syntax/) |
| `agents` | `llms.txt`、Markdown 镜像、JSON API、托管的 MCP server、skills，以及面向编码 agent 的探测清单 | [SEO 与 GEO](/docs/discoverability/) |
| `ai` | 页面内 assistant 和 Open in chat 操作 | [Assistant](/docs/configuration/assistant/) |
| `rateLimit` | 单个读者调用 assistant、playground 代理和服务端搜索的频率，使用来自 `blume/ratelimit` 的适配器（默认开启） | [速率限制](/docs/configuration/rate-limiting/) |
| `narration` | “收听本页”播放器，使用浏览器语音或构建时生成的语音 | [Narration](/docs/configuration/narration/) |
| `reference` | API 参考：`openapi()`、`asyncapi()`、`graphql()` 和 `scalar()` 适配器，来自 `blume/reference` | [OpenAPI](/docs/references/openapi/)、[AsyncAPI](/docs/references/asyncapi/)、[GraphQL](/docs/references/graphql/)、[Scalar](/docs/references/scalar/) |
| `api` | 手写端点页面的服务端、鉴权和 Try it 面板 | [手写 API 页面](/docs/references/api-pages/) |
| `analytics` | 来自 `blume/analytics` 的适配器 —— PostHog、Google Analytics、Plausible、Mixpanel、Segment 等 —— 以及自定义脚本 | [Analytics](/docs/configuration/analytics/) |
| `consent` | 来自 `blume/consent` 的 cookie 同意适配器 —— Blume 自带横幅、Osano 或 Ethyca —— 在读者允许之前拦住 analytics | [Cookie consent](/docs/configuration/consent/) |
| `seo` | 元数据、OG 图片、订阅源、结构化数据、站点地图、robots | [SEO 与 GEO](/docs/discoverability/) |
| `deployment` | 来自 `blume/deploy` 的主机适配器，或用于静态构建的 `{ site, base }` | [部署](/docs/deployment/) |
| `redirects` | 永久和临时重定向 | [部署](/docs/deployment/) |
| `integrations` | 追加在 Blume 内置集成之后的 Astro 集成 | [定制](/docs/configuration/customization/) |
| `basePath` | 每个生成的路由所挂载的路径前缀（例如 `/docs`），侧边栏看不到它 | [部署](/docs/deployment/) |
| `i18n` | Locale、默认 locale 和翻译后的 UI 字符串 | [国际化](/docs/content/i18n/) |
| `versions` | 较旧文档的冻结快照，带版本切换器 | [版本控制](/docs/content/versioning/) |
| `export` | 面向读者的 PDF 和 EPUB 下载 | [导出](/docs/configuration/export/) |
| `examples` | `<Component path>` 示例预览的位置，以及注入其 frame 的 CSS | [Component](/docs/content/components/) |
| `react` | 交互岛中的 React 行为 —— React Compiler 的自动 memo 化 | [Islands](/docs/content/islands/) |
| `variables` | 任何页面中 `{{name}}` 读取的值 | [变量](/docs/content/variables/) |
| `feedback` | 每页底部的“这个页面有帮助吗？”评分（默认 `true`），以及可选的文字评论 | [页面反馈](#page-feedback) |

## 优先级

设置从最低到最高优先级依次解析，因此你只需覆盖自己需要的部分：

1. **Blume 默认值**

    每个字段都有一个合理的默认值。

2. **blume.config.ts**

    你的项目级配置。

3. **文件夹 meta**

    控制某个分区的标题和排序的 [`meta.ts`](/docs/content/meta/)。

4. **页面 frontmatter**

    每页的覆盖优先级最高。

---

# 分析
Source: https://blume.ndjp.net/docs/configuration/analytics/
English: https://useblume.dev/docs/configuration/analytics

Blume 会通过 `blume.config.ts` 里的 `analytics` 列表为你注入分析脚本。每一项都是一个从 `blume/analytics` 导入的适配器：每个提供方一个，再加上供任何没有适配器的服务使用的 `script()`。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { googleAnalytics, plausible, posthog, vercel } from "blume/analytics";

export default defineConfig({
  analytics: [
    posthog({ key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }),
    vercel(),
    googleAnalytics({ id: "G-XXXXXXXXXX" }),
    plausible({ domain: "docs.example.com" }),
  ],
});
```

适配器按你列出的顺序注入 `<head>`，你想组合多少个都可以。每个适配器都是纯数据：它返回的内容会与其余配置一并校验，然后内联进构建好的站点，因此它可以携带任何 JSON 值，但绝不能是函数。某个透传选项若无法用 JSON 表达（函数、`undefined`、bigint），校验会带着它的路径报错，而不是让它悄悄从构建中消失。

分析脚本**只在生产构建中加载**。它们由 `blume build` 输出，`blume dev` 永远不会输出，因此本地流量不会进入你的仪表盘，你也不需要单独准备一个「development」项目。

:::note
分析是可选启用的。没有 `analytics` 列表（或列表为空）时，Blume 不会注入任何东西。
:::

若想先征求读者同意，请设置 [`consent`](/docs/configuration/consent/)：这里的每个适配器都会一直等待，直到读者允许分析。

下面出现的每一个标识符 —— 项目密钥、衡量 ID、站点 token —— 都是提供方安装代码片段里那个公开的、浏览器侧的标识。每个适配器都会渲染那段代码片段，因此可以安全地提交到你的文档仓库；Blume 从不要求你提供密钥。

## 适配器 [#adapters]

| 适配器 | 提供方 | 必填 |
| --- | --- | --- |
| `adobe()` | [Adobe Analytics](#adobe-analytics) | `url` |
| `amplitude()` | [Amplitude](#amplitude) | `key` |
| `clarity()` | [Microsoft Clarity](#microsoft-clarity) | `id` |
| `clearbit()` | [Clearbit](#clearbit) | `key` |
| `cloudflare()` | [Cloudflare Web Analytics](#cloudflare-web-analytics) | `token` |
| `databuddy()` | [Databuddy](#databuddy) | `clientId` |
| `fathom()` | [Fathom](#fathom) | `site` |
| `googleAnalytics()` | [Google Analytics 4](#google-analytics-4) | `id` |
| `googleTagManager()` | [Google Tag Manager](#google-tag-manager) | `id` |
| `heap()` | [Heap](#heap) | `id` |
| `hightouch()` | [Hightouch](#hightouch) | `key` |
| `hotjar()` | [Hotjar](#hotjar) | `id` |
| `logrocket()` | [LogRocket](#logrocket) | `id` |
| `mixpanel()` | [Mixpanel](#mixpanel) | `token` |
| `oneDollarStats()` | [OneDollarStats](#onedollarstats) | — |
| `pirsch()` | [Pirsch](#pirsch) | `code` |
| `plausible()` | [Plausible](#plausible) | `domain` |
| `posthog()` | [PostHog](#posthog) | `key` |
| `segment()` | [Segment](#segment) | `key` |
| `vercel()` | [Vercel Web Analytics](#vercel-web-analytics) | — |
| `script()` | [其它任何服务](#custom-scripts) | `src` 或 `content` |

Blume 文档使用客户端路由器，因此大多数导航都是页内替换，而不是整页加载。每个适配器都把这些计为页面浏览：脚本自身会跟随历史变化的提供方无需额外处理，而只统计真实加载的那几个（PostHog、Segment、Hightouch）由 Blume 自己发送页面浏览事件。两个例外是标签管理器 —— [Google Tag Manager](#google-tag-manager) 和 [Adobe](#adobe-analytics) 会加载一个容器，由容器自己的规则决定触发什么，因此要给它们配一个历史变化触发器。

## PostHog [#posthog]

把**项目 API 密钥**传给 `posthog()` 即可接入 [PostHog](https://posthog.com)。主机默认是 PostHog Cloud US；要使用 EU Cloud（`https://eu.i.posthog.com`）或自托管实例，请设置 `host`。

```ts blume.config.ts lineNumbers
analytics: [
  posthog({
    key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "https://us.i.posthog.com", // 可选，这就是默认值
  }),
],
```

`key` 和 `host` 是 Blume 映射的两个选项（`host` 会变成 `api_host`）。你传入的其它内容 —— `persistence`、`capture_pageview`、`autocapture`、`disable_session_recording` 以及 `posthog.init` 的所有其它选项 —— 都会原样传给 `posthog.init`。

只有当 PostHog 仅靠捕获页面加载来统计时（也就是你既没设 `capture_pageview` 也没设 `defaults` 时的行为），Blume 才会在每次客户端路由导航时发送 `$pageview`。若设了 `capture_pageview: "history_change"`，或设了 PostHog 当前代码片段里那种 `defaults` 日期（例如 `"2025-05-24"`），导航就由 PostHog 自己统计，Blume 不再额外发送任何东西。若设了 `capture_pageview: false`，则完全不会发送页面浏览。

## Vercel Web Analytics [#vercel-web-analytics]

加上 `vercel()` 即可接入 [Vercel Web Analytics](https://vercel.com/docs/analytics)。Blume 会渲染 Vercel 官方的 Astro 组件；在 Vercel 控制台为该项目启用 Web Analytics 之后，该组件会注入由你自己域名提供的第一方脚本。

```ts blume.config.ts lineNumbers
analytics: [vercel()],
```

不需要任何密钥 —— 脚本会把它上报到所属部署的那个项目。它只在 Vercel 部署上采集数据，因为那里存在 `/_vercel/insights` 端点。你传入的任何选项都会作为 prop 传给该组件（`mode`、`debug`、`endpoint`、`scriptSrc` 等）；`beforeSend` 是函数，没法通过配置传递，因此请改为在一个 `script()` 适配器里给 `window.webAnalyticsBeforeSend` 赋值。

## Cloudflare Web Analytics [#cloudflare-web-analytics]

[Cloudflare Web Analytics](https://developers.cloudflare.com/web-analytics/) 有两种接入方式，其中只有一种需要适配器。

**已开启代理的域名（自动接入）。** 如果你的站点由 Cloudflare 提供服务 —— 带自定义域名的 Worker、Pages，或任何开启了橙色云朵的域名 —— 在 Cloudflare 控制台里为该域名启用 Web Analytics 就可以了。Cloudflare 会在边缘注入 beacon，因此不要写 `cloudflare()`；再列一份会让每次页面浏览都被统计两次。

**其它任何托管（手动接入）。** 对于 Cloudflare 未做代理的站点，在控制台的 Web Analytics 下添加该站点，从它给出的 JS 代码片段中复制 token（即 `data-cf-beacon` 里的 `token`），然后传到这里。Blume 渲染的 beacon 标签与那段代码片段完全相同。

```ts blume.config.ts lineNumbers
analytics: [
  cloudflare({
    token: "0123456789abcdef0123456789abcdef",
  }),
],
```

整个选项对象会变成 beacon 的 `data-cf-beacon` JSON，因此任何其它 beacon 设置（`spa` 等）都会直接透传。

## Google Analytics 4 [#google-analytics-4]

把 GA4 网页数据流的**衡量 ID**（`G-…`，在属性「管理 → 数据流」下该数据流的详情中）传给 `googleAnalytics()`。Blume 渲染的 Google 标签与数据流的安装说明完全一致：异步的 `gtag.js` 加载器，加上 `dataLayer` 引导和 `config` 调用。

```ts blume.config.ts lineNumbers
analytics: [
  googleAnalytics({
    id: "G-XXXXXXXXXX",
    anonymize_ip: true, // 可选：任意其它 `config` 参数
  }),
],
```

`id` 是 Blume 唯一映射的选项。你传入的其它内容会原样搭在 `gtag('config', …)` 调用上（`send_page_view`、`cookie_domain`、`debug_mode` 等）。GA4 的增强型衡量默认就把历史变化计为页面浏览，因此客户端导航无需任何额外设置就会被追踪。Google Analytics 需要一两天才会显示新数据；[Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna) 扩展可以实时看到这些请求。

## Google Tag Manager [#google-tag-manager]

把**容器 ID**（`GTM-…`，显示在工作区头部）传给 `googleTagManager()`。Blume 渲染容器代码片段中属于 `<head>` 的那一半；`<noscript>` 里的 iframe 是给没有 JavaScript 的浏览器用的，而那些浏览器本来也不会运行分析脚本。

```ts blume.config.ts lineNumbers
analytics: [
  googleTagManager({
    id: "GTM-XXXXXXX",
    dataLayer: "dataLayer", // 可选，这就是默认值
  }),
],
```

哪些标签触发、在什么条件下触发，都由容器的配置决定。客户端导航会以历史变化的形式抵达容器，所以要用 **History Change** 触发器来触发页面浏览标签，而不是页面加载触发器。Cookie 同意横幅同样要你在容器里自行配置。

## Plausible [#plausible]

把你在 [Plausible](https://plausible.io) 中添加的**域名**传给 `plausible()`。对于自托管或经过代理的实例，把 `host` 设为它的源；默认是 Plausible Cloud。

```ts blume.config.ts lineNumbers
analytics: [
  plausible({
    domain: "docs.example.com",
    host: "https://plausible.example.com", // 可选，默认为 https://plausible.io
  }),
],
```

`domain` 会变成 `data-domain`，`host` 决定 `/js/script.js` 从哪里加载。其它任何选项都会变成标签上对应的 `data-` 属性（`api: "/api/event"` → `data-api`）。把额外行为编进文件名的脚本变体（`script.outbound-links.js` 等）是另一个标签；要加载它们请用 [`script()`](#custom-scripts)。

## Fathom [#fathom]

把**站点 ID**（取自 [Fathom](https://usefathom.com) 中该站点的脚本设置）传给 `fathom()`。

```ts blume.config.ts lineNumbers
analytics: [
  fathom({
    site: "ABCDEFGH",
    "honor-dnt": "true", // 可选：任意其它 `data-` 设置
  }),
],
```

`site` 会变成 `data-site`。其它任何选项都会变成标签上对应的 `data-` 属性（`honor-dnt`、`excluded-domains`、`canonical` 等），且都是字符串。`spa` 默认为 `"auto"`，这样 Fathom 会统计客户端路由器的导航；传入你自己的 `spa` 值即可覆盖它。

## Pirsch [#pirsch]

把**识别代码**（[Pirsch](https://pirsch.io) 中的 Settings → Developer → Identification Code）传给 `pirsch()`。

```ts blume.config.ts lineNumbers
analytics: [
  pirsch({
    code: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  }),
],
```

`code` 会变成 `data-code`，而 Blume 会给标签填上 Pirsch 脚本用来定位自身的 `pianjs` id。其它任何选项都会变成对应的 `data-` 属性（`dev`、`exclude`、`include`、`domain`、`endpoint` 等）。

## Databuddy [#databuddy]

把**客户端 ID**（取自 [Databuddy](https://databuddy.cc) 中该网站的设置）传给 `databuddy()`。

```ts blume.config.ts lineNumbers
analytics: [
  databuddy({
    clientId: "xxxxxxxxxxxxxxxxxxxxx",
    "track-web-vitals": "true", // 可选：任意其它 `data-` 设置
    "skip-patterns": '["/admin/*"]',
  }),
],
```

`clientId` 会变成 `data-client-id`。其它任何选项都会变成标签上对应的 `data-` 属性，所以要按属性的写法用 kebab-case 命名（`track-web-vitals`、`track-errors`、`track-outgoing-links`、`api-url` 等）。Databuddy 会忽略 `trackWebVitals` 这类 camelCase 名字。取值都是字符串：开关用 `"true"` 或 `"false"`，`skip-patterns` 和 `mask-patterns` 用一个 JSON 数组。其它列表形式的取值会被 Databuddy 当作空值。

## OneDollarStats [#onedollarstats]

先在 [OneDollarStats](https://onedollarstats.com) 中添加站点域名，然后列出 `oneDollarStats()`。它不需要密钥，因为 OneDollarStats 靠事件来源的域名来匹配站点。

```ts blume.config.ts lineNumbers
analytics: [oneDollarStats()],
```

每个选项都会变成标签上对应的 `data-` 属性，取值都是字符串：

- `hostname` 会让所有主机上的每一个事件都以该主机名上报（`docs.example.com`，不带 `https://`，也不带路径），而不只是 `localhost`，因此预览部署和预发布环境也会算作该站点的流量。除非每次构建都应以这个名字上报，否则不要设置它。
- 把 `devmode: "true"` 与 `hostname` 一起设置，本地的 `blume preview` 才能发送事件。在 `localhost` 上缺少其中任何一个时，跟踪器都不会发送任何东西，所以不要把它们写进提交的配置里。
- `url` 是事件被 POST 到的收集端点（默认为 `https://collector.onedollarstats.com/events`），而不是站点的 URL。
- `autocollect: "false"` 关闭自动页面浏览统计。
- `"hash-routing": "true"` 会在每次导航时都发送页面浏览，哪怕只有 `#fragment` 发生了变化，比如点击目录中的某个条目。取 `"false"` 时 Blume 不会写出该属性，因为只要它在，跟踪器就会打开 hash 路由。

## Mixpanel [#mixpanel]

把**项目 token**（[Mixpanel](https://mixpanel.com) 中的 project settings → Access Keys）传给 `mixpanel()`。如果项目使用 EU 或印度的数据驻留，请把 `region` 设为对应值，否则 Mixpanel 会丢弃这些事件。

```ts blume.config.ts lineNumbers
analytics: [
  mixpanel({
    token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    region: "eu", // 可选："us"（默认）、"eu" 或 "in"
  }),
],
```

`token` 和 `region` 是 Blume 映射的选项（`region` 会变成 `api_host`）。Blume 还会把 `track_pageview` 设为 `"url-with-path-and-query-string"`，因此这个库会自行追踪每次导航。你传入的其它内容 —— 包括 `track_pageview` 本身 —— 都会原样传给 `mixpanel.init`（`persistence`、`autocapture`、`record_sessions_percent` 等）。

## Amplitude [#amplitude]

把**项目 API 密钥**（[Amplitude](https://amplitude.com) 中的 project settings）传给 `amplitude()`。Blume 渲染的是 Browser SDK 的脚本加载片段：带密钥的 SDK 包加上 `init` 调用。

```ts blume.config.ts lineNumbers
analytics: [
  amplitude({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    serverZone: "EU", // 可选：任意其它 `init` 选项
  }),
],
```

`key` 是 Blume 唯一映射的选项。`init` 选项以控制台代码片段所带的设置为起点 —— `autocapture: true` 和 `fetchRemoteConfig: true` —— 你传入的其它内容会原样合并到它们之上。自动捕获涵盖页面浏览和历史变化，因此客户端导航也会被计入。

## Segment [#segment]

把 [Segment](https://segment.com) 中 JavaScript 数据源的**写入密钥**传给 `segment()`。如果你用[自定义域名](https://segment.com/docs/connections/sources/custom-domain/)提供 analytics.js 来绕开广告拦截器，请把 `cdn` 设为那个源。

```ts blume.config.ts lineNumbers
analytics: [
  segment({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    cdn: "https://cdn.example.com", // 可选，默认为 https://cdn.segment.com
  }),
],
```

`key` 和 `cdn` 是 Blume 映射的选项：代码片段从 `cdn` 加载这个库，并告诉它各个 integration 也从那里获取。你传入的其它内容会原样作为 `analytics.load` 的选项传下去（`integrations` 等）。

## Hightouch [#hightouch]

把 [Hightouch](https://hightouch.com) 中事件数据源的**写入密钥**传给 `hightouch()`。事件 API 主机默认是美国东部区域；如果你的工作区用的是别的区域，请设置 `host`（不带协议）。

```ts blume.config.ts lineNumbers
analytics: [
  hightouch({
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    host: "us-east-1.hightouch-events.com", // 可选，这就是默认值
  }),
],
```

`key` 和 `host` 是 Blume 映射的选项（`host` 会变成 `apiHost`）。你传入的其它内容会原样作为 `htevents.load` 的选项传下去。

## Heap [#heap]

把 **app ID**（[Heap](https://heap.io) 中该项目安装设置下的环境 ID）传给 `heap()`。

```ts blume.config.ts lineNumbers
analytics: [
  heap({
    id: "1234567890",
    disableTextCapture: true, // 可选：任意其它 `heap.load` 选项
  }),
],
```

`id` 是 Blume 唯一映射的选项。你传入的其它内容会原样成为 `heap.load` 的配置对象。

## Hotjar [#hotjar]

把**站点 ID**（[Hotjar](https://hotjar.com) 中该站点跟踪代码里的数字）传给 `hotjar()`。

```ts blume.config.ts lineNumbers
analytics: [
  hotjar({
    id: 1234567,
    version: 6, // 可选，这就是默认值
  }),
],
```

在 Hotjar 的跟踪代码中，`id` 对应 `hjid`，`version` 对应 `hjsv`；该适配器不接受其它选项。

## Microsoft Clarity [#microsoft-clarity]

把**项目 ID**（取自 [Clarity](https://clarity.microsoft.com) 中该项目的跟踪代码）传给 `clarity()`。

```ts blume.config.ts lineNumbers
analytics: [
  clarity({
    id: "xxxxxxxxxx",
  }),
],
```

该适配器不接受其它选项；Clarity 的设置都在它自己的控制台里。

## LogRocket [#logrocket]

把 **app ID**（`org/app` 形式，取自 [LogRocket](https://logrocket.com) 中的项目设置）传给 `logrocket()`。Blume 渲染的是安装代码片段：SDK 加上带保护的 `LogRocket.init` 调用。

```ts blume.config.ts lineNumbers
analytics: [
  logrocket({
    id: "your-org/your-app",
    release: "1.2.0", // 可选：任意其它 `init` 选项
  }),
],
```

`id` 是 Blume 唯一映射的选项。你传入的其它内容会原样传给 `LogRocket.init`（`release`、`console`、`network`、`dom` 等）。请求或响应的 sanitizer 是函数，没法通过配置传递；需要这类函数时，请去掉适配器，改在一个 [`script()`](#custom-scripts)适配器里自己调用 `LogRocket.init`。

## Clearbit [#clearbit]

把**可公开的 API 密钥**（`pk_…`）传给 `clearbit()`。Blume 渲染的是 Clearbit 标签，它会加载你在 Clearbit 中管理的各种标签 —— Reveal、表单等等。

```ts blume.config.ts lineNumbers
analytics: [
  clearbit({
    key: "pk_xxxxxxxxxxxxxxxx",
  }),
],
```

该适配器不接受其它选项。

## Adobe Analytics [#adobe-analytics]

把你的 Launch（Adobe Experience Platform Tags）环境的**嵌入脚本 URL** 传给 `adobe()`。它位于 Data Collection 下 Environments 中该环境的安装说明里；生产环境的那个长得像 `https://assets.adobedtm.com/…/launch-….min.js`。

```ts blume.config.ts lineNumbers
analytics: [
  adobe({
    url: "https://assets.adobedtm.com/xxxxxxxx/launch-xxxxxxxx.min.js",
  }),
],
```

Blume 会异步加载该脚本；它追踪什么由属性的规则决定。客户端导航不会重新加载页面，因此要给属性配一条针对历史变化的规则（或者在一个 [`script()`](#custom-scripts)适配器里调用 `_satellite.track`）。

## 自定义脚本 [#custom-scripts]

用 `script()` 加载任何没有适配器的提供方，或以它的适配器无法渲染的形态加载某个提供方的标签。每一项都会渲染一个 `<script>` 标签，并且必须在 `src`（外部）与 `content`（内联）中**恰好设置一个**。

```ts blume.config.ts lineNumbers
analytics: [
  // Umami
  script({
    src: "https://cloud.umami.is/script.js",
    strategy: "defer",
    attributes: { "data-website-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" },
  }),
  // 一段内联代码
  script({
    content: "console.log('analytics ready')",
  }),
],
```

`attributes` 是一组要展开到标签上的额外 HTML 属性（`data-*`、`id` 等），而 `strategy` 会为外部脚本加上 `async` 或 `defer`。

## 选项 [#options]

| 适配器 | 选项 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `adobe()` | `url` | — | Launch 环境的嵌入脚本 URL。必填。 |
| `amplitude()` | `key` | — | Amplitude 项目 API 密钥。必填。 |
| `amplitude()` | 其它任意选项 | `autocapture: true`、`fetchRemoteConfig: true` | 原样合并进 `amplitude.init` 的选项。 |
| `clarity()` | `id` | — | Clarity 项目 ID。必填。 |
| `clearbit()` | `key` | — | Clearbit 可公开的 API 密钥。必填。 |
| `cloudflare()` | `token` | — | Cloudflare Web Analytics 站点 token（手动接入）。必填。 |
| `cloudflare()` | 其它任意选项 | — | 原样写进 beacon 的 `data-cf-beacon` JSON。 |
| `databuddy()` | `clientId` | — | Databuddy 客户端 ID。必填。 |
| `databuddy()` | 其它任意选项 | — | 渲染为标签上的 `data-` 属性。 |
| `fathom()` | `site` | — | Fathom 站点 ID。必填。 |
| `fathom()` | `spa` | `"auto"` | Fathom 的历史变化追踪（`data-spa`）。 |
| `fathom()` | 其它任意选项 | — | 渲染为标签上的 `data-` 属性。 |
| `googleAnalytics()` | `id` | — | GA4 衡量 ID。必填。 |
| `googleAnalytics()` | 其它任意选项 | — | 原样搭在 `gtag('config', …)` 调用上。 |
| `googleTagManager()` | `id` | — | Tag Manager 容器 ID。必填。 |
| `googleTagManager()` | `dataLayer` | `dataLayer` | 容器所读取的数据层全局变量名。 |
| `heap()` | `id` | — | Heap app ID。必填。 |
| `heap()` | 其它任意选项 | — | 原样作为 `heap.load` 的配置传下去。 |
| `hightouch()` | `key` | — | Hightouch 事件数据源写入密钥。必填。 |
| `hightouch()` | `host` | `us-east-1.hightouch-events.com` | 事件 API 主机，不带协议。 |
| `hightouch()` | 其它任意选项 | — | 原样作为 `htevents.load` 的选项传下去。 |
| `hotjar()` | `id` | — | Hotjar 站点 ID（`hjid`）。必填。 |
| `hotjar()` | `version` | `6` | 跟踪代码版本（`hjsv`）。 |
| `logrocket()` | `id` | — | LogRocket app ID（`org/app`）。必填。 |
| `logrocket()` | 其它任意选项 | — | 原样传给 `LogRocket.init`。 |
| `mixpanel()` | `token` | — | Mixpanel 项目 token。必填。 |
| `mixpanel()` | `region` | `us` | 数据驻留区域：`us`、`eu` 或 `in`。 |
| `mixpanel()` | 其它任意选项 | `track_pageview: "url-with-path-and-query-string"` | 原样合并进 `mixpanel.init` 的选项。 |
| `oneDollarStats()` | `hostname` | — | 所有主机上每个事件都以此主机名上报。 |
| `oneDollarStats()` | 其它任意选项 | — | 渲染为标签上的 `data-` 属性（`"hash-routing": "false"` 不会写出）。 |
| `pirsch()` | `code` | — | Pirsch 识别代码。必填。 |
| `pirsch()` | 其它任意选项 | — | 渲染为标签上的 `data-` 属性。 |
| `plausible()` | `domain` | — | 在 Plausible 中登记的站点域名。必填。 |
| `plausible()` | `host` | `https://plausible.io` | 自托管或经过代理实例的源。 |
| `plausible()` | 其它任意选项 | — | 渲染为标签上的 `data-` 属性。 |
| `posthog()` | `key` | — | PostHog 项目 API 密钥。必填。 |
| `posthog()` | `host` | `https://us.i.posthog.com` | PostHog 数据接入主机（EU Cloud 或自托管）。 |
| `posthog()` | 其它任意选项 | — | 原样传给 `posthog.init`。 |
| `segment()` | `key` | — | Segment 数据源写入密钥。必填。 |
| `segment()` | `cdn` | `https://cdn.segment.com` | 代理 Segment CDN 的自定义域名的源。 |
| `segment()` | 其它任意选项 | — | 原样作为 `analytics.load` 的选项传下去。 |
| `vercel()` | `mode`、`debug` 等 | — | 作为 props 传给官方 Astro 组件。 |
| `script()` | `src` | — | 外部脚本 URL。与 `content` 互斥。 |
| `script()` | `content` | — | 内联脚本正文。与 `src` 互斥。 |
| `script()` | `strategy` | — | 外部脚本用 `async` 或 `defer`。 |
| `script()` | `attributes` | — | 展开到 `<script>` 标签上的额外 HTML 属性。 |

## 自定义事件 [#custom-events]

Blume 的页面反馈（`feedback`，以及开启[书面反馈](/docs/configuration/)时的 `feedback_comment`）、[搜索](/docs/configuration/search/)（`search`、`search_select`）和[朗读](/docs/configuration/narration/)播放器（`narration_play`、`narration_complete`），会通过每个已配置且带客户端 API 的适配器发送自定义事件 —— PostHog、Mixpanel、Heap、Segment、Hightouch、Amplitude、LogRocket、Adobe、Google Analytics、Google Tag Manager（作为 `window.dataLayer` 上的一次 `{ event }` push）、Plausible、Databuddy、Fathom、OneDollarStats（每个属性值都作为字符串）、Pirsch、Clarity、Hotjar 和 Vercel。Cloudflare 和 Clearbit 没有事件 API。每个事件还会作为 `blume:track` CustomEvent 在 `window` 上触发，其 `detail` 里带有 `{ event, props }`，因此一个 `script()` 适配器可以把它转发到别处。关于部署构建好的站点，见[部署](/docs/deployment/)。

---

# 助手
Source: https://blume.ndjp.net/docs/configuration/assistant/
English: https://useblume.dev/docs/configuration/assistant

加入一个能在页面内聊天面板中回答读者问题的助手，背后是一条流式服务端端点和 [AI SDK](https://ai-sdk.dev)。它需要手动启用，在打开之前静态文档就完全保持静态：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
  },
}
```

不做任何其它配置时，答案会通过 [Vercel AI Gateway](#adapters)以 `openai/gpt-5.5` 流式返回。想换一个模型或提供方，需要用[适配器](#adapters)。

## 建议问题 [#suggested-questions]

用几条起始提示语填充空状态。每一条都会渲染成一个可点击的建议 —— 点一下就发送 —— 标签旁还可以放一个可选的 [Lucide 图标](/docs/content/components/)：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    suggestions: [
      { label: "Blume 是什么？", icon: "rocket" },
      { label: "如何编写一个文档页面？", icon: "file-text" },
      { label: "如何配置主题？", icon: "settings" },
    ],
  },
}
```

`label` 是被提出的问题；`icon` 可选。不设置 `suggestions`（或设为空），面板就会以一个普通输入框打开。

## 询问代码 [#asking-about-code]

启用助手后，每个代码块在复制按钮旁都会多出一个 **提问**按钮。它会带着这段代码打开助手，代码以 chip 的形式显示在输入框上方，读者可以问它是做什么的、为什么会失败，或者该怎么改造。不带问题直接发送时，它会让助手解释这段代码。代码会作为围栏代码块跟在问题之后发给模型，最长 6,000 个字符。

基于 `useAssistant` 自建的聊天界面也能做到同样的事：监听 `window` 上的 `blume:open-assistant` 事件，其 `detail.code` 里放着这段代码块的 `language`、`source` 和 `title`。

## 联系支持 [#contact-support]

当文档答不上来时，把读者交给真人。设置 `support`，一旦有了对话，面板就会在下方显示一个 **联系支持**链接：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    support: "mailto:help@example.com", // 或 "https://example.com/support"，或 "/support"
  },
},
```

一个 `mailto:` 地址会打开一封以对话内容为正文的邮件，读者不必再解释一遍（很长的对话只保留最近的几轮）。一个 URL 或你站点上的某个页面会收到作为 `thread` 查询参数的对话 ID。助手的 `ask`、`ask_answer` 和 `ask_error` [分析事件](#analytics)带上同一个 `thread`，因此你的支持团队能在分析数据里找到这次对话。

## 自定义指令 [#custom-instructions]

用 `instructions` 加入你自己的系统提示词 —— 身份、语言、语气，或任何助手应当始终记住的其它设定：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    instructions:
      "你是 Acme 的文档助手 Bloomy。请用提问时使用的语言回答，并把回答控制在三段以内。",
  },
}
```

你的文字是**追加到**内置指令之后，而不是替换它们：内置部分承载着[接地](#grounding)约定 —— 只依据检索到的页面作答，并以 Markdown 链接引用它们 —— 聊天面板的引用功能依赖于此，所以无论你加什么，它都会保持完整。

## 接地 [#grounding]

助手是**以你的文档为依据**的。对每个问题，它会检索出最相关的页面 —— 使用与页面内搜索相同的词法 [Orama](/docs/configuration/search/) 索引 —— 并把它们注入模型的系统提示词，因此答案来自你的内容，而不是模型自身的知识。助手会被要求只依据检索到的页面作答、在文档没有覆盖时明说，并引用它所依据的页面。

读者当前所在的页面会先加入上下文，用来把检索范围限定到该页面的语言 —— 在[带版本](/docs/content/versioning/)的站点上，还限定到它的文档版本 —— 让答案与读者所处的文档位置保持相关。检索在请求时执行，数据来自烘焙进构建产物的一份快照，因此不论你用哪个[搜索](/docs/configuration/search/)提供方都能工作 —— 即使 `search: false` —— 也无需任何配置。

除 **[Inkeep](#inkeep)** 之外，所有适配器都开启接地 —— Inkeep 会对你在其控制台中建立索引的内容执行自己的检索。

## 搜索与阅读页面 [#searching-and-reading-pages]

检索到的页面只是个起点。助手还可以自己查找：它有一个 `search_docs` 工具用来搜索你的文档，还有一个 `read_page` 工具用来读取整个页面，当摘录不足以回答时就会用到。它可以在一个问题之内先搜索、读一两页、再搜索一次，然后才作答。工具调用在你的服务器上针对与接地相同的那份快照执行，遵循读者的语言与文档版本，并且不会传到读者那里；他们只看得到答案。

对于模型支持工具调用的适配器，这些工具默认开启。对于 [OpenAI 兼容端点](#openai-compatible-endpoints)它们默认关闭，因为自托管模型未必支持。设置 `tools` 可以改变其中任何一种默认值：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    provider: openai({ baseUrl, model, apiKeyEnv }),
    tools: true, // 这个模型支持工具调用
  },
}
```

每个问题最多经过五个模型步骤：至多四轮工具调用，然后才是答案。使用 `tools: false` 时，助手只依据检索到的页面作答，就像工具出现之前那样。

## 检索量 [#retrieval-size]

一个问题携带多少文档，是影响读者等待第一个字时长最大的因素：模型会读完每一个被注入的字符，然后才吐出第一个 token。在托管的前沿模型上这几乎察觉不到，但在自托管后端上它就是主要开销。`retrieval` 用来控制这个量：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    retrieval: {
      maxResults: 3, // 每个问题检索到的页面更少
      excerptChars: 1200, // 每页的摘录更短
      contextBudget: 3000, // 注入总量更小
    },
  },
}
```

| 选项 | 默认值 | 说明 |
| --------------- | ------- | ----------------------------------------------- |
| `maxResults`    | `6`     | 每个问题检索到的文档数。                       |
| `excerptChars`  | `2000`  | 从每个检索到的页面保留的字符数。               |
| `contextBudget` | `10000` | 所有摘录合计注入的字符数。                     |

这三者不能互相替代。`contextBudget` 给整个注入量封顶，`excerptChars` 决定在单个长页面里摘录能深入到多深 —— 当答案全在一个页面里、而摘录把它截断了，就把它调大 —— 而 `maxResults` 给检索加入的页面数量封顶。读者正在看的那个页面会叠加在检索到的页面之上被注入，因此一个答案最多能比 `maxResults` 多引用一页。

默认值适合托管模型。如果你在自己的硬件上提供服务，并且首 token 时间比召回率更重要，就调低它们；无论哪种情况答案都保持有据可依，而且助手会被要求在内容未被覆盖时明说，而不是自行填补。

## 外部端点 [#external-endpoint]

已经有 AI 后端 API 了？把面板指向它，同时让文档构建保持静态：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    endpoint: "https://api.example.com/v1/docs/ask",
  },
}
```

Blume 发送的 `POST` 请求体与它内置路由的完全一致：

```json
{
  "messages": [{ "role": "user", "content": "How do I deploy?" }],
  "page": { "path": "/deployment" }
}
```

返回一个成功的响应，其响应体是纯 UTF-8 文本流。如果该端点位于另一个源，就用 CORS 放行文档所在的源：接受 `OPTIONS` 和 `POST`，允许 `content-type` 请求头，并且在预检响应和流式响应上都返回 CORS 响应头。设置了 `endpoint` 后，Blume 会生成聊天界面，但不会生成服务端路由、接地快照、提供方依赖或提供方密钥警告；检索、认证、速率限制、模型访问和引用都由你的后端负责。与它同时设置的适配器会被忽略。

## 跨源调用方 [#cross-origin-callers]

生成的端点会在自己的源上响应页面内的助手。若还想从另一个站点调用它 —— 比如一个带提问框的营销页 —— 把那个站点的源列进 `cors`：

```ts blume.config.ts lineNumbers
ai: {
  assistant: {
    enabled: true,
    cors: ["https://www.example.com"],
  },
}
```

这样该路由会响应浏览器的 `OPTIONS` 预检，并在每个响应上标出列表中的那个源 —— 无论是流式答案还是错误状态，以便调用方能把被拒绝的响应体与提供方故障区分开。不在列表中的源拿不到任何响应头，仍然受浏览器的同源规则约束。每个条目都会被归约为它的源，所以 `https://www.example.com/docs/` 和 `https://www.example.com` 是一回事。若要允许任意页面调用该路由，就列出 `"*"` 而不是具体源。

调用方发送的 `POST` 请求体与[外部端点](#external-endpoint)约定中描述的完全一致，读回的也是同样的文本流。以 JSON 发送，并带上 `content-type: application/json` 头：

```ts
const response = await fetch("https://docs.example.com/api/ask", {
  body: JSON.stringify({
    messages: [{ role: "user", content: "How do I deploy?" }],
  }),
  headers: { "content-type": "application/json" },
  method: "POST",
});
```

内容类型很重要：Astro 的跨站请求检查会在路由运行之前，就以 403 拒绝没有内容类型的跨源 `POST`，或 `text/plain` 这类表单式内容类型；而那个响应不带 CORS 响应头，因此浏览器会把它报告为网络错误而不是某个状态码。预检会放行调用方所请求的任何请求头，所以一个会自行添加响应头的 fetch 封装无需额外配置。

`cors` 只影响生成的路由；使用外部 `endpoint` 时，CORS 是那个后端自己的事，两者同时设置属于配置错误。无论哪种情况，该端点都不做认证，因此[速率限制](#rate-limiting)的建议同样适用于跨源流量。

## 需要服务端输出 [#server-output-required]

Blume 内置的助手后端是一条服务端路由（`POST /api/ask`），因此它无法在静态构建上运行。指定一个来自 `blume/deploy` 的宿主适配器，即可切换到服务端输出：

```ts blume.config.ts lineNumbers
import { vercel } from "blume/deploy";

export default defineConfig({
  deployment: vercel(),
});
```

在启用助手又没有外部 `endpoint` 的情况下做静态构建，构建会立刻失败，并提示你去设置宿主适配器。适配器列表见[部署](/docs/deployment/)。

## 适配器 [#adapters]

`provider` 决定由哪个后端作答。它的值是一个**适配器**：一个从 `blume/ai` 导出的函数，接受该后端自己的选项，返回一份普通描述对象，Blume 把它写进生成的路由。每个适配器各自掌管自己的模型、读取密钥的环境变量、如何映射[推理](#reasoning)，以及需要哪个提供方 SDK —— 因此不存在一份需要在各后端之间对齐的公共字段集合：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { anthropic } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: anthropic({ model: "claude-sonnet-5" }),
    },
  },
});
```

| 适配器 | 作答所用 | 密钥环境变量 | 需安装的 SDK |
| --- | --- | --- | --- |
| [`openai()`](#openai) | 任意 [OpenAI](https://platform.openai.com) 模型，或任意 [OpenAI 兼容端点](#openai-compatible-endpoints) | `OPENAI_API_KEY` | `@ai-sdk/openai`（配合 `baseUrl` 时用 `@ai-sdk/openai-compatible`） |
| [`anthropic()`](#anthropic) | 任意 [Claude](https://platform.claude.com) 模型 | `ANTHROPIC_API_KEY` | `@ai-sdk/anthropic` |
| [`gemini()`](#gemini) | 任意 [Gemini](https://ai.google.dev) 模型 | `GEMINI_API_KEY` | `@ai-sdk/google` |
| [`grok()`](#grok) | 任意 [xAI](https://x.ai/api) Grok 模型 | `XAI_API_KEY` | `@ai-sdk/xai` |
| [`gateway()`](#vercel-ai-gateway)（默认） | 通过 Vercel AI Gateway 使用一个 `provider/model` 字符串 | `AI_GATEWAY_API_KEY` | 无需安装 —— Blume 自带 |
| [`openrouter()`](#openrouter) | 任意 [OpenRouter](https://openrouter.ai) 模型 | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
| [`llmgateway()`](#llmgateway) | 任意 [LLMGateway](https://llmgateway.io) 模型 | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
| [`inkeep()`](#inkeep) | 任意 [Inkeep](https://inkeep.com) QA 模型 | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |

`openai()`、`anthropic()`、`gemini()` 和 `grok()` 直接用你的密钥调用提供方自己的 API —— 中间没有任何东西。这些 SDK 是可选的 peer 依赖，因此把适配器需要的那一个加入你的项目即可（比如 `npm install @ai-sdk/anthropic`）。如果缺少它，`blume build` 会在 Vite 运行之前停下，指出缺哪个包以及安装它的命令，[`blume doctor`](/docs/cli/doctor/) 也会报告这一项。

适配器返回的描述对象是纯数据 —— 它的种类、选项、读取的环境变量以及所需的 SDK —— 因此生成的路由（以及[抽离](/docs/configuration/customization/)出来的那条路由）会把它作为字面量内联进去，并按名字导入提供方的 SDK。请求时没有任何东西去读 `blume.config.ts`，路由里也永远不会写入密钥：适配器只接收保存密钥的环境变量的**名字**，由路由通过 Astro 的 [`getSecret()`](https://docs.astro.build/en/guides/environment-variables/#retrieving-secrets-programmatically) 读取它的值，因此每个部署适配器都以自己的方式提供它 —— Node、Vercel 和 Netlify 上用环境变量，Cloudflare 上用 Worker 的 [bindings](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets)。

### OpenAI [#openai]

任意 [OpenAI](https://platform.openai.com) 模型，通过 OpenAI 自家的 AI SDK 提供方直接调用：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { openai } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: openai({ model: "gpt-5.5" }),
    },
  },
});
```

#### OpenAI 兼容端点 [#openai-compatible-endpoints]

任何讲 OpenAI API 的端点 —— 自托管模型、内部网关 —— 同样可以通过 `openai()` 使用：加上它的 `baseUrl`，通常再加上 `apiKeyEnv` 指定保存其密钥的环境变量（默认是 `OPENAI_API_KEY`）。`name` 是 AI SDK 报告的提供方名字，也是该端点读取 [`providerOptions`](#options-every-adapter-takes) 时使用的键；默认是 `openai-compatible`：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { openai } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: openai({
        baseUrl: "https://my-gateway.example.com/v1",
        apiKeyEnv: "MY_GATEWAY_API_KEY",
        model: "gpt-4o",
        name: "my-gateway",
      }),
    },
  },
});
```

带 `baseUrl` 时，路由会通过 `@ai-sdk/openai-compatible` 调用该端点的 Chat Completions API，所以请安装这个包而不是 `@ai-sdk/openai`：大多数兼容端点并不提供 OpenAI 的 Responses API。[文档工具](#searching-and-reading-pages)默认关闭，因为自托管模型未必支持工具调用。

:::note
早期 Blume 版本里的 `openaiCompatible()` 仍然可用：它就是带 `baseUrl` 的 `openai()`，是同一个适配器。
:::

### Anthropic [#anthropic]

任意 [Claude](https://platform.claude.com) 模型，通过 Anthropic 自家的 AI SDK 提供方直接调用：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { anthropic } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: anthropic({ model: "claude-sonnet-5" }),
    },
  },
});
```

### Gemini [#gemini]

任意 [Gemini](https://ai.google.dev) 模型，通过 Google 自家的 AI SDK 提供方直接调用。密钥是来自 Google AI Studio 的 API key：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { gemini } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: gemini({ model: "gemini-3.5-flash" }),
    },
  },
});
```

### Grok [#grok]

任意 [xAI](https://x.ai/api) Grok 模型，通过 xAI 自家的 AI SDK 提供方直接调用：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { grok } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: grok({ model: "grok-4.7" }),
    },
  },
});
```

### Vercel AI Gateway [#vercel-ai-gateway]

默认选项。`model` 是一个 `provider/model` 字符串，所以换模型只需改这个值（`openai/gpt-5.5`、`anthropic/claude-sonnet-4-5` 等），无需安装任何提供方 SDK。gateway 从你的环境变量中读取 `AI_GATEWAY_API_KEY`，在部署到 Vercel 时会自动接好，在那里它还可以用该部署的 OIDC token 完成认证：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { gateway } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: gateway({ model: "anthropic/claude-sonnet-4-5" }),
    },
  },
});
```

不设置 `provider` 等同于 `gateway({ model: "openai/gpt-5.5" })`。

### OpenRouter [#openrouter]

[OpenRouter](https://openrouter.ai) 上的任意模型，通过它专用的 AI SDK 提供方调用：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { openrouter } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: openrouter({
        model: "anthropic/claude-sonnet-4-5",
        reasoning: "none",
      }),
    },
  },
});
```

### LLMGateway [#llmgateway]

[LLMGateway](https://llmgateway.io) 上的任意模型，通过它 OpenAI 兼容的端点调用：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { llmgateway } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: llmgateway({ model: "openai/gpt-5.5" }),
    },
  },
});
```

当你自己运行 LLMGateway 时，`baseUrl` 会覆盖预设端点（`https://api.llmgateway.io/v1`）。

### Inkeep [#inkeep]

[Inkeep](https://inkeep.com) 会依据你在 Inkeep 控制台中建立索引的内容作答 —— 它执行自己的检索 —— 因此 Blume 让它保持**无接地**：不会注入本站页面的快照，[检索量](#retrieval-size)相关的选项也不适用。它同样没有推理控制，所以该适配器不接受 `reasoning`：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { inkeep } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: inkeep({ model: "inkeep-qa-expert" }),
    },
  },
});
```

`baseUrl` 会覆盖预设端点（`https://api.inkeep.com/v1`）。

### 每个适配器都接受的选项 [#options-every-adapter-takes]

**`apiKeyEnv`** 让适配器改用与默认不同的环境变量 —— `gateway({ apiKeyEnv: "DOCS_GATEWAY_KEY" })` 会读取那个变量而不是 `AI_GATEWAY_API_KEY`，`blume dev`/`build` 中缺少密钥的警告也会检查它。在密钥设置好之前，已部署的路由会以 `503` 应答，并给出指明该变量名的消息。路由最多只读取 64 KB 的请求体，更大的请求一律以 `413` 应答。

**`headers`** 让每次调用都带上静态请求头 —— 比如给共享后端加一个标识调用方的头，让它自己的可观测性或速率限制能把你的文档流量与其他流量区分开：

```ts blume.config.ts lineNumbers
provider: openai({
  baseUrl: "https://llm.internal.example.com/v1",
  apiKeyEnv: "INTERNAL_LLM_API_KEY",
  model: "gpt-4o",
  headers: { "X-Caller-Id": "docs" },
}),
```

这些值会原样写入生成的路由，因此请把密钥放在 `apiKeyEnv` 里，而不是放在 `headers` 里。API key 的 `Authorization` 头会先被应用，自定义头无法把它挤掉。

**`providerOptions`** 会把其余任何内容按 SDK 自己的结构直接传给 AI SDK 的 [`providerOptions`](https://ai-sdk.dev/docs/foundations/prompts#provider-options) —— 先按提供方、再按选项分层 —— 因此新增的模型控制项永远不需要 Blume 为它单开一个字段：

```ts blume.config.ts lineNumbers
provider: gateway({
  model: "openai/gpt-5.5",
  providerOptions: { openai: { textVerbosity: "low" } },
}),
```

Blume 只映射自己具名列出的选项（`model`、`reasoning`、`apiKeyEnv`、`headers`），而 `providerOptions` 原样透传，因此它必须是 JSON —— 它会被内联进路由 —— 并且必须使用底层提供方所期待的键（`openai()` 或 gateway 后面的 OpenAI 模型用 `openai`，`anthropic()` 用 `anthropic`，`gemini()` 用 `google`，`grok()` 用 `xai`，OpenRouter 上用 `openrouter`，OpenAI 兼容端点上则用该适配器的 `name`）。启用助手还会为页面内的交互岛开启 React —— 见[定制](/docs/configuration/customization/)。

## 推理 [#reasoning]

推理模型会先思考再作答，而它们默认思考多少因模型而异。对有接地的文档问答来说，检索到的摘录已经带着答案，因此那大部分思考只是读者在等待的延迟。适配器的 `reasoning` 选项设定模型思考多少：`"none"`、`"minimal"`、`"low"`、`"medium"`、`"high"` 或 `"xhigh"`：

```ts blume.config.ts lineNumbers
provider: gateway({ model: "openai/gpt-5.5", reasoning: "none" }),
```

每个适配器都把这个级别作为自己后端的推理控制发送出去，这也是它挂在适配器上而不是挂在 `assistant` 上的原因：

| 适配器 | 该级别最终变成 |
| --- | --- |
| `openai()` | OpenAI 的 `reasoning_effort`。带 `baseUrl` 时，它会作为请求中的 `reasoning_effort` 发送，因此该端点必须接受这个参数。 |
| `anthropic()` | Claude 的思考：在支持自适应思考的模型上是努力程度，在较旧的模型上是思考预算，而 `"none"` 则完全关闭思考。 |
| `gemini()` | Gemini 的思考级别，或在支持该设置的模型上是思考预算。 |
| `grok()` | xAI 的推理努力程度，仅在提供该设置的模型上可用。 |
| `gateway()` | AI SDK 的 [`reasoning`](https://ai-sdk.dev/docs/ai-sdk-core/reasoning) 调用选项，gateway 会把它映射到模型自己的设置 —— 例如 OpenAI 的 `reasoning_effort`。 |
| `openrouter()` | OpenRouter 的 `reasoning.effort`，设置在模型上。它的提供方会忽略 AI SDK 的调用选项，所以这个级别要放在 OpenRouter 读取它的位置。 |
| `llmgateway()` | 通过 AI SDK 的调用选项，作为请求中的 `reasoning_effort` 发送。 |
| `inkeep()` | 不支持。Inkeep 运行自己的 QA 流程，没有推理控制，所以该适配器没有 `reasoning` 选项，设置它属于配置错误。 |

模型必须支持你选的那个级别：OpenAI 会拒绝模型没有提供的级别（`"none"` 和 `"xhigh"` 只存在于部分模型上），所以设置前请先查模型的文档。不设置则保持模型默认值。和[检索量](#retrieval-size)一样，它是在详尽程度与首 token 时间之间做取舍，无论如何答案都保持有据可依。

## 分析 [#analytics]

配置了[分析提供方](/docs/configuration/analytics/)之后，助手会通过页面反馈小组件所用的同一个 `track()` 上报使用情况，因此提问会与你的页面浏览量并排出现：

| 事件 | 何时触发 | 属性 |
| --- | --- | --- |
| `ask` | 发出一个提问时 | `path`、`questionChars`、`thread` |
| `ask_answer` | 答案流式输出结束时 | `path`、`questionChars`、`thread`、`ms`、`chars` |
| `ask_error` | 请求失败、中断或返回空时 | `path`、`questionChars`、`thread`、`ms`、`status` |

`path` 是读者提问时所在的页面（已服务的 pathname，因此在设置了 `base` 时它与反馈小组件和你的页面浏览量一致），`questionChars` 是问题的长度，`thread` 是对话的 ID（读者清空对话时即为新 ID），`ms` 是从发出问题到最后一个数据块的时间，`chars` 是答案的长度。`status` 是 HTTP 状态码：完全没有收到响应时为 `0`（离线、DNS、CORS）；响应本身正常、但数据流在答案中途断开时为 `200` —— 提供方或凭证错误正是这样暴露出来的，因为后端已经发出了响应头 —— 或者什么都没送达时。在答案中途清空对话不会上报其中任何一种结果。

问题的文本永远不会到达提供方：它是读者自由输入的内容（粘贴的密钥、错误日志、姓名），会违反大多数提供方的服务条款和单值大小限制。它只通过 `blume:track` 这个 DOM 事件传递，作为 `detail.props` 里的 `question`，因此你写的监听器可以自行决定把它转发到哪里。基于 `blume/hooks` 中 `useAssistant` 自建的聊天界面上报同样的事件。没有配置提供方时，内置的提供方调用都是空操作，但 `blume:track` 事件仍会触发，因此监听它的自定义集成照样能收到。

## 速率限制 [#rate-limiting]

`POST /api/ask` 端点**不做认证** —— 必须如此，页面内的助手才能调用它。Blume 会校验每个请求 —— 拒绝格式错误的请求体、把它限制在 1–40 条消息、只接受 `user`/`assistant` 角色，以免调用方注入自己的系统提示词、把这条路由挪用成通用 LLM 代理 —— 以限制单次调用能在你的模型上花掉多少。[速率限制](/docs/configuration/rate-limiting/)默认开启，它进一步限制单个读者能提多少个问题：超出之后，面板会提示他们几分钟后再试。

## Bot 防护 [#bot-protection]

速率限制按 IP 地址计数，因此一个把问题分散到大量地址上的脚本能绕过它。要拦住脚本，就加入一个来自 `blume/captcha` 的 bot 检查：每次提问之前，面板先从检查中取到一个 token，路由在模型运行之前向提供方验证它。大多数读者根本不会看到挑战；只有在检查没有把握时才会要求点一下。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { turnstile } from "blume/captcha";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      captcha: turnstile({ siteKey: "0x4AAAAAAA…" }),
    },
  },
});
```

| 适配器 | 提供方 | 密钥环境变量 |
| --- | --- | --- |
| `turnstile()` | [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) | `TURNSTILE_SECRET_KEY` |
| `hcaptcha()` | [hCaptcha](https://www.hcaptcha.com)，以无感方式运行 | `HCAPTCHA_SECRET_KEY` |

site key 会下发到浏览器，可以安全提交；密钥留在服务器上。对 Turnstile，请在 Cloudflare 控制台里创建一个组件，并选择 **Managed** 或 **Invisible** 模式。在密钥设置好之前，助手会回答「尚未配置」，`blume build` 也会发出警告。提供方的脚本会在读者的第一个问题到来时加载，而不是随页面一起加载。

检查失败时，会给读者显示一条已翻译的「我们无法确认你是真人」提示，路由以 `403` 应答。两家提供方都公开了始终通过的测试密钥，方便在本地试验：Turnstile 的 `1x00000000000000000000BB` 搭配密钥 `1x0000000000000000000000000000000AA`，hCaptcha 的 `10000000-ffff-ffff-ffff-000000000001` 搭配 `0x0000000000000000000000000000000000000000`。

使用[外部端点](#external-endpoint)时，面板仍会发送那个 token，放在请求体的 `captcha` 字段里，由你的后端验证。

该端点会与站点其余的机器可读输出面一起，写进 [agent 可读性清单](/docs/discoverability/agent-discovery/)。

---

# Cookie 同意
Source: https://blume.ndjp.net/docs/configuration/consent/
English: https://useblume.dev/docs/configuration/consent

在 `blume.config.ts` 中设置 `consent`，就能在[分析](/docs/configuration/analytics/)脚本运行前先询问读者。它接受一个来自 `blume/consent` 的适配器：Blume 自带的横幅，或者你已经在用的托管同意管理器。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { googleAnalytics, posthog } from "blume/analytics";
import { native } from "blume/consent";

export default defineConfig({
  analytics: [
    googleAnalytics({ id: "G-XXXXXXXXXX" }),
    posthog({ key: "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }),
  ],
  consent: native({ policy: "/privacy" }),
});
```

设置 `consent` 后，每个分析适配器都会等待。它的标签已经在页面里，但要到读者允许分析之后才会运行，并且按你列出的顺序运行。拒绝的读者永远不会加载它们，也看不到[页面评分](/docs/configuration/)及其评论框，因为他们的回答无处可去。Vercel Web Analytics 无论如何都会加载，因为它的组件不是 Blume 能拦下的标签，但在读者允许分析之前它不会发送任何数据。

:::note
同意管理是可选启用的。没有 `consent` 时，分析会像往常一样在页面加载时运行。
:::

## 适配器 [#adapters]

| 适配器 | 同意管理器 | 必填 |
| ---------- | ------------------------------------ | ------------------------ |
| `native()` | [Blume 自带的横幅](#blumes-banner) | —                        |
| `osano()`  | [Osano](#osano)                      | `customerId`、`configId` |
| `ethyca()` | [Ethyca](#ethyca)                    | `privacyCenter`          |

## Blume 自带的横幅 [#blumes-banner]

`native()` 会在读者做出选择之前，在页面底部显示一张小卡片，**接受**与**拒绝**并排摆放，让拒绝和接受一样容易。这个选择保存在读者的浏览器里，一旦给出，横幅就不会再出现。

```ts blume.config.ts lineNumbers
consent: native({
  policy: "/privacy", // 可选：把横幅链接到你的隐私政策
}),
```

`policy` 接受一个页面路由或完整 URL。横幅文案在每个内置语言中都已翻译。要修改措辞，用 `i18n.ui` 覆盖 `consent` 的 [UI 字符串](/docs/content/i18n/)（`message`、`accept`、`decline`、`policy`、`settings`）。

横幅在 `blume dev` 中同样有效，所以你写作时就能看到它。分析脚本本身只在生产构建中加载。

## Osano [#osano]

`osano()` 会加载 [Osano Cookie Consent](https://www.osano.com)，展示你在 Osano 控制台中设置好的横幅和抽屉。等 Osano 报告读者已同意分析时，Blume 就运行你的分析脚本；之后每当读者更改选择时再运行一次。两个 ID 都来自 Osano 提供给你的脚本标签：`https://cmp.osano.com/<customerId>/<configId>/osano.js`。

```ts blume.config.ts lineNumbers
import { osano } from "blume/consent";

consent: osano({ customerId: "AzZdRbSIoEzZU2", configId: "7b9e2f4a-…" }),
```

Osano 按你在其控制台中选择的合规模式，决定各个地区什么才算同意。

## Ethyca [#ethyca]

`ethyca()` 从你的隐私中心加载 [Ethyca 的 Fides](https://www.ethyca.com) 同意管理器，展示你在 Fides 中设置好的横幅和弹窗。等读者的分析通知处于开启状态时 —— 已选择加入、未选择退出，或只是一个要求他们确认知悉的通知 —— Blume 就运行你的分析脚本。

```ts blume.config.ts lineNumbers
import { ethyca } from "blume/consent";

consent: ethyca({
  privacyCenter: "https://privacy.example.com",
  propertyId: "FDS-XXXXXX", // 可选：要加载哪个 Fides 属性
  notice: "analytics", // 可选：涵盖分析的通知键
}),
```

`notice` 默认为 `analytics`。当你在 Fides 中针对分析的通知用的是另一个键时，才需要设置它。

与分析一样，Osano 和 Fides 也只在生产构建中加载，所以在 `blume dev` 中测试不会产生任何同意记录。用 `blume build` 和 `blume preview` 来预览它们。

## 更改选择 [#changing-an-answer]

设置 `consent` 后，站点页脚会显示一个 **Cookie 设置**链接。它会重新打开 Blume 的横幅，或托管同意管理器的偏好设置面板。如果你用自己的 [`Footer`](/docs/configuration/customization/) 替换了页脚，给任意元素加上 `data-blume-consent-open` 属性，就能让它成为这个链接：

```html
<button data-blume-consent-open type="button">Cookie settings</button>
```

读者如果先允许分析、之后又收回同意，页面会重新加载 —— 这是唯一能停下已经启动的脚本的办法。从那以后分析就一直保持关闭。

## 你自己的脚本 [#your-own-scripts]

你自己的任何脚本也用同样的方式拦下：给它 `type="text/plain"` 和 `data-blume-consent="analytics"`，它就会在读者允许分析之后运行。若想自己响应对话结果，监听 `window` 上的 `blume:consent` 事件，其 `detail.analytics` 就是读者的选择。`window.blumeConsent.analytics` 保存当前选择：在同意管理器给出答复之前为 `null`，之后为 `true` 或 `false`。

```js
window.addEventListener("blume:consent", (event) => {
  if (event.detail.analytics) {
    // 启动需要同意才能运行的东西
  }
});
```

---

# 定制
Source: https://blume.ndjp.net/docs/configuration/customization/
English: https://useblume.dev/docs/configuration/customization

## 组件覆盖 [#component-overrides]

在项目根目录添加一个 `components.ts`（或 `components.tsx`）并导出 `defineComponents`。其中的 `mdx` map 既可以**替换**内置组件，也可以**新增**一个组件 —— 新组件在任何 `.mdx` 页面里都能用，无需 import。

```ts components.ts lineNumbers
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";
import Pricing from "./components/Pricing.astro";

export default defineComponents({
  mdx: {
    Callout, // 替换内置的 Callout
    Pricing, // 新增一个 <Pricing /> 组件
  },
});
```

键就是你在 MDX 里书写的名称（`<Callout>`、`<Pricing>`）。当你 import React 组件时，请使用 `.tsx` 文件名。

### 引用形式 [#reference-form]

每个覆盖项 —— 无论在 `mdx` 还是 `layout` 中 —— 都接受三种形式：

```ts components.ts
import { defineComponents } from "blume";
import Callout from "./components/Callout.astro";

export default defineComponents({
  mdx: {
    Callout, // 1. import 进来的组件
    Note: "./components/Note.astro", // 2. 路径字符串（相对项目根目录解析）
    Chart: { component: "./components/Chart.tsx", client: "load" }, // 3. 描述符
  },
});
```

Blume 以静态方式读取 `components.ts` —— 它从不执行该文件 —— 因此这三种形式就是它接受的全部。内联函数或表达式、在文件内部声明的组件、展开运算符、计算得到的键，以及不是下列模式字符串的 `client`，都会触发 `BLUME_COMPONENTS_INVALID` 错误并指明具体条目：`blume dev` 会在终端和浏览器浮层中报告它，`blume build` 则会直接失败。

**描述符**形式额外提供一个 hydration 模式，让交互式的 React/Vue/Svelte 组件携带自己的 JavaScript 并在客户端激活。没有 `client` 模式时，框架组件会渲染为静态 HTML —— Blume 发现这种情况时会打印构建警告，因为这通常是个错误。

| `client` | hydration 时机 |
| --- | --- |
| `"load"` | 页面加载时立即激活 |
| `"idle"` | 主线程空闲时激活 |
| `"visible"` | 滚动进入视口时激活 |
| `"media"` | `media` 查询匹配时激活（附加 `media: "(min-width: 40rem)"`） |
| `"only"` | 仅客户端，绝不服务端渲染 |

带 `client` 模式的 `mdx` 条目*就是*一个交互岛：它在每个页面都可用，hydration 行为与放进 [`islands/` 文件夹](/docs/content/islands/)的组件完全一致。那个文件夹仍然是零配置的路径 —— 当你想要一个不同于文件名的名称、一个 `media` 查询，或希望交互岛与其他覆盖项并排放置时，再使用 `components.ts` 条目。

### 为覆盖项标注类型

当你替换内置组件时，从 `blume/components` 中 import 它的 prop 类型，让你的组件符合那份契约 —— 这些类型是从组件本身推导出来的，因此永远不会失配：

```tsx components/Callout.tsx
import type { CalloutProps } from "blume/components";

export default function Callout(props: CalloutProps) {
  // ……你自己的提示框，prop 与内置版相同
}
```

内容组件的 prop 类型都有导出（`CalloutProps`、`CardProps`、`TabsProps`、`StepsProps`、`BadgeProps` 等）。

## 布局插槽 [#layout-slots]

`layout` map 用你自己的组件替换 Blume 的某块界面外壳。每个覆盖项接收到的 prop 与它所替换的内置组件完全相同，因此你可以包裹默认实现，也可以从零开始。

```ts components.ts
import { defineComponents } from "blume";
import Footer from "./components/Footer.astro";
import Logo from "./components/Logo.astro";

export default defineComponents({
  layout: {
    Logo, // 页头中的品牌标识 + 标题
    Footer, // 全站页脚，取代 `footer` 配置的那个
  },
});
```

已接线的插槽：

| 插槽 | 替换对象 | Props |
| --- | --- | --- |
| `Layout` | 整个页面外壳（`RootLayout`） | 内置布局接收到的全部内容，外加 `layout` map |
| `Header` | 顶部导航栏 | `site`、`logo`、`navigation`、`route`、`searchEnabled` 等 |
| `Logo` | 页头中的品牌链接（标识 + 标题） | `site`、`logo`、`locale` |
| `Search` | 页头搜索触发按钮 + 弹窗 | `navigation`、`strings`、`locale`、`assistantEnabled` |
| `Sidebar` | 主导航树 | `items`、`currentRoute` |
| `MobileNav` | 移动抽屉内的导航（默认复用 `Sidebar`） | `items`、`currentRoute` |
| `Breadcrumbs` | 面包屑路径 | `crumbs` |
| `TableOfContents` | 本页大纲 | `headings`、`title`、`variant` |
| `Pagination` | 上一页/下一页页脚链接 | `prev`、`next`、`strings` |
| `Feedback` | 文章下方的“这个页面有帮助吗？”评分（仅在 [`feedback`](/docs/configuration/)开启时渲染） | `strings`、`comments` |
| `PageHeader` | 文章上方的注入点（无内置实现） | `page`、`headings`、`route` |
| `PageFooter` | 文章下方的注入点（无内置实现） | `page`、`headings`、`route` |
| `Footer` | 内容网格之后的[站点页脚](/docs/configuration/)：链接、社交资料、仓库链接和 Cookie 设置 | `footer`、`locale`、`site`、`navigation`、`ui` |

`PageHeader` 和 `PageFooter` 没有内置组件 —— 在你设置它们之前什么都不渲染，这使它们成为放置促销横幅或“最后更新于”提示的便捷注入点。内置的 `Footer` 保存着通往你的仓库和社交资料的唯一链接，因此 `Footer` 覆盖项（配置无法表达的营销型页脚该放的地方）应该保留它们。设置了 `consent` 时，同样要保留重新打开它的入口：任何带 `data-blume-consent-open` 的元素都可以充当 [Cookie 设置](/docs/configuration/consent/)链接。

布局插槽接受与 MDX 覆盖项相同的[三种引用形式](#reference-form)，因此插槽可以是路径字符串，也可以在你想要交互式页头或页脚时使用已 hydration 的描述符（`{ component, client }`）。

## 交互岛 [#interactive-islands]

对于交互式 UI（React、Vue 或 Svelte），把组件放进 `islands/` 文件夹，然后在任意 MDX 页面中使用它 —— Blume 会替你完成 hydration，无需任何包装或注册：

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>Clicked {n}</button>;
}
```

```mdx page.mdx
Use it anywhere: <Counter />
```

hydration 策略和框架配置参见 [Islands](/docs/content/islands/)。

## 自定义页面 [#custom-pages]

在 `pages/` 文件夹下添加 `.astro` 文件，让完全自定义的路由与文档并存 —— 一个落地页、一个定价页，或手工搭建的索引页。它们保留自己的位置，因此相对 import 和 `getStaticPaths` 都照常工作，并且可以从 `blume:data` 模块读取你的配置、导航和路由。

完整指南参见 [Custom pages](/docs/advanced/custom-pages/)。

## 组件注册表

`blume add` 会把一个由 Blume 维护的组件以**源码**形式复制到你的项目里 —— 它归你所有，你可以随意编辑。不带参数运行它可以列出可用的组件：

```bash
blume add
```

安装一个布局插槽（页头、侧边栏、面包屑、目录、分页或反馈）或任意内容组件（提示框、卡片、标签页、步骤、折叠面板等）：

```bash
blume add callout
blume add pagination
```

复制过来的文件从 `blume/*` 引入框架的其余部分，因此在你改动之前它的渲染效果与内置版完全一致。`blume add` 会打印用于注册它的 `defineComponents` 片段 —— 内容组件放在 `mdx` 下，布局部件放在 `layout` 下。

## Astro 集成 [#astro-integrations]

通过 `blume.config.ts` 顶层 `integrations` 数组添加任意 Astro 集成。请先在你的站点中安装该集成；Blume 不会把它加入生成运行时的依赖，也不会管理它的 Astro 兼容性。

```bash
npm install @astrojs/partytown
```

```ts blume.config.ts lineNumbers
import partytown from "@astrojs/partytown";
import { defineConfig } from "blume";

export default defineConfig({
  integrations: [
    partytown({
      config: { forward: ["dataLayer.push"] },
    }),
  ],
});
```

Blume 保持自身内置集成的原有顺序，然后按声明顺序追加你的条目。它不会排序或去重，因此两个 `name` 相同的集成都会运行。Blume 只校验 `integrations` 是数组，每个条目则由 Astro 校验并报告无效集成。

由于 Blume 加载集成的方式是从生成的 Astro 配置中重新 import `blume.config.ts`，而不是复制实例，配置模块每次运行会求值两次 —— 一次在 Blume 读取你的配置时，一次在 Astro 加载它时。请保持集成工厂无副作用（返回集成即可，不要在构造时写文件或打开连接），这样第二次求值就是无害的。

同样的集成在 `blume dev` 和 `blume build` 中都会运行。在 `blume dev` 期间编辑 `blume.config.ts` 会重新生成隐藏的 Astro 配置并触发配置重启；如果改动后的集成没有生效，请重启 `blume dev`。Blume 无法判断哪些配置改动会影响集成，因此一旦 `integrations` 非空，对 `blume.config.ts` 的每一次编辑 —— 即使改的是无关字段 —— 都会重启开发服务器，而不是热更新。Blume 只跟踪 `blume.config.ts` 的内容，因此编辑它 import 的其他文件不会单独触发生成 —— 这类编辑之后请重启 `blume dev`。如果你 eject 了，Blume 托管的 `astro.config.mjs` 会保留一条指向 `blume.config.ts` 的相对桥接，因此配置好的集成仍会运行；之后你可以在完全接管时把它们直接移进 Astro 配置。

## Eject [#eject]

当你想要完全的控制权时，把生成的运行时 eject 成一个独立的 Astro 项目：

```bash
npx blume eject --yes
```

eject 是单向操作：隐藏的 `.blume/` 运行时变成一个归你所有、可直接修改的普通 Astro 应用。`blume` 包依然可以 import，因此你保留了它的组件、主题和 Markdown 处理器。

eject 会把 `package.json` 里的脚本指向 `astro dev` 和 `astro build`，并按名称加入这个 Astro 应用所 import 的包 —— 生成的样式表需要 `astro`、`@tailwindcss/vite`、`tailwindcss` 和 `@tailwindcss/typography`，还有搜索客户端、集成、配置接线的 adapter，交互岛/示例/assistant 用到 React 时需要 `react`，assistant 路由需要 `ai`，EPUB 导出需要 `epub-gen-memory` —— 版本范围与 Blume 自身使用的一致。在 `dev` 或 `build` 之前先跑一次安装；eject 会列出它添加了什么。ejected 应用中的每个路径都是相对的，因此在任何检出目录下都能构建，CI 也不例外。

从那以后，请通过应用自己的脚本运行它（`npm run dev`、`npm run build`）：在 ejected 项目里 `blume dev`、`blume build`、`blume check`、`blume sync` 和 `blume preview` 都会停下并提示你改用这些脚本。再次运行 `blume eject` 同样会被拒绝，因为它会覆盖你的修改；传 `--force` 可以无论如何重新生成应用。

### eject 保留了什么

隐藏运行时作为页面提供的路由会被写进应用的 `src/pages`，因此它响应同样的 URL：每个页面的 Markdown 孪生版本、带 `/404.md` 与 `/404.json` 孪生版本的 [404 页面](/docs/advanced/custom-pages/)、托管的 MCP server，以及位于 `/api/docs/…` 和 `/openapi.json` 的 [JSON 文档 API](/docs/discoverability/json-api/) —— `llms.txt` 和未找到页面会把 agent 指向它们。

ejected 应用的 `build` 脚本运行的是普通的 `astro build`，而 `blume build` 叠加在其上的产物 —— 搜索索引（以及托管提供方的索引同步）、`llms.txt` 和 `llms-full.txt`、`sitemap.xml`、`robots.txt`、`agent-readability.json`、`.well-known` 探测文件、Agent Skills，以及平台的 `_redirects`/`_headers` 文件 —— 依然会产出：ejected 的 `astro.config.mjs` 中的 Blume 集成会从 Astro 的 `astro:build:done` hook 写出它们，扫描项目（你的 `blume.config.ts` 和内容）的方式与 CLI 当年一致。ejected 构建不再做的是 CLI 的 adapter 后处理：Vercel 和 Cloudflare 的 `Accept: text/markdown` 路由拼接、Vercel 函数包审计、`node()` 服务器入口包装（`.well-known` 探测文件的 media type 和 CORS 头、对下载 SVG 的沙箱处理，以及每个重定向的确切状态码）、`netlify()` 服务器构建写入 `.netlify/v1/config.json` 的响应头规则、Cloudflare Worker 的命名（取自你的项目名）及其用于在项目根目录执行 `wrangler deploy` 的 `.wrangler/deploy` 重定向，以及 `--analyze`/`--budget-*` 质量门禁。

---

# 导出
Source: https://blume.ndjp.net/docs/configuration/export/
English: https://useblume.dev/docs/configuration/export

Blume 可以在目录下方添加一个 **Export** 操作（见[页面操作](/docs/content/navigation/)），让读者把当前页面保存为 **PDF** 或 **EPUB**。它默认关闭，且完全在客户端完成 —— 没有服务端，[静态](/docs/deployment/)构建依然是静态的。

## 启用

一个开关即可同时启用两种格式：

```ts blume.config.ts
export: true,
```

如果只想提供其中一种格式，改为传入一个对象：

```ts blume.config.ts
export: {
  pdf: true,
  epub: false,
},
```

你省略掉（或设为 `false`）的格式不会出现在菜单里。两种都关闭时（默认值），**Export** 操作根本不会出现。

## PDF

**Export to PDF** 会打开浏览器的打印对话框，并使用一份打印样式表把站点外壳 —— 页头、侧边栏、导航 —— 剥离掉，只留下正文。选择 **Save as PDF** 即可完成。

由于它打印的是带完整样式的实时页面，导出结果会保留清晰、可选中的文字、真实字体以及带语法高亮的代码。它不依赖任何东西，在开发环境、生产环境和静态托管上都表现一致。

:::note
PDF 导出走的是浏览器原生的打印对话框，因此 "Save as PDF" 的具体措辞和可选项取决于浏览器。在对话框中开启 **Background graphics**，才能保留代码块和提示框的背景。
:::

## EPUB

**Export to EPUB** 会在浏览器中生成当前页面的自包含 `.epub` 文件并触发下载 —— 可以直接放进 Apple Books、Calibre 或任何电子阅读器。生成器只在读者点击 Export 时才加载，因此绝不会拖慢你站点的其余部分。

为了让文件在没有样式表、也没有 JavaScript 的设备上依然可读，Blume 会把页面重写为干净的独立 HTML：带语法高亮的代码变为纯等宽文本，装饰性图标和复制按钮被移除，间距、代码块和表格则由内置的电子阅读器样式表负责处理。

## 导出的内容

两种格式导出的都是读者正在查看的**单个页面**，而不是整个站点 —— 这与该操作的位置一致，它就在该页目录的下方。

:::note
EPUB 里没有 JavaScript 来切换标签页，因此带标签页的内容 —— 例如 [package-install](/docs/content/syntax/) 代码块和代码组 —— 会被展开，一次性展示所有面板。客户端渲染的嵌入内容（例如 Mermaid 图）不会包含在内。
:::

---

# 朗读
Source: https://blume.ndjp.net/docs/configuration/narration/
English: https://useblume.dev/docs/configuration/narration

朗读会在每个页面的描述下方加一个 **收听本页**播放器。读者按下播放，页面就从标题开始逐句朗读，被读到的句子会高亮并保持在视野内。它需要手动启用：

```ts blume.config.ts lineNumbers
export default defineConfig({
  narration: true,
});
```

设为 `true` 时，页面使用读者设备自带的[浏览器语音](#browser-voices)朗读：无需密钥，无需构建步骤，在任何托管平台上都能工作，静态的或非静态的都可以。加上一个 `provider` 则改用[生成的语音](#generated-voices)。

## 它朗读哪些内容 [#what-it-reads]

朗读会按顺序读出页面标题、描述、各级标题、段落、列表项和卡片文字。有些组件前面会加一句简短的语音提示，让听者知道接下来是什么内容：

| 组件 | 提示 |
| --- | --- |
| [提示框](/docs/content/syntax/) | 「注意。」「提示。」「警告。」等等 |
| [Steps](/docs/content/components/) | 「第 1 步。」「第 2 步。」 |
| [Tabs](/docs/content/components/) | 「macOS 标签页。」每个标签页都会被朗读，不只是当前打开的那个 |
| [Accordion](/docs/content/components/) 和 [Expandable](/docs/content/components/) | 「可展开区块。」 |

当朗读遇到折叠起来的区块或未显示的标签页时，会把它展开，这样高亮总能落在读者看得见的文字上。

代码块、表格、图片、视频、图表、公式、类型展示、文件树和实时组件预览都会被跳过 —— 它们读出来没有意义。

只有正文足够多、值得一听的页面才会出现播放器，大约 50 词以上。很短的页面，以及大部分由代码或 API 字段构成的页面，都不会出现播放器。

## 收听 [#listening]

页面播放时，播放器会固定在页头下方，包含播放与暂停、上一句与下一句、进度条、已读时间与页面总长度的对比，以及 0.8× 到 2× 的倍速控制。这个倍速会被记住，下一页继续沿用。

页面会自动滚动，让正在朗读的句子保持在视野内。如果读者自己滚走了，跟随就会停止而音频继续播放；滚回那个句子，或者按下 **跟随朗读**，就会重新跟上。打开另一个页面会停止朗读。

## 浏览器语音 [#browser-voices]

`narration: true` 使用 [Web Speech API](https://developer.mozilla.org/docs/Web/API/SpeechSynthesis) 和读者设备上的语音来朗读页面，并按页面语言挑选一个合适的声音。如果浏览器没有该语言的声音，播放器会保持隐藏，而不是用错误的口音把页面念出来。

这不需要你提供任何东西，也不产生任何费用，但效果取决于设备：macOS、iOS 和 Windows 上的系统语音都不错，而某些 Linux 浏览器自带的语音很少，甚至一个都没有。

## 生成的语音 [#generated-voices]

传入一个 `provider`，就能在构建时用神经语音模型生成音频。这个 provider 就是 assistant 使用的同一个 [`gateway()`](/docs/configuration/assistant/)适配器，只是指向一个语音模型：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { gateway } from "blume/ai";

export default defineConfig({
  narration: {
    provider: gateway({
      model: "openai/tts-1-hd",
      voice: "alloy",
    }),
  },
});
```

`blume build` 会完全按播放器的方式读取每个构建好的页面，把它拆成句子，并通过 [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) 为每个句子生成一段音频。这些音频和每页一份的小清单会作为静态文件写入你的构建产物，放在 `/blume-narration/` 下，因此重播不花任何代价，也没有任何东西在服务器上运行。

在生成任何东西之前，构建会先打印它需要多少段新音频、总共覆盖多少字符，让成本一目了然：

```txt
Generating narration: 214 new clip(s), 15,880 characters, with openai/tts-1-hd
```

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `model` | `openai/tts-1-hd` | gateway 的语音模型：`openai/tts-1`、`openai/tts-1-hd`、`fish-audio/s2.1-pro`、`spacexai/grok-tts`，以及 gateway 列出的其它模型。 |
| `voice` | `alloy` | 模型使用的声音。 |
| `instructions` |  | 指定声音该如何朗读，适用于接受指令的模型（「像一位老师那样，平静地朗读」）。 |
| `apiKeyEnv` | `AI_GATEWAY_API_KEY` | 保存 gateway 密钥的环境变量。在 Vercel 上，构建的 OIDC token 同样可用。 |
| `headers` |  | 随每次请求发送的静态响应头。 |
| `providerOptions` |  | 原样传给 AI SDK 的 `generateSpeech`，用于 Blume 没有具名列出的模型设置。 |

### 缓存 [#caching]

音频会按决定其声音的那些条件缓存在 `node_modules/.cache/blume/narration` 下：句子本身、它的语言、模型、声音和指令。重新构建时只需为发生变化的句子付费，被多个页面共用的句子只生成一次。Vercel 和 Netlify 会从各自的构建缓存中恢复 `node_modules`，所以在那里部署只会重新生成变化的部分。在其它 CI 上，请在两次运行之间缓存这个目录。

### 回退 [#fallbacks]

在没有音频的地方，生成的语音会回退到浏览器语音：

- 在 `blume dev` 中，它从不生成音频。运行 `blume build` 和 `blume preview` 就能在本地听到生成的语音。
- 构建时未设置密钥。构建会发出警告并跳过生成。
- 生成失败时。由于 AI SDK 已经重试过，构建会在第一段失败的音频处停下，并保留所有已缓存的音频。

## 语言 [#languages]

朗读会用每个页面自身的内容语言进行，因此在一个[国际化](/docs/content/i18n/)的站点上，每个 locale 都用自己对应的声音朗读。这些语音提示和播放器标签在每个内置 UI 语言中都已翻译。要按 locale 覆盖它们，在 [`i18n.ui`](/docs/content/i18n/) 中改写 `narration` 下的内容。

## 为单个页面关闭它 [#turning-it-off-for-a-page]

在页面的 [frontmatter](/docs/content/frontmatter/) 中设置 `narration: false`，就能让该页面不出现播放器：

```yaml
---
title: Changelog
narration: false
---
```

## 让内容不被朗读 [#keeping-content-out]

给某个元素加上 `data-blume-narration="skip"`，就能让它及其内部的一切都不参与朗读。Blume 就是靠它跳过自己的类型展示和预览的，对你自己的组件和交互岛同样有效：

```html
<div data-blume-narration="skip">
  <PricingCalculator />
</div>
```

## 分析 [#analytics]

读者开始收听时，播放器会发送一个 `narration_play` 事件，附带 `engine`（`audio` 或 `browser`）和页面的 `path`；页面播放到结尾时再发送 `narration_complete`。这两个事件和其它自定义事件一样，都会经过你的[分析](/docs/configuration/analytics/)适配器。

---

# 速率限制
Source: https://blume.ndjp.net/docs/configuration/rate-limiting/
English: https://useblume.dev/docs/configuration/rate-limiting

读者每调用一次服务端路由，你都要付出一定成本：[assistant](/docs/configuration/assistant/) 会消耗模型 token，[API playground](/docs/references/openapi/) 代理会向你的 API 转发请求，[Mixedbread 搜索](/docs/configuration/search/) 则执行一次付费查询。Blume 会限制单个读者（按 IP 地址识别）调用它们各自的频率。超出限制的读者会收到 `429 Too Many Requests` 以及一个 `Retry-After` 响应头，assistant 则会提示他们几分钟后重试。

速率限制默认开启，每位读者每条路由每 10 分钟 30 次请求：多到一个人永远不会碰到，少到足以拦下一个脚本。它只对服务端构建有意义；静态站点没有服务端路由可供限制。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { upstash } from "blume/ratelimit";

export default defineConfig({
  rateLimit: upstash({ requests: 30, window: 600 }), // window 以秒为单位
});
```

每条路由各自计数，因此一次繁忙的 playground 会话不会吃掉读者用于 assistant 提问的额度。

## 计数保存在哪里

| 适配器 | 计数保存在 | 限制生效范围 |
| --- | --- | --- |
| `memory()` | 服务端进程内存（默认） | 精确限于单个服务器；在 serverless 托管上按实例计算 |
| `upstash()` | [Upstash Redis](https://upstash.com) | 在每个托管上都精确生效 |
| `cloudflare()` | Cloudflare Workers 速率限制 | 按 Cloudflare 站点位置计算 |

### Memory

`memory()` 不需要任何依赖。在以单进程运行的服务器上，例如 `deployment: node()`，计数是精确的。Vercel、Netlify 和 Cloudflare 会运行许多短生命周期的实例，每个实例各自计数，所以在这些平台上它只能拦下一个读者的突发请求，而非精确执行限制。若想在这些托管上获得精确限制，请使用下面任意一种共享存储。

```ts blume.config.ts lineNumbers
import { memory } from "blume/ratelimit";

rateLimit: memory({ requests: 60, window: 600 }),
```

### Upstash

`upstash()` 把计数保存在 Upstash Redis 中，所有实例共享同一份。先创建一个数据库（在 Vercel 上可从 Marketplace 添加 Upstash），然后把它的 REST endpoint 和 token 分别设为 `UPSTASH_REDIS_REST_URL` 与 `UPSTASH_REDIS_REST_TOKEN`。Blume 通过 Upstash 的 REST API 通信，因此无需安装任何东西。在两者都设置好之前，路由会在内存中计数，并且 `blume build` 会给出警告。

```ts blume.config.ts lineNumbers
import { upstash } from "blume/ratelimit";

rateLimit: upstash(),
```

### Cloudflare

`cloudflare()` 使用 [Workers 速率限制](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/)计数，适用于以 `deployment: cloudflare()` 部署的站点。Blume 会在构建时于 Worker 配置中声明该绑定，因此无需任何额外设置。Cloudflare 按位置计数，窗口只能是 10 秒或 60 秒，所以它的默认值是每 60 秒 10 次请求。

```ts blume.config.ts lineNumbers
import { cloudflare } from "blume/deploy";
import { cloudflare as cloudflareRateLimit } from "blume/ratelimit";

export default defineConfig({
  deployment: cloudflare(),
  rateLimit: cloudflareRateLimit({ requests: 10, window: 60 }),
});
```

绑定的命名空间来自 Worker 的名称，因此同一账户下的两个站点不会共享计数。设置 `namespaceId` 可以自行指定。

## 关闭它

设置 `rateLimit: false` 可以放行所有请求 —— 例如当你的托管方防火墙已经在限制这些路由时。主机无法识别来源地址的请求始终会被放行，共享存储计数失败的请求同样如此：失败会被记录下来，因此存储服务中断不会把读者挡在门外。

对于 assistant，请把速率限制与 [bot 检查](/docs/configuration/assistant/)搭配使用，以拦下把请求分散到大量地址上的脚本。

---

# 搜索
Source: https://blume.ndjp.net/docs/configuration/search/
English: https://useblume.dev/docs/configuration/search

Blume 自带本地搜索，不依赖任何托管基础设施，也不需要 API key。它在浏览器中运行，在 `blume dev` 和 `blume build` 中都能工作，并且只索引你的真实内容 —— 导航外壳和被排除的页面都会被跳过。当它不再够用时，你可以切换到托管或语义后端，而搜索的外观和行为都不变 —— 变的只是传给 `search` 的适配器。

每个后端都是从 `blume/search` import 的一个**适配器**：**Orama**（默认）、**FlexSearch**、**Pagefind**、**Algolia**、**Orama Cloud**、**Typesense** 和 **Mixedbread**。每个适配器自带它的选项、运行时依赖和所需密钥，因此只有被配置的那个适配器的 SDK 会被安装进你的项目 —— 选一个后端绝不会把其他的也拖进来。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { algolia } from "blume/search";

export default defineConfig({
  search: algolia({
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_SEARCH_ONLY_KEY",
    indexName: "docs",
  }),
});
```

适配器只是对后端的一份纯描述 —— 不是活动的客户端 —— 因此 Blume 能把它内联到生成的站点里，也能内联到 ejected 项目中。直接传适配器即可；如果你还想在旁边设置[热门链接](#popular-pages)或[索引](#whats-indexed)选项，就用对象形式：

```ts blume.config.ts lineNumbers
import { pagefind } from "blume/search";

search: {
  provider: pagefind(),
  popular: [{ href: "/guides/getting-started", icon: "rocket", label: "Getting started" }],
  indexing: { includeCodeBlocks: true },
},
```

## 使用搜索

用页头的搜索图标、⌘K（或 `Ctrl K`），或者在未处于输入状态时按 `/` 打开搜索。`Esc` 关闭它，`⌘J`（或 `Ctrl J`）切换结果预览面板。

查询会匹配页面的**标题**、**描述**和**正文**文字，标题匹配权重最高，其次是描述，最后是正文。

## 热门页面 [#popular-pages]

在读者输入查询之前，搜索对话框会显示一份 **Popular** 列表。默认是侧边栏的前六个页面 —— 在多标签站点上这往往会把读者带到错误的分区。请改为固定你想要的链接：

```ts blume.config.ts lineNumbers
search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},
```

每个条目接受一个 `href`（站内路由或外部 URL）和一个 `label`，还可以选填 `icon` —— 一个[内置图标](/docs/content/components/)名称、图片路径/URL，或内联 SVG（与导航图标相同的_输入_），默认是一个文件字形。省略 `popular` 或留空则保留侧边栏兜底。在对象形式中不写 `provider` 会保留默认的 Orama 适配器。

`href` 要按站点挂载在根路径来写 —— `basePath` 会自动加上，和 `navigation.featured` 一样。外部 URL 则原样透传。

> **警告**
>
> 精选列表是所有语言共用的一套链接。在配置了 `i18n` 的站点上，侧边栏兜底会跟随读者的 locale，
> 但 `popular` 条目只会跳向其 `href` 所指的地方 —— 因此只有当你想让每位读者都被送到
> 同一种语言时，才固定带 locale 前缀的路由。

## 索引了什么 [#whats-indexed]

对 Orama、FlexSearch、Algolia、Orama Cloud 和 Typesense —— 以及 MCP server 的 `search_docs` 工具 —— Blume 会索引每个页面的标题、描述，以及被简化为纯文本的正文：代码块、图片和标记会被剥离，因此结果保持相关性。这些索引从你的源文件构建，所以在开发环境和生产环境中完全一致。Pagefind 改为索引构建后的 HTML，Mixedbread 则同步你的原始 Markdown，因此这两者始终都能搜到代码。

如果你的文档依靠代码示例来暴露诸如选项、方法或错误名这类可搜索的词，请把围栏代码纳入基于源文件的索引：

```ts blume.config.ts lineNumbers
search: {
  indexing: {
    includeCodeBlocks: true,
  },
},
```

每个围栏的正文和标题（上面那个围栏的标题是 `blume.config.ts`）都会变得可搜索；语言标记和围栏标记本身不会。在 `.mdx` 页面上，索引按组件显示出来的文字来读取它们 —— Card 的标题、Tab 的标签、TypeTable 的描述 —— 使用与 [agent surfaces](/docs/discoverability/markdown/)相同的序列化器，因此一个 `agents.markdownComponents` 条目同样能覆盖你自己的组件。该选项对 Pagefind 和 Mixedbread 无效。请预期索引会随你的围栏内容一起增长 —— 客户端索引会分发给每位读者，托管适配器则限制记录大小（当某个页面的记录超过套餐上限时，Algolia 会拒绝这批同步，从而保留上一份可用索引），而命中围栏内部的结果会在摘要中显示扁平化的代码。

在[带版本](/docs/content/versioning/)的站点上，结果默认限定在当前查看的版本，对话框页脚有一个 "All versions" 开关（按读者记忆）。跨版本命中的结果会在行内标明其版本。Orama、FlexSearch、Algolia 和 Typesense 都遵循这一限定 —— 托管记录携带一个 `version` 分面，当前文档上传为 `"current"`。Pagefind、Orama Cloud 和 Mixedbread 不按版本限定：它们的结果横跨所有版本，对话框中也不会出现那个开关。

## 标签

在页面 frontmatter 中添加 `search.tags`，把它归入搜索对话框中的一个筛选项 —— 读者一键即可把结果收窄到某个标签。标签在托管适配器上也会成为一个分面。

```yaml
search:
  tags: [api, reference]
```

## 排序权重 [#ranking]

两个 frontmatter 字段决定一个页面的排名。`search.keywords` 列出额外的检索词，即使页面正文里没用到这些词也能被搜到。它适合那些读者会用旧名称、缩写或竞品术语来搜索的页面。`search.boost` 则把页面的相关性乘上一个系数：大于 1 会把它排上来，小于 1 会把它压下去。

```yaml
search:
  keywords: [install, setup, getting started]
  boost: 3
```

只给读者最常用的少数几个页面加权重，比如快速上手或概览，取值在 2 到 5 之间。对于那些应当排在同等匹配页面之后的页面，比如一份遗留指南，可以使用小于 1 的值，例如 `0.5`。权重不要超过 10：再往上，权重就会淹没页面本身的匹配程度，让它在自己几乎不匹配的搜索里也位居榜首。

权重对页面的移动幅度取决于适配器：

- **Orama**（默认）和 **FlexSearch** 在排序前把每次匹配都乘上该页面的权重，因此权重为 3 就算作三倍。[MCP server](/docs/discoverability/mcp/)与 [assistant](/docs/configuration/assistant/)的搜索采用同样的排序方式。
- **Pagefind** 会更重地看待被加权页面的文字。它会抑制重复匹配，因此提升幅度小于乘数：权重为 5 会让该页排名更高，但更接近两倍而不是五倍。Pagefind 把超过 10 的权重按 10 计。
- **Algolia** 和 **Typesense** 在匹配程度相近的结果之间按权重排序，因此权重只在势均力敌时起决定作用，不会把较弱的匹配抬到强匹配之上。在 Algolia 上，同步会在你设置的任何 ranking 之后，为索引的自定义 ranking 追加 `desc(boost)`。
- **Orama Cloud** 会取回更大一批结果，再按相关性乘权重重新排序。
- **Mixedbread** 搜索的是你自己的存储，Blume 并不会把数据上传过去，因此权重和关键词都到不了它那里。

除 Mixedbread 外，所有适配器都会搜索关键词。

## 搜索分析 [#search-analytics]

配置了 [analytics 适配器](/docs/configuration/analytics/)之后，搜索会报告读者在找什么。查询在稳定下来之后才被记录 —— 停止输入一秒后，或读者选中某个结果或关闭对话框时 —— 记为一个 `search` 事件，包含 `query`、结果数量 `results`，以及发起搜索的 `path`。没有结果的查询会以 `results: 0` 出现，因此按它筛选就能列出文档尚未覆盖的内容。选中某个结果会发出一个 `search_select` 事件，包含 `query`、该结果的 1 起始 `position` 和它的 `url`，用于统计点击率。

查询按原样发送，最长 100 个字符。你的 analytics 会像看到任何页面的搜索词一样看到它们，因此请把它们当作读者输入来对待。开启 [cookie consent](/docs/configuration/consent/)后，只有允许 analytics 的读者才会被计入。

## 适配器

客户端适配器无需密钥、也不需要任何选项 —— 它们的客户端是从 `i18n` 配置的（Pagefind 则从构建后的 HTML 配置），因此一个未知密钥会在配置校验时被拒绝，而不是被悄悄忽略。托管适配器接受**公开**凭据（可以安全地发到浏览器），并在构建时从环境变量读取它们的**密钥**管理密钥 —— 密钥绝不会进入配置或客户端 bundle。你传给托管适配器的每个选项都会被原样保留，并在浏览器中交给它的搜索客户端（或对 Mixedbread 而言，交给搜索端点），因此 Blume 没有命名的选项也能到达 SDK —— Algolia 的 `liteClient`、Typesense 的 `Client` 或 `OramaClient`。这些选项必须是 JSON 值 —— 描述符会作为字面量被内联到生成的项目中，因此函数、`undefined` 或 bigint 会让配置校验失败并报出具体路径，而不是在途中悄悄消失。

### Orama（默认）

Blume 的默认引擎。它构建一个在 `/blume-search.json` 提供的 JSON 索引，并在浏览器中查询它 —— 即时、纯客户端，并且在 `blume dev` 中随着你编辑而实时更新。没有密钥，没有服务。完全省略 `search` 就会选中它；只有在你想显式写出时才写：

```ts blume.config.ts lineNumbers
import { orama } from "blume/search";

search: orama(),
```

#### 非拉丁文字

Orama 的标准分词器只保留基本的拉丁字母、数字和少数几个带变音符的元音，因此其他任何文字系统中的文本 —— 日文、中文、韩文和泰文，俄文、希腊文、希伯来文和印地文同样如此 —— 否则会完全匹配不到任何结果。Blume 为你处理好这一点：当 [`i18n.defaultLocale`](/docs/content/i18n/)解析为非拉丁文字时，索引会切换到按词切分的分词器（基于浏览器和 Node 原生的 `Intl.Segmenter`）。只需声明你站点的语言：

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}
```

同一个分词器同时服务搜索对话框、MCP server 的 `search_docs` 工具和 assistant 的依据注入。做决定的是文字系统，而不是语言名称 —— `az-Cyrl` 会被切分，而 `sr-Latn` 不会 —— 而且整个索引由 default locale 决定：在多语言站点上，每个页面都共用默认 locale 的分词器。默认 locale 是非拉丁文字时这样做是安全的，因为拉丁单词在切分后依然完整，因此英文页面仍能与默认语言一起被搜到。反过来则不成立：在拉丁默认的站点上，非拉丁语言的译文无法被搜到。大量依赖变音符的拉丁文字语言（越南语，或用拉丁字母书写的塞尔维亚语）在标准分词器下表现也较差，因为它只折叠少数几个带变音符的元音，其余则会在词内切分。

日文和中文则更进一步。仅靠切分会把一个复合词按组成部分索引 —— 資金決済法 被拆成 資金、決済 和 法 —— 这会让某个只是零散提到各部分的页面排在真正讲这个词的页面之前。因此汉字、平假名和片假名会按相互重叠的字符对来索引，查询这些索引时会优先返回同时含有这些字符对的页面，当没有页面包含全部字符对时则放宽为任意配对匹配，因此输入一整句话仍能返回最接近的页面。韩文和泰文保留它们的切分结果。

### FlexSearch

第二个无需密钥的纯客户端选项。它复用 Orama 提供的同一个 `/blume-search.json` 索引，并在浏览器中构建一份 [FlexSearch](https://github.com/nextapps-de/flexsearch)文档索引。在 `blume dev` 和 `blume build` 中都能工作。

FlexSearch 没有对应的切分钩子，因此对于使用非拉丁文字的站点，请优先选择 Orama（默认）或 [Pagefind](#pagefind)，后者的 `pagefind_extended` 二进制能索引广泛的语言集合，并原生切分中文、日文和韩文。

```ts blume.config.ts lineNumbers
import { flexsearch } from "blume/search";

search: flexsearch(),
```

### Pagefind [#pagefind]

对于规模极大的文档，可以选用 [Pagefind](https://pagefind.app)。它索引你构建后的 HTML，并按需分片加载索引，因此无论站点多大，初始负载都很小。

```ts blume.config.ts lineNumbers
import { pagefind } from "blume/search";

search: pagefind(),
```

Pagefind 只在 `blume build` 期间运行，因此使用该适配器时搜索在 `blume dev` 中不可用。它索引每个文档页面的 article 部分 —— 而不是周围的页头、侧边栏或页脚 —— 因此基于 `PageLayout` 构建的自定义页面、404 页面以及生成的更新日志索引都不会出现在结果中。

### Algolia

浏览器用你的 search-only key 直接查询 [Algolia](https://www.algolia.com)。每次 `blume build` 都会用 `ALGOLIA_ADMIN_API_KEY` 中的管理密钥替换索引（若未设置，构建会警告并跳过上传）。整个索引在每次同步时都被整体替换，因此你删除或重命名的页面不会作为陈旧结果残留。同步还会把 `filterOnly(locale)` 和 `filterOnly(version)` 加入索引的 `attributesForFaceting`，同时保留你自己声明的任何分面 —— 因为对话框会按语言和文档版本限定结果，而在 Algolia 上，对一个未声明用于 faceting 的属性做过滤会匹配不到任何东西。

```ts blume.config.ts lineNumbers
import { algolia } from "blume/search";

search: algolia({
  appId: "YOUR_APP_ID",
  apiKey: "YOUR_SEARCH_ONLY_KEY", // 公开
  indexName: "docs",
}),
```

### Orama Cloud

托管版 Orama。浏览器用公开 API key 查询你的索引端点；`blume build` 则用 `ORAMA_PRIVATE_API_KEY` 把记录推送到索引。设置 `indexId` 以启用同步。

```ts blume.config.ts lineNumbers
import { oramaCloud } from "blume/search";

search: oramaCloud({
  endpoint: "https://cloud.orama.run/v1/indexes/your-index",
  apiKey: "YOUR_PUBLIC_API_KEY",
  indexId: "your-index-id", // 用于构建时同步
}),
```

### Typesense

自托管或云端 [Typesense](https://typesense.org)。浏览器用 search-only key 查询集合；`blume build` 会重建集合并用 `TYPESENSE_ADMIN_API_KEY` 导入文档。每次同步都会丢弃并重建集合，因此删除或重命名的页面不会作为陈旧结果残留 —— 如果你手动调整过集合设置，请在构建后重新应用。

```ts blume.config.ts lineNumbers
import { typesense } from "blume/search";

search: typesense({
  host: "xyz.a1.typesense.net",
  collection: "docs",
  apiKey: "YOUR_SEARCH_ONLY_KEY", // 公开
  // port + protocol 默认为 443 / https
}),
```

### Mixedbread [#mixedbread]

通过 [Mixedbread](https://www.mixedbread.com) 实现语义搜索。查询会经过生成的 `/api/search` 端点代理，该端点持有你的密钥，因此这个适配器**要求服务端输出**：需要来自 `blume/deploy` 的主机适配器，例如 `deployment: vercel()`（见[服务端渲染](/docs/deployment/)）。该端点读取 `MIXEDBREAD_API_KEY`。在构建中用 Mixedbread CLI 把内容同步到存储，例如 `mxbai vs sync <STORE_ID> ./content --ci`。

```ts blume.config.ts lineNumbers
import { mixedbread } from "blume/search";

search: mixedbread({
  storeId: "YOUR_STORE_ID",
}),
```

### 关闭搜索

```ts blume.config.ts lineNumbers
search: false,
```

如果你仍希望 `indexing` 对 MCP server 的索引生效，请在对象形式中改设 `provider: false`。

## 排除页面

只有可索引的页面才会被搜索。当页面在 frontmatter 中设置了 `search.exclude` 时，它会被排除在索引之外：

```yaml
search:
  exclude: true
```

[隐藏页面](/docs/content/navigation/)默认也会被排除。若仍想索引它们，请显式开启：

```ts blume.config.ts lineNumbers
search: {
  indexing: { includeHiddenPages: true },
},
```

---

# 主题
Source: https://blume.ndjp.net/docs/configuration/theming/
English: https://useblume.dev/docs/configuration/theming

Blume 的主题由 token 驱动，开箱即支持亮色与暗色模式。按你的需要多取或少取：常见情况改几个配置 token，用 `theme.css` 覆盖任意设计 token，或用 Tailwind 工具类定制组件。

## 配置 token

日常使用的旋钮位于配置中的 `theme` 下：

```ts blume.config.ts lineNumbers
theme: {
  accent: "teal",   // 命名预设或任意 CSS 颜色
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  fonts: {          // 自托管的 Google 字体
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}
```

### Accent [#accent]

强调色用于着色可交互元素和高亮元素 —— 步骤标记、选中的标签页、徽章、卡片悬停等等。使用命名预设或任意 CSS 颜色：

```ts blume.config.ts lineNumbers
theme: {
  accent: "#ff0066", // hex、oklch()、rgb()……任何 CSS 能理解的值
}
```

命名预设：`blue`（默认）、`green`、`orange`、`pink`、`purple`、`red` 和 `teal`。每个预设都有一个更深的亮色模式色阶和一个更浅的暗色模式色阶，因此强调色文字和按钮标签在两种模式下都满足 WCAG AA 对比度（4.5:1）。

字符串同时作用于两种颜色模式；若要[按模式设置不同强调色](#dark-mode-colors)，请传入一个对象。

位于强调色或操作色填充之上的文字，例如按钮标签或步骤编号，在该颜色上白色满足 AA 时为白色，否则为深色。浅色强调色无需任何额外配置即可获得深色标签。[`blume audit`](/docs/cli/audit/) 会用同样的标准检查自定义的强调色、操作色和背景色。

### Radius

`radius` 设置卡片、代码块、提示框和输入框共用的圆角大小 —— `none`、`sm`、`md`（默认）或 `lg`。

### 颜色模式

`mode` 设置初始配色方案：

- **`system`**（默认）—— 跟随读者的操作系统偏好
- **`light`** / **`dark`** —— 默认使用其中一种方案

页头始终有一个切换按钮供读者切换，并且他们的选择会跨次访问被记住。暗色模式通过 `<html>` 元素上的 `data-theme="dark"` 属性应用。

### 字体 [#fonts]

`fonts` 为三种用途设置字体：

- **`display`** —— 标题（`h1`–`h6`）
- **`body`** —— 正文、UI 和文章内容
- **`mono`** —— 代码块和行内代码

标题的字母间距（`-0.05em`）由主题本身提供，属于 display 级排版，因此你为 `display` 选的任何字体 —— 包括默认的 Inter 这类无衬线字体族 —— 在标题字号下都能正确呈现，而不依赖字体自带的字距设置。

每一项都默认使用精心挑选的 Google 字体，因此 Blume 开箱即看起来是经过设计的：

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: "inter",         // 默认
    body: "inter",            // 默认
    mono: "ibm-plex-mono",    // 默认
  },
}
```

只设置你想改的用途，其余保持默认值：

```ts blume.config.ts lineNumbers
theme: {
  fonts: { display: "geist" }, // body 与 mono 仍为 Inter / IBM Plex Mono
}
```

字体是**自托管**的：Blume 在构建时下载它们并从你自己的站点提供，因此运行期不会有指向 Google 的请求，也不会有布局偏移（Astro 会自动生成兜底的度量匹配字体）。

一个裸字符串就是下面精选集合中的 Google Fonts slug：

| 类别 | Slug |
| --- | --- |
| 无衬线 | `dm-sans` `figtree` `geist` `ibm-plex-sans` `inter` `inter-tight` `manrope` `open-sans` `plus-jakarta-sans` `roboto` `source-sans-3` `space-grotesk` `work-sans` |
| 衬线 | `ibm-plex-serif` `lora` `merriweather` `playfair-display` `source-serif-4` |
| 等宽 | `fira-code` `geist-mono` `ibm-plex-mono` `jetbrains-mono` `roboto-mono` `source-code-pro` `space-mono` |

#### 任意提供方的字体族

需要一个精选集合之外的字体族吗 —— 比如能覆盖非拉丁文字的那种？传入一个带有精确名称的对象。它同样是自托管并以相同方式优化的：

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}
```

- **`name`** —— 提供方列出的字体族精确名称。
- **`provider`** —— 字体族来自哪里：`google`（默认）、`fontsource`、`bunny` 或 `fontshare`。
- **`weights`** —— 要加载的字重，用数字或类似 `"100..900"` 的可变范围表示。默认为 `[400, 500, 600, 700]`。
- **`subsets`** —— 要加载的字符子集，使用提供方的名称（`latin`、`latin-ext`、`vietnamese`、`cyrillic`、`greek` 等）。默认为 `latin` 加上你配置的 locale 所需的部分 —— 见下文。
- **`fallback`** —— 字体加载期间以及缺少字形时使用的系统字体栈：`sans`、`serif` 或 `mono`。mono 用途默认为 `mono`，其余默认为 `sans`。

#### 子集与 locale

Google、Bunny 和 Fontsource 会把每个字体族拆成按文字系统划分的子集，只有你加载的子集才会得到一个 `@font-face`。Blume 从你的 [`i18n.locales`](/docs/content/i18n/) 推导出这个列表：包含越南语、波兰语、俄语或希腊语 locale 的站点，会在 `latin` 之外加载 `vietnamese`、`latin-ext`、`cyrillic` 或 `greek`，这样变音符号和非拉丁字母会用你选定的字体渲染，而不是回退到系统字体。没有 `i18n` 配置块、或只有拉丁-1 语言的站点只加载 `latin`。浏览器只在页面用到某个子集的字符时才下载它，预加载也遵循同一份列表。

在某个字体族上设置 `subsets` 可以覆盖推导出的列表 —— 例如单 locale 站点，但其内容仍需要该 locale 并不蕴含的文字系统：

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}
```

像 `inter` 这样的精选 slug 会遵循 locale 推导出的列表；这些字体族也可以用对象形式来固定子集。

#### 本地字体文件

对于你拥有的字体（或任何提供方都不提供的字体），把某个用途指向项目中的字体文件。每个变体会成为一个 `@font-face`：

```ts blume.config.ts lineNumbers
theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}
```

路径相对于项目根目录解析。`weight` 和 `style`（`normal`、`italic`、`oblique`）是可选的 —— 省略时 Astro 会从字体文件中读取。

:::note
当你显式设置 `theme.fonts` 时，你的 display 和 body 字体会自动为生成的 [Open Graph 卡片](/docs/discoverability/open-graph/)设置样式，让分享出去的链接与站点风格一致。非 Google 提供方的字体族在那里会被跳过（卡片渲染器只能从 Google Fonts 获取）；本地文件在任何地方都可用。
:::

想退回系统字体栈吗？直接在 [`theme.css`](#themecss)中覆盖 `--blume-font-*` token。

### 暗色模式配色 [#dark-mode-colors]

`accent` 和 `background` 遵循同一条规则：字符串同时作用于两种颜色模式，`{ light, dark }` 对象则分别设置每种模式：

```ts blume.config.ts lineNumbers
theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}
```

每种颜色都可以填命名预设或任意 CSS 颜色。对于 `background`（以及 `backgroundImage`），两个键都可以省略其中一个以只覆盖单一模式 —— `background: { dark: "#0a0a0a" }` 会保留默认的亮色背景。

### 操作色

`action` 是主行动召唤（CTA）和 `action` Tailwind 工具类（`bg-action`、`text-action`）使用的次要强调色。它默认为你的 `accent`：

```ts blume.config.ts
theme: {
  action: "#ff0066",
}
```

### 背景图

用 `backgroundImage` 设置内容背后的背景图 —— 一个 URL 或 `public/` 下的路径。和颜色一样，字符串同时作用于两种模式，`{ light, dark }` 对象则分别设置每种模式的图片：

```ts blume.config.ts lineNumbers
theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}
```

## theme.css [#themecss]

在项目根目录放一个 `theme.css`，即可覆盖任意设计 token。它是层叠中的最后一层，因此优先级高于默认值和配置 token：

```css theme.css lineNumbers
:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}
```

在 `:root` 下设置 token 用于亮色模式，在 `:root[data-theme="dark"]` 下设置用于暗色模式。颜色 token 在暗色选择器处以更高优先级声明了各自独立的内置暗色值，因此只写 `:root` 而覆盖 `--blume-accent`、`--blume-background` 等只会作用于亮色模式 —— 若两种模式都要改变，请同时声明暗色块。

`theme.css` 会被内联到站点的 Tailwind 入口中，因此 Tailwind 指令在它里面同样有效。monorepo 中最需要知道的是 `@source`：Blume 会扫描你的项目以寻找工具类，而一个从同级 workspace 包引入组件的页面需要那个包也被扫描。相对于 `theme.css` 指定它 —— 这是 Tailwind 的标准写法 —— Blume 会把这个路径带入生成的样式表：

```css theme.css lineNumbers
@source "../../packages/ui/src";
```

### 设计 token

| Token | 控制项 |
| --- | --- |
| `--blume-background` | 页面背景 |
| `--blume-foreground` | 正文文字 |
| `--blume-muted` | 低对比度的表面 —— 提示框、表头 |
| `--blume-muted-foreground` | 次要文字 |
| `--blume-border` | 边框和分隔线 |
| `--blume-accent` | 强调色 |
| `--blume-accent-foreground` | 强调色背景上的文字和图标 |
| `--blume-action` | 次要强调色（默认为 accent） |
| `--blume-action-foreground` | 操作色背景上的文字和图标（默认为强调色前景色） |
| `--blume-code-background` | 代码块底色 |
| `--blume-code-highlight`, `--blume-code-highlight-border` | 高亮代码行的背景和左侧标线（`// [!code highlight]` 或 `{1,4-5}` 区间） |
| `--blume-code-add`, `--blume-code-add-border` | 新增行的背景和左侧标线（`// [!code ++]`） |
| `--blume-code-remove`, `--blume-code-remove-border` | 删除行的背景和左侧标线（`// [!code --]`） |
| `--blume-code-word`, `--blume-code-word-border` | 高亮词的背景和外框（`// [!code word:…]`） |
| `--blume-content-width` | 正文栏最大宽度 —— 文章、面包屑、目录、反馈和分页（默认 `42rem`） |
| `--blume-radius` | 圆角半径 |
| `--blume-font-display` | 标题字体 |
| `--blume-font-body` | 正文 / UI 字体 |
| `--blume-font-mono` | 代码字体 |

把任意 `--blume-font-*` token 设为一个字体栈，即可使用精选列表之外的字体，或回退到系统字体栈：

```css theme.css lineNumbers
:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

## Tailwind 工具类

Blume 的主题内部基于 Tailwind v4 构建，你项目中的 `.astro`、`.tsx` 和 `.jsx` 文件也会被扫描 —— 因此你可以用工具类给自定义组件和页面设置样式，无需任何 Tailwind 配置。每一个 token 都以工具类形式暴露，因此你的组件会自动跟随主题：

| Token                       | 工具类                       |
| --------------------------- | -------------------------- |
| `--blume-background`        | `bg-background`            |
| `--blume-foreground`        | `text-foreground`          |
| `--blume-muted`             | `bg-muted`                 |
| `--blume-muted-foreground`  | `text-muted-foreground`    |
| `--blume-border`            | `border-border`            |
| `--blume-accent`            | `bg-accent`, `text-accent` |
| `--blume-accent-foreground` | `text-accent-foreground`   |
| `--blume-action`            | `bg-action`, `text-action` |
| `--blume-action-foreground` | `text-action-foreground`   |
| `--blume-code-background`   | `bg-code`                  |
| `--blume-content-width`     | `max-w-content`            |
| `--blume-radius`            | `rounded-blume`            |
| `--blume-font-display`      | `font-display`             |
| `--blume-font-body`         | `font-sans`                |
| `--blume-font-mono`         | `font-mono`                |

## 层叠顺序

样式分三层解析，每一层都覆盖前一层：

1. **基础层**

    Blume 的样式重置、默认 token 和组件样式。

2. **配置 token**

    `theme` 中的 `--blume-accent`、`--blume-radius` 以及 `--blume-font-*` token。

3. **theme.css**

    你的 token 覆盖 —— 最终决定权。

---

# 内容
Source: https://blume.ndjp.net/docs/content/
English: https://useblume.dev/docs/content

你的文档不过是一个装着 Markdown 和 MDX 文件的文件夹。Blume 会把每个文件变成一个页面 —— 路由、导航和元数据都从文件系统推断，因此没有需要保持同步的清单文件。

内容放在你的**内容根目录**下（默认是 `docs/`；用 [`blume.config.ts`](/docs/configuration/) 里的 `content.root` 修改）。

## Markdown 和 MDX

Blume 会渲染两类文件：

- **`.md`** —— 面向纯散文的 Markdown：GFM、frontmatter、智能标点，以及上标和下标。
- **`.mdx`** —— `.md` 拥有的一切，外加[组件](/docs/content/components/)以及 MDX 专有的[指令、包安装和数学公式](/docs/content/syntax/)。

页面只是散文时用 `.md`，需要组件或指令时用 `.mdx`。切换只需重命名文件。

## 文件与路由 [#files-and-routes]

每个文件按其在内容根目录下的路径映射到一个路由：

| 文件 | 路由 |
| --- | --- |
| `docs/index.mdx` | `/` |
| `docs/quickstart.mdx` | `/quickstart` |
| `docs/guides/theming.mdx` | `/guides/theming` |
| `docs/guides/index.mdx` | `/guides` |

嵌套文件夹会变成嵌套路由，而文件夹里的 `index.mdx` 会成为该文件夹自己的页面。

会破坏页面 URL 的字符 —— `#`、`?`、`%` 和 `:` —— 会从路由中被去掉，所以 `100%.mdx` 会发布在 `/100`。彻底不要在文件名和文件夹名里使用 `#` 和 `?`：Astro 的内容加载器读不了这类文件，Blume 会把它报告为错误并排除在站点之外。把 `sdks/c#.mdx` 改名为 `sdks/c.mdx`，它就会发布在 `/sdks/c` —— 反正这些字符在原本的路由里也会被去掉。

## 用数字前缀排序 [#ordering-with-numeric-prefixes]

给文件或文件夹加上一个数字前缀，再跟一个 `-`、`_` 或 `.`，就能控制它在侧边栏里的顺序。前缀会从 URL 中去掉，所以你可以重排页面而不弄坏链接：

```txt
01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation
```

名称开头的版本号或 ISO 日期是名称的一部分，而不是顺序标记：`1.2.0.mdx` 的路由是 `/1.2.0`，`2024-01-05-launch.mdx` 的路由是 `/2024-01-05-launch`。只有文件和文件夹名会去掉前缀（Obsidian 仓库里的笔记按文件算）。frontmatter 中的 `slug`，以及来自[内容源](/docs/content/sources/)（比如某个 CMS 或 GitHub Releases）的页面，则保留它们被赋予的名称。

排序有多层规则 —— 完整的优先级见[导航](/docs/content/navigation/)。

## 分组文件夹 [#group-folders]

用括号把文件夹名包起来，可以让它的页面在侧边栏里归为一组，同时**不会**新增 URL 段：

```txt
docs/(internal)/security.mdx  ->  /security
```

这些页面共享一个「Internal」侧边栏分组，但 URL 依然是扁平的、不带括号。分组文件夹和普通文件夹一样可以带[数字前缀](#ordering-with-numeric-prefixes)，写在括号内或括号外都可以：`(01-internal)` 和 `01-(internal)` 都会排在最前，路由行为也与 `(internal)` 相同。

## 草稿

把一个页面标记为草稿，可以让它不进入生产构建，同时仍能在 `blume dev` 里预览：

```yaml lineNumbers
---
title: 编写中
draft: true
---
```

`blume build` 会跳过草稿；`blume dev` 会渲染它们，方便你公开地边写边看。

## 内容类型

每个页面都有一个**类型**，通过 `type` frontmatter 字段设置（默认 `doc`）。类型让 Blume 能区别对待成组的页面 —— 最重要的是，`blog` 和 `changelog` 页面会被收集进[订阅源](#feeds)。

```yaml lineNumbers
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: 新功能
---
```

类型与文件所在的位置无关，但按惯例，博客文章放在 `blog/` 下，更新日志条目放在 `changelog/` 下。两者都会自动获得一个 RSS 订阅源，更新日志条目还会被收集进自动生成的 [`/changelog` 时间线](/docs/advanced/changelog/)。如何撰写这两类内容，分别见[博客](/docs/advanced/blog/)和[更新日志](/docs/advanced/changelog/)。

## 订阅源 [#feeds]

Blume 会为 [`seo.rss.types`](/docs/discoverability/rss/) 中列出的每一种内容类型自动生成 RSS 订阅源 —— 默认是 `blog` 和 `changelog` —— 只要它至少有一个页面。订阅源提供在 `/<type>/rss.xml`：

| 类型 | 订阅源 |
| --- | --- |
| `blog` | `/blog/rss.xml` |
| `changelog` | `/changelog/rss.xml` |

给每个条目一个 `date`，这样条目会按最新在前排序，并带上 `pubDate`。不加引号的 YAML 日期也没问题 —— Blume 会做归一化：

```yaml lineNumbers
---
title: Blume 登场
type: blog
date: 2026-06-22
description: 我们为什么打造一个 markdown 优先的文档框架。
---
```

订阅源需要一个绝对的站点 URL，所以请设置 [`deployment.site`](/docs/deployment/)。Blume 会给每个页面加上 `<link rel="alternate">` 标签，让浏览器和订阅阅读器自动发现它们。如何撰写这两种内容类型，分别见[博客](/docs/advanced/blog/)和[更新日志](/docs/advanced/changelog/)。

## 本页导航

每个页面都会自动获得一份目录，由它的标题构建而成。在宽屏上它位于内容旁边的吸顶侧边栏中；在较窄的屏幕上它会折叠成页面上方的一个**本页导航**面板。滚动时，你正在阅读的那一节对应的条目会高亮，因此在长页面里你始终知道自己在哪里。

Blume 会把每个标题转成锚点 slug，因此每个条目都直接链接到它对应的小节 —— 你也可以在 URL 后追加标题的 slug 来深链接到任意标题（`.../my-page#getting-started`）。

默认情况下目录会列出你的 `##` 和 `###` 标题（H2 和 H3）；设置 [`toc`](/docs/configuration/) 可以改变标题范围或关闭目录。某个页面在该范围内没有标题时，它就只是没有目录而已。

## 接下来看什么

**[Frontmatter](/docs/content/frontmatter/)**

页面元数据：标题、描述、侧边栏、SEO 和搜索。

**[语法](/docs/content/syntax/)**

你能写下的每一项 Markdown 和 MDX 特性。

**[组件](/docs/content/components/)**

任意 MDX 页面里可用的 JSX 组件。

**[导航](/docs/content/navigation/)**

规划侧边栏、排序和标签页。

**[文件夹 meta](/docs/content/meta/)**

用一个 `meta.ts` 文件配置侧边栏分组。

---

# 组件
Source: https://blume.ndjp.net/docs/content/components/
English: https://useblume.dev/docs/content/components

Blume 自带一套无障碍、可换主题的组件，在任何 `.mdx` 页面上都能用，且**无需 import**。下面每个组件都配有实时预览和它的源码。这些组件是原生的、不依赖 React；只有当你的项目用到 React 时才会启用 React——项目里出现任何 `.tsx` 或 `.jsx` 文件、一个 React [交互岛](/docs/content/islands/)、[`<Component>`](#component) 示例，或[组件覆盖](/docs/configuration/customization/)——或者启用了[助手](/docs/configuration/assistant/)时。

## Card 与 CardGroup

卡片用一个图标、标题和一段简短说明把读者引向某个目的地。用 `CardGroup` 把它们排成响应式网格。落地页、章节索引和“下一步”这类地方都适合用它们——凡是引导读者继续往前走的地方。

**[快速上手](/docs/quickstart/)**

安装 Blume 并发布你的第一个页面。

**[组件](/docs/content/components/)**

浏览组件库。

```astro lineNumbers
<CardGroup cols={2}>
  <Card title="Quickstart" href="/docs/quickstart" icon="rocket">
    Install Blume and ship your first page.
  </Card>
  <Card title="Components" href="/docs/content/components" icon="folder">
    Browse the component library.
  </Card>
</CardGroup>
```

`Card` 接受 `title`、可选的 `href`（不传就是不可点击的卡片），以及取自 Blume 内置图标集的 `icon`。`CardGroup` 接受 `cols`（默认 `2`）。

卡片还接受 `img`（横跨顶部的图片，或配合 `horizontal` 从 `sm` 断点起与文字并排）、`cta`（文字下方用强调色显示的一行行动号召）、`arrow`（标题与 CTA 之后的一个箭头；默认只对外链显示）、`type`（像提示框那样给卡片着色并挑选匹配的图标：`note`、`info`、`tip`、`check`、`warning` 或 `danger`），以及 `color`（给图标用的任意 CSS 颜色）。

## Steps [#steps]

编号纵向序列，用来放有先后顺序的说明——安装步骤、配置流程，以及顺序要紧的教程。每个 `Step` 接受一个 `title` 和可选的 `icon`，图标会显示在标记里取代编号。`Steps` 上的 `titleSize` 用来设定步骤标题的字号，像正文一样（`p`，默认值）或像 `h4`、`h3`、`h2` 标题一样。

1. **安装 Blume**

    把这个包加入你的项目。

2. **编写页面**

    在你的内容文件夹里放一个 `.mdx` 文件。

3. **发布上线**

    运行 `blume build` 并部署 `dist/`。

```astro lineNumbers
<Steps>
  <Step title="Install Blume">Add the package to your project.</Step>
  <Step title="Write a page">
    Drop an `.mdx` file into your content folder.
  </Step>
  <Step title="Ship it">Run `blume build` and deploy `dist/`.</Step>
</Steps>
```

## Tabs [#tabs]

在原地切换等价的同类内容——不同语言的变体、各操作系统的命令，或不同的实现路线——而不必把一切都堆在页面上。每个 `Tab` 接受一个 `title`。

**macOS**

用 Homebrew 安装这套工具链。

**Windows**

用 winget 安装这套工具链。

```astro lineNumbers
<Tabs>
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

加上 `inline` 可以渲染成无边框样式——一条贯穿全宽的分隔线上的标签条，内容像散文一样在其下流动——而不是带边框的方框。加上 `param` 可以把当前标签同步到 URL 查询参数而不是 hash，这样选中项就能分享：一个以 `?install=windows` 结尾的链接会打开 Windows 标签。每个分组同步到各自的 `param`，因此你可以在同一个页面上使用多个彼此独立、可深链的分组。

标题相同的标签会一起切换——在一个分组里选了“macOS”，所有带 macOS 标签的分组都会跟着变。加上 `syncKey` 可以限定这种同步范围：只有共享同一个 key 的分组才会一起切换，这样碰巧标题相同的无关分组仍保持独立；或者用 `sync={false}` 让某个分组完全不参与。

当前标签会写入 URL hash，因此链接会打开对应标签；传 `hash={false}` 则不去动 URL。当没有链接或同步选中项决定初始标签时，`defaultTabIndex` 决定先打开哪个标签（从零开始计数，默认 `0`）。`dropdown` 会把标签条换成下拉菜单（仅在带边框的布局中生效），`borderBottom={false}` 去掉标签条下方那条分隔线，每个 `Tab` 还接受一个显示在标题之前的 `icon`。

**macOS**

用 Homebrew 安装这套工具链。

**Windows**

用 winget 安装这套工具链。

```astro lineNumbers
<Tabs inline param="install">
  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
  <Tab title="Windows">Use winget to install the toolchain.</Tab>
</Tabs>
```

## View

用 `<View>` 块为多个受众写同一页内容，比如使用不同编程语言或框架的读者。每个不同的 `title` 都会变成页面内容上方选择器里的一个选项，并且只显示被选中视图的块。目录也会随之变化：隐藏视图里的标题会从目录中消失。`<View>` 之外的散文在每个视图里都会显示，共享同一标题的块会一起显示或隐藏，因此同一页可以交替出现共享区块和视图专属区块。`icon` 会显示在选择器里视图名称的旁边。

````mdx lineNumbers
Everyone reads this paragraph.

<View title="JavaScript" icon="braces">

## Install the client

```bash
npm install @acme/commerce
```

</View>

<View title="Python" icon="terminal">

## Install the client

```bash
pip install acme-commerce
```

</View>
````

在读者另选一个视图之前，显示的是第一个视图。Blume 会跨页面记住用视图写法页面上的这个选择，并把它以 `?view=Python` 写入 URL，因此链接会打开同一个视图。指向视图内部某个标题的链接会打开该视图。当页面大部分内容都随选择变化时用 `<View>`，只有一小部分变化时用 [Tabs](#tabs)。面向 agent 的 Markdown 会包含每个视图，各自归在自己的名字之下。

## Badge

一个小小的行内标签，用来标注状态或元数据——版本标签、“新”或“beta”标记、稳定程度。`variant` 用来让颜色贴合语义。

### 默认

不带特别强调的中性元数据。

稳定

```astro
<Badge>Stable</Badge>
```

### 强调

借助主题强调色吸引视线——适合“新”或精选标记。

新增

```astro
<Badge variant="accent">New</Badge>
```

### 成功

正面或通过的状态。

通过

```astro
<Badge variant="success">Passing</Badge>
```

### 警告

需要谨慎使用的东西，比如实验性功能。

测试版

```astro
<Badge variant="warning">Beta</Badge>
```

### 危险

负面或破坏性变更的状态，比如已废弃。

已废弃

```astro
<Badge variant="danger">Deprecated</Badge>
```

### 颜色、形状与尺寸

除 `variant` 之外，徽章还接受 `color`——一个具名色相（`blue`、`green`、`orange`、`purple`、`red`、`teal`、`violet`、`yellow`）、一个中性色（`gray`、`surface`、`white`、`surface-destructive` 或 `white-destructive`），或一个十六进制值——以及 `shape`（`rounded`，默认值，或 `pill`）、`size`（默认 `xs`、`sm`、`md`，或 `lg`）、用来改成描边而非填充的 `stroke`、显示在标签之前的 `icon`、悬停文字 `tooltip`，以及把它变暗的 `disabled`。

带图标和描边的紫色药丸标签：Preview

```astro
<Badge color="purple" icon="sparkles" shape="pill" stroke>Preview</Badge>
```

## Icon [#icon]

按名字渲染图标——卡片、步骤、标签页和侧边栏条目用的是同一个 `icon` 属性。名字来自 [Lucide](https://lucide.dev/icons)，全小写并用连字符分隔（`rocket`、`gauge`、`book-open`）。



```astro
<Icon icon="rocket" size={20} />
```

Blume 只认 Lucide——裸名字会解析到 Lucide，你也可以给名字加上 `lucide:` 前缀（`lucide:rocket`），以和其它图标输入方式保持一致。`size` 设置像素尺寸（默认 `16`），`color` 给它着色（任意 CSS 颜色，默认 `currentColor`）。传入原始的 `<svg>` 字符串、图片 URL 或本地图片路径来代替名字，就能渲染你自己的图形；再加一个 `label` 让辅助技术能够识别它——没有 `label` 时该图标被视为装饰性的。

图标在构建期解析并内联成零 JS 的 SVG——运行时不会请求任何资源。

## 文件树 [#file-tree]

用来说明一个项目或文件夹的布局。把一个普通的 Markdown 列表包起来，Blume 就会把它渲染成树状——在配置类文档里讲解结构时很顺手。

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

```astro lineNumbers
<FileTree>

- docs/
  - index.mdx
  - guides/
    - configuration.mdx
- blume.config.ts

</FileTree>
```

## Accordion [#accordion]

把相关的折叠块堆在一个带分隔线的边框容器里——常见问题、可选步骤或长示例。每个子项是一个 `AccordionItem`（`title`、可选的 `icon`、`description`、`defaultOpen`）。若只想单独做一个折叠块，用 [Expandable](#expandable)。

**支持 MDX 吗？**

支持——每个页面都可以是 `.md` 或 `.mdx`。

**主题可定制吗？**

可以，通过 Tailwind v4 设计令牌和你自己的 `theme.css`。

```astro lineNumbers
<Accordion>
  <AccordionItem title="Does it support MDX?">
    Yes — every page can be `.md` or `.mdx`.
  </AccordionItem>
  <AccordionItem title="Is the theme customizable?">
    Yes, via Tailwind v4 tokens and your own `theme.css`.
  </AccordionItem>
</Accordion>
```

## Expandable [#expandable]

一个轻量的行内折叠块，用来放嵌套的细节——展开某个字段的子属性，或一段可选的补充说明。`title` 是切换按钮上的文字（默认是“显示更多”）；设 `defaultOpen` 可让它初始展开。

**显示高级选项**

这些设置是可选的，很少需要改动。

```astro
<Expandable title="Show advanced options">
  These settings are optional and rarely need changing.
</Expandable>
```

## Columns

把卡片或区块排成等宽列的响应式网格，在移动端自动重排。`Columns` 接受 `cols`；每个单元格用一个 `Column` 包起来。

**快速**

基于 Astro 和 Vite 构建。

**可定制主题**

Tailwind v4 设计令牌。

```astro lineNumbers
<Columns cols={2}>
  <Column>
    <Card title="Fast" icon="rocket">
      Built on Astro and Vite.
    </Card>
  </Column>
  <Column>
    <Card title="Themeable" icon="sun">
      Tailwind v4 design tokens.
    </Card>
  </Column>
</Columns>
```

## CodeGroup [#codegroup]

把几个代码块归到一个带标签页的切换器里——每种语言或每个文件一个标签页。标签文字就是每个代码块的标题（语言之后的那部分文字），分组的复制按钮位于标签栏上，复制的是当前显示的那个代码块。加上 `dropdown` 可以改用菜单而不是标签栏来切换。

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

````astro
<CodeGroup>

```ts TypeScript
export const greet = (name: string) => `Hello, ${name}`;
```

```python Python
def greet(name: str) -> str:
    return f"Hello, {name}"
```

```rust Rust
fn greet(name: &str) -> String {
    format!("Hello, {name}")
}
```

</CodeGroup>
````

## Frame

把一张图片或任意视觉内容包进居中的边框里，并可选地加上 `caption`（以 Markdown 渲染）和 `hint`。

Frame 会居中并为视觉内容添加图注。

<svg
  width="160"
  height="72"
  viewBox="0 0 160 72"
  role="img"
  aria-label="Sample frame"
>
  <rect width="160" height="72" rx="8" fill="#3b82f6" />
</svg>

一幅**带边框**的插图。

```astro lineNumbers
<Frame
  caption="A **framed** illustration."
  hint="Frames center and caption visuals."
>
  <img src="/screenshot.png" alt="Product screenshot" />
</Frame>
```

## YouTube

把 YouTube 视频嵌进一个响应式的、对隐私友好的（`youtube-nocookie.com`）16:9 画面中，并且不加载任何客户端 JavaScript。传入视频 `id` 或完整的 `url`，再加上可选的 `title`（用于无障碍）和以秒为单位的 `start` 起始时间。

[Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

```astro lineNumbers
<YouTube id="aqz-KE-bpKQ" title="Big Buck Bunny" />
<YouTube url="https://youtu.be/aqz-KE-bpKQ" start={30} />
```

## Color

显示色板并提供可复制的十六进制值——适合记录一套配色或品牌色。用 `variant="compact"` 做色板列表，或用 `variant="table"` 配合 `Color.Row` 把它们分组。每个 `Color.Item` 接受一个 `name` 和一个 `value`（十六进制字符串，或针对感知主题的 `{ light, dark }`）；感知主题的色板会复制读者当前所看主题对应的那个值。

- **blue-500**：`#3B82F6`

- **green-500**：`#16A34A`

- **background**：`#FFFFFF`（浅色）、`#0A0A0A`（深色）

```astro lineNumbers
<Color variant="compact">
  <Color.Item name="blue-500" value="#3B82F6" />
  <Color.Item name="green-500" value="#16A34A" />
  <Color.Item name="background" value={{ light: "#FFFFFF", dark: "#0A0A0A" }} />
</Color>
```

## Tree

渲染带可展开文件夹的层级文件/文件夹结构。（想要一个由列表驱动的简版，见[文件树](#file-tree)；`Tree` 则提供按文件夹的控制。）使用 `Tree.Folder`（`name`、可选的 `defaultOpen`、`openable`）和 `Tree.File`（`name`）。

- src/
  - index.ts
  - components/
    - Button.tsx
- blume.config.ts

```astro lineNumbers
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="index.ts" />
    <Tree.Folder name="components">
      <Tree.File name="Button.tsx" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="blume.config.ts" />
</Tree>
```

## Panel

一个带标题的容器，用来放补充性的旁支内容。`title` 是可选的。

**需要知道**

Panel 用来承载补充细节，不会打断主线流程。

```astro
<Panel title="Good to know">
  Panels hold supporting detail without interrupting the main flow.
</Panel>
```

## Tooltip

让行内术语在悬停时显示定义或提示。`tip` 是悬停文字；还可以加一个可选的 `headline`，以及用于后续链接的 `cta` + `href`。

把鼠标悬停在 **API**（API：一组软件用来通信的协议。）这个词上可以了解更多。

```astro
Hover the <Tooltip tip="A set of protocols software uses to communicate." headline="API" cta="Read the guide" href="/docs/quickstart">API</Tooltip> term.
```

## Tile

一个可点击的预览，用视觉元素——一个图标或一张图片——领起，上面配标题与描述。适合画廊和作品展示。接受 `title`、`description` 和 `href`；子元素就是那个视觉元素。

**[快速上手](/docs/quickstart/)**

几分钟内发布你的第一个页面。

```astro
<Tile
  title="Quickstart"
  description="Ship your first page in minutes."
  href="/docs/quickstart"
>
  <Icon icon="rocket" size={28} />
</Tile>
```

## Prompt [#prompt]

一行内容，由标签和复制按钮组成。`description`（Markdown）是可见的标签；正文则是提示词本身——默认隐藏，按下 **Copy prompt** 按钮时连同其中的链接、列表和代码一起以 Markdown 形式复制到剪贴板。`actions` 控制按钮（例如 `["copy", "cursor"]`）。

**让模型为某个接口编写文档。**

> 为 POST /v1/pets 接口编写参考文档。

```astro
<Prompt
  description="Ask the model to **document** an endpoint."
  actions={["copy"]}
>
  Write reference docs for the POST /v1/pets endpoint.
</Prompt>
```

## Visibility [#visibility]

按受众显示或隐藏内容。`for="web"` 只在站点上渲染；`for="agents"` 面向 AI agent 读取的 Markdown（`llms-full.txt` 以及每个页面的 `.md` 镜像）。

```astro
<Visibility for="web">Shown on the site only.</Visibility>
<Visibility for="agents">Shown only in the generated Markdown.</Visibility>
```

## 类型表格

用来记录某个对象的属性——它的 props、类型和默认值——的表格。用 `TypeTable` 手工写各行，或用 `AutoTypeTable` 直接从一个 TypeScript 接口或类型别名生成。

### 类型表格

一个 **Prop / 类型**网格，每一行展开后可看到它的描述与细节。传入一个以属性名为键的 `type` 映射；每个条目接受 `type`，以及可选的 `description`、`default`、`required` 标志、`typeDescription` 和 `typeDescriptionLink`。可选属性（未设 `required`）会在名字后显示一个 `?`。

| 属性 | 类型 | 默认值 | 描述 |
| - | - | - | - |
| `label` | `string` | - | 按钮上可见的标签文字。 |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | 视觉样式。 |
| `disabled?` | `boolean` | - | |

```astro lineNumbers
<TypeTable
  type={{
    label: {
      type: "string",
      required: true,
      description: "The button's visible label.",
    },
    variant: {
      type: '"primary" | "ghost"',
      default: '"primary"',
      description: "Visual style.",
    },
    disabled: { type: "boolean" },
  }}
/>
```

### 自动类型表格

从一个 TypeScript 类型生成类型表格，让文档始终与源码保持同步。用 `path`（相对于项目根目录解析）和类型 `name` 指向 `AutoTypeTable`。描述来自 JSDoc 注释，默认值来自 `@default` 标签，可选属性（`?`）也会相应标注。

```astro
<AutoTypeTable path="./src/button.ts" name="ButtonProps" />
```

你也可以用 `type` 直接内联传入类型，而不用 `path`——小例子这样很方便：

| 属性 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `label` | `string` | | 按钮上可见的标签文字。 |
| `variant?` | `"primary" \| "ghost"` | `"primary"` | 视觉样式。 |
| `disabled?` | `boolean` | | 禁用交互。 |

```astro lineNumbers
<AutoTypeTable
  name="ButtonProps"
  type={`
export interface ButtonProps {
  /** The button's visible label. */
  label: string;
  /**
   * Visual style.
   * @default "primary"
   */
  variant?: "primary" | "ghost";
  /** Disable interaction. */
  disabled?: boolean;
}
`}
/>
```

## API 字段 [#api-fields]

用来逐个手工记录接口字段的表格行，样式与生成的 [OpenAPI 参考](/docs/references/openapi/)一致。`ParamField` 表示一个请求参数，由说明它去向的属性命名：`path`、`query`、`header` 或 `body`。`ResponseField` 表示响应中的一个字段，由 `name` 命名。两者都接受 `type`、`required`、`deprecated` 和一个 `default`，并以内容作为描述；`ResponseField` 还接受用在名字前后做标注的 `pre` 与 `post`。

- **`userId`** · path · `string` · 必填

  用户的 ID。

- **`limit`** · query · `integer` · 默认 `20`

  返回多少条结果，最多 100 条。

- **`plan`** · beta · `string`

  用户的套餐。

```mdx lineNumbers
<ParamField path="userId" type="string" required>
  The user's ID.
</ParamField>

<ParamField query="limit" type="integer" default={20}>
  How many results to return, up to 100.
</ParamField>

<ResponseField name="plan" type="string" post={["beta"]}>
  The user's plan.
</ResponseField>
```

可以用一个 [`Expandable`](#expandable) 把对象的字段嵌进它的描述里：

```mdx lineNumbers
<ResponseField name="address" type="object">
  Where the order ships.

  <Expandable title="properties">
    <ResponseField name="city" type="string" required>
      City name.
    </ResponseField>
  </Expandable>
</ResponseField>
```

在带 `api` frontmatter 的页面上，这些 `ParamField` 还会用来生成页面的 Try it 面板和请求示例：见[手写 API 页面](/docs/references/api-pages/)。这些字段沿用与 Mintlify 相同的名字和属性，因此为它写的页面可以直接照原样渲染。页面的 Markdown 副本会列出每个字段及其类型与标志。

### 请求与响应示例 [#request-and-response-examples]

`RequestExample` 和 `ResponseExample` 用来承载代码块，每个带标题的围栏各占一个标签页（`dropdown` 会切换成语言菜单，和 [`CodeGroup`](#codegroup) 一样）。在宽屏上它们会固定到页面旁边的一列里，请求在上、响应在下，并在读者滚动浏览字段时保持在视野中，就像 OpenAPI 操作的示例那样；页面会收起目录来腾出空间。在窄屏上它们则跟随页面内容。

````mdx lineNumbers
<RequestExample>

```bash cURL
curl --request POST https://api.acme.dev/v1/users \
  --header "Authorization: Bearer $ACME_TOKEN" \
  --data '{ "email": "ada@example.com" }'
```

```ts title="Acme SDK"
await acme.users.create({ email: "ada@example.com" });
```

</RequestExample>

<ResponseExample>

```json 201
{ "id": "usr_8f2k", "status": "invited" }
```

</ResponseExample>
````

把它们写在页面顶层的任意位置即可；每个都会移到那一列。嵌套在另一个组件里（比如某个 `Tab` 中）的则会留在书写处不动。

## GitHub 信息

一张指向 GitHub 仓库的卡片，带有 star 和 fork 数量。这些数字在构建期获取——没有客户端 JavaScript——因此显示的是你上次构建时的数字，而非实时数据；即使 API 不可达，卡片仍会在没有这些数字的情况下渲染。传入 `owner` 和 `repo`，或省略它们以使用 `blume.config` 中的仓库。设置 `GITHUB_TOKEN` 环境变量可以提高 API 速率限制；`token` 属性能为某一张卡片覆盖该变量，但环境变量能让你不必把 token 写进内容里。

卡片会从 [`github.host`](/docs/configuration/) 读取实例，因此在 Enterprise 托管的站点上，显式的 `owner`/`repo` 也会指向那个实例。传入 `host` 可以把某一张卡片指向别处——比如从 Enterprise 站点指向一个公开项目；REST 基址会以与从 `github.host` 相同的方式推导出来。

[haydenbleasel/blume](https://github.com/haydenbleasel/blume)

```astro lineNumbers
<!-- 使用 blume.config 中的仓库 -->
<GithubInfo />

<!-- 或指向任意仓库 -->
<GithubInfo owner="haydenbleasel" repo="blume" />

<!-- 或指向另一个实例上的仓库 -->
<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
```

## Component [#component]

`Component` 会把项目 `examples/` 目录下的一个示例文件渲染成实时预览，并排展示带高亮的源码，用标签页切换。用 `path` 指向一个文件——它在 `examples/` 下的位置，不带扩展名（所以 `examples/counter.tsx` 的 `path="counter"`）。React、Vue、Svelte 和 Astro 示例都受支持；框架示例会水合，Astro 示例则静态渲染。预览与代码由同一个文件保持同步。

预览渲染在一个隔离的框里，文档样式完全影响不到它——不会有正文边距、排版或主题外壳渗进你的组件。这个框会带上 Tailwind（preflight 以及从你的项目和示例目录扫描到的工具类）、Blume 的设计令牌（因此 `bg-background` 这类类名默认跟随站点配色），并实时跟随站点的浅色/深色切换。面板会按渲染出的示例自适应大小——示例在加载后变大或变小时仍会继续跟踪——Preview 与 Code 两个标签共享同一高度，因此来回切换不会让页面跳动。

若想用你自己的设计系统来美化预览——比如 shadcn 变量——把 `examples.css` 指向一个样式表即可。它会在 Blume 默认样式之后注入每个预览框，因此你的令牌优先生效。不要在里面 `@import "tailwindcss"`；这个框已经提供了 Tailwind。深色模式覆盖既可以用 `.dark`，也可以用 `[data-theme="dark"]`：

```ts
// blume.config.ts
export default defineConfig({
  examples: { css: "examples/theme.css" },
});
```

```css
/* examples/theme.css */
:root {
  --primary: oklch(0.6 0.2 260);
}

.dark {
  --primary: oklch(0.75 0.15 260);
}

@theme inline {
  --color-primary: var(--primary);
}
```

目录也是可配置的——当你的示例放在别处时（比如某种 registry 布局），设置 `source`（或使用字符串简写 `examples: "..."`）。`path` 始终相对于它：

```ts
// blume.config.ts
export default defineConfig({
  examples: "registry/files-sdk",
});
```

```astro
<!-- registry/files-sdk/file-list/basic.tsx -->
<Component path="file-list/basic" />
```

`examples` 也可以是一个 glob（任何含 `*`、`?`、`[]`、`{}` 或 `!` 的模式）。只有匹配的文件会被发现，而 `path` 相对于该 glob 的静态前缀（第一个通配符之前的部分）。这适用于把每个组件的源码与其示例放在一起的 registry——只指向示例即可，这样没有默认导出、无法预览的源码就不会被一并扫进来：

```ts
// blume.config.ts
export default defineConfig({
  // registry/files-sdk/file-list/file-list.tsx — 源码，不纳入
  // registry/files-sdk/file-list/examples/basic.tsx — 被发现
  examples: "registry/files-sdk/**/examples/*",
});
```

```astro
<!-- 相对于 registry/files-sdk 作为键 -->
<Component path="file-list/examples/basic" />
```

在 monorepo 中，示例所导入的组件通常位于同级的 workspace 包中。Tailwind 的 `@source` 扫描的是文件而不是 import：Blume 会扫描你的项目和 `examples` 目录（无论 `source` 指向哪里，哪怕在项目之外），因此只在这个同级包里用到的类，在你把该包加入扫描范围之前不会被生成。你可以借助 `examples.css`（用于预览框）或 `theme.css`（用于站点）里的一条 `@source` 指令来做到这一点，路径相对于它所在的文件书写——这是 Tailwind 的标准规则——Blume 会把它一并带进生成的样式表：

```css
/* examples/theme.css */
@source "../../../packages/ui/src";
```

```tsx
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <button
      className="rounded-blume border-border bg-background text-foreground hover:bg-muted border px-4 py-2 text-sm font-medium transition-colors"
      onClick={() => setCount((value) => value + 1)}
      type="button"
    >
      Clicked {count} {count === 1 ? "time" : "times"}
    </button>
  );
};

export default Counter;
```

```astro
<!-- examples/counter.tsx -->
<Component path="counter" />
```

Astro 示例会实时渲染，且不加载任何客户端 JavaScript：

```astro
---
interface Props {
  title?: string;
}

const { title = "Hello from Astro" } = Astro.props;
---

<div class="rounded-blume border border-border bg-muted/30 px-5 py-4">
  <p class="m-0 font-semibold text-foreground text-sm">{title}</p>
  <p class="m-0 mt-1 text-muted-foreground text-sm">
    A static, server-rendered example — no client JavaScript ships.
  </p>
</div>
```

## CodeBlock

`CodeBlock` 用与你围栏代码相同的 Shiki 主题和 transformer 来高亮一段代码字符串——包括浅色/深色切换——用于放不下围栏的场合，比如落地页或自定义组件。传入 `code` 和 `lang`：

```ts
export const greet = (name: string): string =>
`Hello, ${name}!`;
```

```astro
---
import CodeBlock from "blume/components/content/CodeBlock.astro";
---

<CodeBlock lang="ts" code={source} />
```

`title` 设置标题栏上的文字——比如一个文件名——否则那里显示的是语言名；`icons={false}` 会隐藏语言的品牌图标，就像围栏代码可以通过 [`markdown.code.icons`](/docs/content/syntax/) 做到的那样。

若想自己对 HTML 字符串做高亮（例如在你自己的组件内部），从 `blume/markdown` 导入底层辅助函数：

```ts
import { highlightCode } from "blume/markdown";

const html = await highlightCode(source, "ts");
```

## Diff

`Diff` 渲染 git 风格的差异，使用与你代码块相同的 Shiki 主题高亮，并且完全在构建期产出——没有客户端 JavaScript。可以给它两个行内字符串（`old` / `new`）、两个文件路径（`before` / `after`），或一份统一的补丁（行内的 `patch` 字符串或一个 `src` 文件）。

**变更前**

```ts
export function greet(name) {
return "Hi, " + name;
}
```

**变更后**

```ts
export function greet(name: string): string {
return "Hi, " + name + "!";
}
```

```astro
<Diff
  lang="ts"
  old={`export function greet(name) {
  return "Hi, " + name;
}`}
  new={`export function greet(name: string): string {
  return "Hi, " + name + "!";
}`}
/>
```

对比项目中的两个文件，路径相对于项目根目录：

<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />

```astro
<Diff before="diffs/button-before.ts" after="diffs/button-after.ts" />
```

或者渲染一份统一的补丁——既可以用 `src` 从文件读取，也可以用 `patch` 内联给出：

<Diff src="diffs/greet.patch" />

```astro
<Diff src="diffs/greet.patch" />
```

```astro
<Diff
  patch={`--- a/greet.ts
+++ b/greet.ts
@@ -1,3 +1,4 @@
-export function greet(name) {
-  return "Hi, " + name;
+export function greet(name: string): string {
+  const greeting = "Hi, " + name + "!";
+  return greeting;
 }`}
/>
```

---

# Frontmatter
Source: https://blume.ndjp.net/docs/content/frontmatter/
English: https://useblume.dev/docs/content/frontmatter

每个页面都可以使用以下 frontmatter 字段。所有字段都是可选的。

| 字段 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `title?` | `string` | - | 页面标题。 |
| `description?` | `string` | - | 页面摘要。 |
| `type?` | `string` | `doc` | 内容类型。blog/changelog 会驱动订阅源。 |
| `date?` | `string` | - | blog/changelog 订阅源使用的发布日期（ISO 或 YAML 日期）。 |
| `authors?` | `string \| string[] \| object[]` | - | blog/changelog 内容的作者——一个名字，或带 name 以及可选的 avatar/url 和任意额外字段的对象。保持原样。 |
| `slug?` | `string` | - | 设置页面从内容根目录起的完整路由（guides/setup）。它替换的是文件位置给出的整条路径，而不只是最后一段。出现 . 或 .. 段属于错误：浏览器会把它消解掉，任何链接都无法到达该页面。 |
| `draft?` | `boolean` | `false` | 不纳入生产构建。 |
| `deprecated?` | `boolean` | `false` | 标记页面已弃用：它的侧边栏行会加上一个弃用标记（可翻译的 UI 文案）。 |
| `hidden?` | `boolean` | `false` | `sidebar.hidden` 的简写。 |
| `noindex?` | `boolean` | `false` | `seo.noindex` 的简写。 |
| `narration?` | `boolean` | `true` | 设为 false 可让该页面在开启朗读时不显示「收听本页」播放器。 |
| `related?` | `(string \| { [title]: string })[] \| false` | - | 建议在页面底部展示的页面，最多十个：根相对路径、绝对 URL，或用 `{ Title: link }` 为链接命名。参见下文的「相关页面」。 |
| `pagination?` | `boolean` | `true` | 设为 false 可去掉页面底部的上一页/下一页链接。页面本身仍留在顺序中，因此相邻页面依旧会链接到它。 |
| `icon?` | `string` | - | 当 `sidebar.icon` 未设置时，用于页面侧边栏行的 Lucide 图标（`sidebar.icon` 优先）。 |
| `lastModified?` | `string` | - | 固定页面的「最后更新」日期（ISO 或 YAML 日期）；会覆盖从 git 推导出的日期。 |
| `mode?` | `"default" \| "wide" \| "center" \| "custom" \| "frame"` | `"default"` | 页面在内容之外还显示哪些部分。参见下文的「布局」。 |
| `api?` | `string` | - | 该页面手动记录的接口，以 HTTP 方法加路径或 URL 表示（POST /v1/users）。参见「手写 API 页面」。 |
| `authMethod?` | `"bearer" \| "basic" \| "key" \| "none"` | - | api 页面的接口如何认证，作用于站点的 `api.auth`。 |
| `playground?` | `"interactive" \| "simple" \| "none"` | `"interactive"` | api 页面显示什么：「试一试」面板和示例、仅示例，或都不显示。 |

## 布局

`mode` 决定页面在内容之外还显示什么：

| 模式 | 侧边栏 | 标题与目录 | 页尾链接与页脚 | 内容宽度 |
| --- | --- | --- | --- | --- |
| `default` | 显示 | 显示 | 显示 | 正文宽度 |
| `wide` | 显示 | 仅标题 | 显示 | 整列 |
| `center` | 不显示 | 仅标题 | 显示 | 居中的更宽一列 |
| `frame` | 显示 | 不显示 | 不显示 | 整列 |
| `custom` | 不显示 | 不显示 | 不显示 | 整页 |

`wide` 适合满是宽表格或图示的页面，`center` 适合从头往下读的发行说明或公告。`custom` 只保留页眉，适合用 MDX 编写的落地页；`frame` 还会保留侧边栏，适合嵌在文档导航里的工具或仪表盘。这两种模式都不渲染页面的 title 和 description，所以请自己写标题。所有模式都会参与搜索，并保留 Markdown 副本。

```yaml lineNumbers
title: Welcome
mode: custom
```

这些取值与 Mintlify 一致；它的 `assistant` 模式（整页聊天）在这里没有对应项。

## 相关页面

`related` 列出建议在页面底部展示的页面，以卡片形式显示在 **相关页面** 标题之下：

```yaml lineNumbers
related:
  - /guides/deployment
  - Search setup: /configuration/search
  - https://astro.build
```

根相对路径指向另一个页面，卡片会用该页面的标题和描述展示它；在已翻译的页面上，如果存在译文则链接到译文。`Title: link` 形式的条目会自行设定卡片标题，而绝对 URL 则以主机名链接到站外。路径和页面上的其他链接一样会被校验，所以 [`blume validate`](/docs/cli/validate/) 会报告匹配不到任何页面的路径。这个键名与 Mintlify 一致，因此迁移过来的页面可以原样保留。

## 侧边栏

```yaml lineNumbers
sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page
```

`hidden` 会把页面从侧边栏以及上一页/下一页翻页中移除。用在文件夹的 `index` 页面上时，它只移除该页面自己的那一行：分组行仍然链接到该页面，上一页/下一页链接也仍会经过它。

`display` 设定页面所属文件夹分组的渲染模式（[按分组覆盖](/docs/content/navigation/)），并且只在自动生成的侧边栏中、文件夹的 `index` 页面上才有意义——在其他任何位置（非 index 页面、内容根目录自身的 `index` 页面，或显式 `navigation.sidebar` 下的任何页面）它都没有可配置的分组，Blume 会以 `BLUME_SIDEBAR_DISPLAY_IGNORED` 发出警告。

## SEO

```yaml lineNumbers
seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
  x:
    creator: "@jane"
```

`noindex` 会输出 robots `noindex`，把页面从站点地图中移除，并跳过它的结构化数据。`x.creator` 把页面的作者信息指向一个 X 账号（`twitter:creator`）——比如客座文章的作者。全部字段参见[元数据](/docs/discoverability/metadata/)。

## 搜索

```yaml lineNumbers
search:
  exclude: false
  tags: [api]
  keywords: [install, setup]
  boost: 3
```

`exclude` 让页面不出现在搜索结果中，`tags` 把它归入搜索对话框里的某个筛选项。`keywords` 是除页面正文之外、能命中该页面的额外词。`boost` 会乘上页面的相关度：大于 1 排名更高，小于 1 则更低。参见[排序](/docs/configuration/search/)。

## AI

```yaml lineNumbers
ai:
  exclude: true
```

`ai.exclude` 让页面不出现在 [`llms.txt` 与 `llms-full.txt`](/docs/discoverability/llms-txt/) 中。页面照常渲染、参与搜索，并在站点地图中保留位置。

## 更新日志 [#changelog]

更新日志条目（`type: changelog`）可以接受一个可选的 `changelog` 对象，用来提供更丰富的订阅源与展示元数据：

```yaml lineNumbers
type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features
```

`date` 可以写在这里，也可以写在顶层——两者都会用于[更新日志 RSS 订阅](/docs/content/)。自动生成的时间线页面和订阅源参见[更新日志](/docs/advanced/changelog/)。

## 自定义键 [#custom-keys]

本表之外的任何键都会导致构建失败，从而尽早发现拼写错误。带有自有元数据的项目可以在 `blume.config.ts` 中通过 [`frontmatter.extend`](/docs/configuration/) 开放额外的键，每个键都由项目提供的 schema 校验：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});
```

```yaml page.mdx
---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---
```

schema 通过 [Standard Schema](https://standardschema.dev) 接口接入，因此 Zod（无论你的项目安装的是哪个版本）、Valibot 和 ArkType 都能用。每个声明的键都会在每个页面上校验——包括不存在的页面——因此必填 schema 会在全站强制该键；把它标为 `.optional()` 则只在出现时校验。其他所有键仍保持严格校验，内置字段也不能重复声明。

### 按类型区分的键 [#per-type-keys]

如果只想在某一种内容类型上要求某些键——比如 RFC 的 `status`、事故报告的 `severity`——就改在 [`content.types`](/docs/configuration/) 下按它们适用的 frontmatter `type` 声明：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});
```

```yaml rfcs/openapi-request-schemas.mdx
---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---
```

按类型区分的键遵循与 `extend` 相同的校验规则，但只作用于解析出的 `type` 匹配的页面——当声明针对 [`content.defaultType`](/docs/configuration/) 时，也包括那些没有设置 `type` 的页面。一个键只属于一处声明，要么全站级别，要么按类型级别，不能两者兼有。而只为另一种类型声明的键在其他地方依然属于未知键，所以普通文档页面上多写一个 `status` 仍会导致构建失败。

校验失败的页面会让 `blume build` 失败，并给出指明文件和键名的诊断信息。加上 [`--no-strict`](/docs/cli/) 后构建仍会成功，但失败的页面会从产物中剔除——构建摘要会报告剔除的数量。

这些 schema 从 `blume/schema` 导出，供编辑器和迁移工具使用。

---

# 国际化
Source: https://blume.ndjp.net/docs/content/i18n/
English: https://useblume.dev/docs/content/i18n

Blume 让一个项目支持多种语言。把译文放到正确的位置，Blume 就会为你接好路由、语言切换器、按语言的导航和 SEO——你不需要再维护一套单独的路由层。它是可选的：没有 `i18n` 块，你的站点就和以前一样保持单语言。它也可以与[版本管理](/docs/content/versioning/)组合——冻结的快照会保留自己的翻译，语言回退在每个版本内部生效。

## 启用

添加一个 `i18n` 块，列出你的语言以及哪一个是默认语言：

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}
```

每种语言都有一个 `code`（用于 URL）、一个 `label`（显示在语言切换器里），以及一个可选的 `dir` 用于从右到左的文字（默认 `"ltr"`）。可选的 `style` 会为 [`blume translate`](/docs/cli/translate/) 提供该语言的自由格式指引——语域、方言、术语，例如 `"Brazilian Portuguese, informal você"`——这样这个选择从第一次翻译起就被固定下来，而不是由 agent 临场决定。

## 组织翻译内容

默认语言的内容位于内容根目录。其他每种语言都是以其 `code` 命名的顶层文件夹，结构与默认语言一一对应：

```txt
docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar
```

| 文件 | 路由 |
| --- | --- |
| `docs/index.mdx` | `/` |
| `docs/guides/quickstart.mdx` | `/guides/quickstart` |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

不要为默认语言单独建文件夹：只有其它 code 才是语言文件夹，因此在默认语言为 `en` 的情况下，`docs/en/` 只是普通内容，会发布在 `/en/…`（并作为法语回退出现在 `/fr/en/…`）。Blume 发现这样的文件夹时会给出警告。

你只需要翻译想翻译的文件——其余的会自动回退（见[回退语言](#fallbacks)）。

### 文件名后缀

更希望把译文放在原文旁边？设置 `parser: "dot"`，并用语言后缀命名文件，而不用文件夹：

```txt
docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (默认)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (法语)
```

适合翻译量不多的情况——把已翻译的几页放在一起，不必镜像整棵目录树。

### 共享文件

对于每种语言都一样的正文——更新日志、状态页——加上 `$` 标记，让一个文件服务所有语言，无需重复：

```txt
docs/changelog.$.mdx   ->  /changelog 与 /fr/changelog（内容相同）
docs/guides/meta.$.ts   (文件夹元数据应用于所有语言)
```

针对某种语言的 `meta.ts` 仍会为该语言覆盖这份共享文件。

## 默认语言的 URL

默认情况下，默认语言没有 URL 前缀（`/`、`/guides/quickstart`），而其它语言带前缀（`/fr/…`）。这样主语言的 URL 保持干净。要给所有语言加前缀（包括默认语言）：

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## 按语言的导航 [#per-locale-navigation]

每种语言都有自己的侧边栏，由该语言的文件生成——因此译文在结构、顺序或标签上都可以不同。文件夹的 [`meta.ts`](/docs/content/meta/) 文件同样按语言解析：在默认的 `dir` 解析器下，把 `meta.ts` 放在 `fr/guides/` 下即可独立排序法语分组。在某种语言拥有自己的 `meta.ts`（或共享的 `meta.$.ts`）之前，它的分组会沿用[回退](#fallbacks)语言的分组——即那个文件夹的 `meta.ts`，以及其索引页所设置的 `sidebar.display`——这样发生回退的页面能保持相同的标题、顺序和可折叠分组。在 `dot` 解析器下译文与原文相邻，因此文件夹的 `meta.ts` 适用于所有语言。[导航](/docs/content/navigation/)的其他一切行为都按语言照常工作。

头部标签页、头部链接和页脚都是配置出来的，而不是从内容推导的，因此它们的文案要在 `blume.config.ts` 中本地化。每一条已配置的文案都接受一个按语言映射的对象（`{ en: "Docs", fr: "Documentation" }`），也可以直接用纯字符串；未填写的语言会回落到默认语言的条目：标签页与下拉菜单文案（[标签页](/docs/content/navigation/)）、[精选链接](/docs/content/navigation/)、[头部操作项](/docs/content/navigation/)及行动号召、[页脚](/docs/configuration/)链接，以及[横幅](/docs/configuration/)的文本与链接文字。

```ts blume.config.ts lineNumbers
navigation: {
  cta: {
    href: "https://acme.dev/signup",
    label: { en: "Start free", fr: "Essai gratuit" },
  },
},
footer: {
  links: [
    { label: { en: "Pricing", fr: "Tarifs" }, href: "https://acme.dev/pricing" },
  ],
},
```

标签页路径、头部与页脚链接，以及头部 logo 的链接，也会在该语言确实提供这个路由时切换到读者所在的语言，让整个界面始终停留在一种语言之内。只由默认语言提供的路由——例如[自定义页面](/docs/advanced/custom-pages/)或生成的[更新日志](/docs/advanced/changelog/)索引——会保留自己的路径，而不是指向一个会 404 的本地化 URL。

## 回退语言 [#fallbacks]

当某个页面还没有翻译时，Blume 会在本地化的 URL 上渲染回退语言的内容——这样链接照常可用，页面完整预渲染，搜索引擎也不会被引到死胡同。回退语言默认取你的 `defaultLocale`：

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // 默认；设为 null 则改为返回 404
}
```

回退页面把 canonical 链接指向它们所复制的那一页，并且被排除在搜索索引、`llms.txt` 以及 MCP 和 JSON API 的页面列表之外，`hreflang` 里也不会把它们宣称为真正的译文，因此未翻译的内容不会争抢排名。它们仍会出现在该语言的侧边栏里，导航因此保持完整——读者在任何语言下都能到达每个页面。

来自 [`githubReleases()`](/docs/content/sources/github-releases/) 内容源的发布说明是个例外：它们只用一种语言发布，因此永远不会被复制到其它语言的 URL 上，也不显示语言切换器。

:::tip
先从最重要的页面开始翻译——首页、快速上手和最核心的指南——其余的交给回退。你可以随时间逐步补齐译文，而不会弄坏任何链接。
:::

## 跨语言链接

在所有语言里（包括已翻译的页面），都像在默认语言中那样书写内部链接——`[Setup](/guides/setup)`、`<Card href="/guides/setup">`。当某个页面渲染在语言前缀之下时，只要该路由在那里有提供（无论是真译文还是回退页面），Blume 就会把每个根相对的页面链接迁到该语言下（`/fr/guides/setup`）。没有对应语言变体的链接——自定义页面、生成的路由，或在关闭回退的站点上缺失的译文——会保留你写下的目标，而不是指向 404；已经带语言前缀的链接（`/de/guides/setup`）则原样不动，因此跨语言链接始终是显式的。

锚点会跟着链接一起走，因此各语言标题的 id 必须一致。[`blume translate`](/docs/cli/translate/) 会处理这件事：每个译后的标题都会用结尾的 `[#id]` 标记固定到源标题的 id。手工编写译文时，请用同样的[`[#custom-id]` 标记](/docs/content/syntax/)自行固定标题——否则 `#ordering` 就匹配不上法语页面自动生成的 `#ordre`，`blume validate` 会针对读者实际落到的那一页报告不一致。

## 用 agent 翻译

你不必手工补齐每种语言。[`blume translate`](/docs/cli/translate/) 会找出每种语言中缺失或过期的页面，并用本地 agent CLI（[Codex](https://developers.openai.com/codex/cli) 或 [Claude Code](https://claude.com/claude-code)）翻译它们：

```bash
blume translate --codex
```

Blume 会校验每份结果的结构——frontmatter、代码围栏、链接——并自行写入文件；agent 只负责翻译文本。一份提交进版本库的账本（`blume.translations.json`）会记录每份译文来自哪个源修订，因此重跑时只改动发生变化的部分，而你手写的译文会被原样沿用，绝不覆盖。在 CI 中，当某个源页面比它的译文走得更远时，`blume translate --check` 会失败。

## 语言切换器 [#the-language-switcher]

启用 i18n 后，头部会自动出现语言切换器，由你的 `locales` 生成。对每个页面，它会链接到每种语言中对应的译文；若缺少译文，则链接到回退页面并标记为未翻译。没有任何需要配置的东西。来自 [GitHub Releases](/docs/content/sources/github-releases/) 内容源的页面是个例外：发布说明只有一种语言，因此这些页面渲染时不带切换器。

## 按浏览器语言路由

想把访客送到他自己的语言，就打开 `routeByBrowserLanguage`：

```ts blume.config.ts lineNumbers
i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
  ],
  routeByBrowserLanguage: true,
}
```

于是，从站外进入默认语言首页的访客会被送到其浏览器首选语言下的首页，前提是站点提供该语言。Blume 会按顺序逐一尝试浏览器偏好的语言，先匹配完整 code，再匹配基础语言（`fr-CA` 找到 `fr`）。如果默认语言排在第一位，访客就留在原地。一旦读者用切换器选定了一种语言，Blume 会记住这个选择，不再对他们做路由。只有首页会路由；指向其它页面的链接按原样打开。

重定向在页面绘制之前于浏览器中执行，因此在任何托管方式下都能工作，静态构建也包括在内。它默认关闭，因为搜索引擎只会用一种语言抓取：启用它时，请保留 Blume 输出的 [`hreflang` 备选链接](#seo)，以便每种语言的页面仍能被收录。

## 界面文案翻译 [#translated-ui]

Blume 自带自身界面文案的内置翻译——“On this page”、“Search”、“Edit on GitHub” 以及其余部分——所以有内置语言包的语种开箱即得翻译好的界面。**你只需要翻译自己的内容。**

语言包覆盖 30 多种语言——阿拉伯语、孟加拉语、保加利亚语、加泰罗尼亚语、简体中文与繁体中文、克罗地亚语、捷克语、丹麦语、荷兰语、芬兰语、法语、德语、希腊语、希伯来语、印地语、匈牙利语、印尼语、意大利语、日语、韩语、挪威语、波斯语、波兰语、葡萄牙语（含巴西葡萄牙语）、罗马尼亚语、俄语、塞尔维亚语、斯洛伐克语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语、越南语。它们由社区维护——提一个 PR 就能新增语种或打磨译文。

缺失或尚未发布的文案会先回落到默认语言，再回落到英文。要覆盖某句文案或补上你自己的语言，按语言设置 `i18n.ui`：

```ts blume.config.ts lineNumbers
i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}
```

## SEO [#seo]

本地化 SEO 由 Blume 为你处理——不需要逐页编写元数据：

- `<html lang>` 与 `dir` 依据当前生效的语言设置。
- `hreflang` 备选链接会链到某个页面的每一个真实译文，外加一个指向默认语言的 `x-default`。
- Canonical URL 与语言对应，JSON-LD 会带上 `inLanguage`。

设置 [`deployment.site`](/docs/deployment/)，这些内容就能以绝对 URL 的形式输出。

## 搜索

搜索范围限定在当前语言：在 `/fr/…` 页面上对话框返回法语结果，并提供一个**所有语言**开关，可一次搜遍所有语种。默认的（Orama）和 FlexSearch 索引在浏览器端过滤；托管服务提供方则会在每条记录上带上 `locale` 分面。

## 从右到左

给某种语言设置 `dir: "rtl"`，Blume 会把整个界面镜像过来——侧边栏、头部、目录、分页、搜索和菜单——并把 `<html dir>` 设成一致。有两处刻意保持从左到右：**代码块**（代码在任何语言里都是从左到右阅读的），以及**回退内容**——未翻译的页面保留其实际所用语言的方向，因此在 RTL 语言下显示的英文仍能正常阅读，而周围的界面则完整镜像。

## 接下来看什么

**[导航](/docs/content/navigation/)**

塑造每种语言的侧边栏、排序与标签页。

**[可发现性](/docs/discoverability/)**

站点地图、Open Graph 与结构化数据。

---

# 包含片段
Source: https://blume.ndjp.net/docs/content/includes/
English: https://useblume.dev/docs/content/includes

只需写一次代码片段，就能把它嵌入任意页面。单独占一行的 `<include>` 语句会在构建时嵌入另一个文件，就如同它的内容直接写在那里一样——其中的标题会并入页面的目录，文字会被搜索索引，这些内容也会出现在页面的 `.md` 镜像和 llms-full.txt 中。即使格式化工具把语句折成多行，它依然会被嵌入；而 Blume 无法解析的语句会在其所在行报出 `BLUME_INCLUDE_MALFORMED` 警告，而不是渲染成一个原始标签。

```mdx
<include>./_snippets/prerequisites.mdx</include>
```

路径相对于包含它的文件来解析。以 `/` 开头的路径从内容根目录解析，因此层级很深的页面无需 `../../..` 就能引用共享片段：

```mdx
<include>/_snippets/prerequisites.mdx</include>
```

该语法与 Fumadocs 的 include 语法一致，因此迁移过来的内容无需改动即可使用。

下面就是实际效果——紧接着的这个提示框是从一个共享片段嵌入进来的：

:::tip
这个提示框位于 `_snippets/include-demo.mdx`——它能在这里渲染，是因为本页通过一条 `<include>` 语句把它嵌入了进来。
:::

## 局部片段

默认情况下，文件名（或文件夹名）以下划线开头的文件不会进入路由、导航、搜索和站点地图——这个约定天然适合用来放共享片段：

```text
docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx
```

局部片段就是普通的 Markdown 或 MDX 文件。被嵌入时它的 frontmatter 会被剥离（以包含它的页面的 frontmatter 为准），其余内容——提示框、代码围栏、组件、公式——都和直接内联书写时渲染得完全一样。局部片段还可以再包含其他局部片段；循环包含会报错。

局部片段内部的相对图片引用依然有效：它们会以包含它的页面为基准重新解析，因此与片段放在一起编写的 `![diagram](./diagram.png)`，无论片段被嵌入到哪里都能正确解析。

在 `blume dev` 运行期间修改局部片段，会让所有包含它的页面重新加载。

## 属性

以属性的形式把值传进局部片段，再在片段里用 `{{name}}` 读取，语法和[变量](/docs/content/variables/)完全一样。这样一个片段就能服务所有需要不同变体的页面：

```mdx docs/_snippets/upgrade.mdx
Upgrade to the **{{plan}}** plan to use {{feature}}.
```

```mdx docs/sso.mdx
<include plan="Enterprise" feature="SSO">
  ./_snippets/upgrade.mdx
</include>
```

属性既作用于被包含的文件，也作用于它继续包含的内容，并且优先于同名的站点级变量。除 `lang` 和 `meta` 之外，其他每个属性都是一个 prop；属性值是纯文本。

## 包含代码文件

如果目标文件不是 `.md`/`.mdx`，它会以围栏代码块的形式嵌入，并从扩展名推断语言。用 `lang` 可以覆盖语言（也可以把 Markdown 文件按源码展示而不嵌入内容），用 `meta` 可以传入围栏的 meta 字符串，例如标题：

```mdx
<include>./examples/config.ts</include>

<include meta='title="config.ts"'>./examples/config.ts</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>
```

## 规则与诊断

包含语句必须独占一行——它们是块级的，不是行内的。围栏代码块内部的语句不会被处理，所以你可以照常讲解这套语法（就像本页所做的）。

目标文件必须位于内容根目录之内：根目录之外的文件会在版本快照和 eject 出来的项目中被悄悄漏掉，因此 `blume` 会报 `BLUME_INCLUDE_OUTSIDE_ROOT` 而不嵌入它。目标不存在是 `BLUME_INCLUDE_NOT_FOUND`，包含成环则是 `BLUME_INCLUDE_CYCLE`——这三者都会让 `blume build` 失败（可以加 `--no-strict` 强行构建），并且会出现在 `blume validate` 中。

局部片段内部的失效链接会记在片段文件上，而不是记在嵌入它的那些页面上，所以你在片段所在的位置修正它们即可。

:::note
局部片段在各语言环境之间共用，`blume translate` 不会翻译它们——请让局部片段保持语言中立（代码、表格、图示），或者为每个语言环境分别创建片段，再由各语言环境的页面分别包含。
:::

---

# 交互岛
Source: https://blume.ndjp.net/docs/content/islands/
English: https://useblume.dev/docs/content/islands

默认情况下，Blume 会把你的文档渲染成**零 JavaScript**的静态 HTML。当你需要交互能力时——一个可实时运行的示例、一张图表、一个 playground——就加上一个**交互岛**：一个只为自身、且只在用到它的页面上加载 JS 的框架组件。

## `islands/` 约定

把组件放进项目根目录下的 `islands/` 文件夹里。它的文件名会成为你可以在**任意** `.mdx` 页面中使用、无需 import 的组件：

```tsx islands/Counter.tsx lineNumbers
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Clicked {count}</button>;
}
```

```mdx page.mdx
Here's a live counter: <Counter />
```

文件名就是组件名，因此它**必须是帕斯卡命名的标识符**——只能包含字母、数字和下划线（`Counter.tsx` → `<Counter />`）。小写文件名，以及带连字符、点或空格的名字（比如 `Time-Picker.tsx`）会被跳过，并给出构建警告。当两个交互岛解析出同一个名字时——`Counter.tsx` 与 `Counter.vue`，或者不同子文件夹下的两个 `Counter.tsx`——Blume 会按文件路径保留第一个、忽略另一个，并给出构建警告。

:::note
交互岛用于**交互式** UI。若只是想跨页面复用一个静态组件（一个带样式的提示框、一张价格表），请改用 [MDX 覆盖](/docs/configuration/customization/)——它不加载任何 JavaScript。
:::

## 在 `components.ts` 中注册交互岛 [#registering-islands-in-componentsts]

如果你更愿意把交互岛放在其余组件旁边——或者想给它们一个与文件名不同的名字——就用 `defineComponents` 把它们注册为带 `client` 模式的 `mdx` 条目。交互岛无非就是一个会水合的 MDX 组件。每个条目在每个 MDX 页面里都可用，而与某个 `islands/` 文件同名的条目会取代它。

```ts components.ts
import { defineComponents } from "blume";
import Counter from "./widgets/Counter.tsx";

export default defineComponents({
  mdx: {
    Counter: { component: Counter, client: "visible" }, // 在任意 MDX 页面中使用 <Counter />，并水合
  },
});
```

你可以通过 import 或路径字符串来引用组件，并为每个交互岛选择水合模式（`"media"` 需要同时提供一个 `media` 查询）：

```ts components.ts
export default defineComponents({
  mdx: {
    Chart: { component: "./widgets/Chart.tsx", client: "only" },
  },
});
```

与文件夹方式不同，这里没有默认值：不带 `client` 的 `mdx` 条目会渲染成静态 HTML，若该条目是 React、Vue 或 Svelte 组件，Blume 会给出警告。Blume 会静态解析 `components.ts`，因此一个条目必须是导入进来的组件、路径字符串，或一个 `{ component, client, media }` 对象字面量——可接受的形式以及其它写法会得到的报错，见[自定义](/docs/configuration/customization/)。

## 水合

默认情况下交互岛使用 `client:visible`：当读者把它滚动到视野中时才水合，因此即使满页都是交互岛也能瞬间加载。要换用别的策略，就在交互岛文件里写 `export const client`：

```tsx islands/Chart.tsx lineNumbers
// 完全跳过服务端渲染——适用于会访问 DOM/window 的组件
export const client = "only";

export default function Chart() {
  /* ... */
}
```

| `client` 取值 | 何时水合 | 适用场景 |
| --- | --- | --- |
| `"visible"` _(默认)_ | 滚动到视野中时 | 大多数交互岛 |
| `"load"` | 页面加载时立即 | 首屏、必须瞬时呈现的 UI |
| `"idle"` | 主线程空闲时 | 不紧急的交互 |
| `"only"` | 仅客户端，永不服务端渲染 | 需要 `window`/`document` 的库（图表、编辑器） |
| `"media"` _(`components.ts` 仅支持)_ | 某个 CSS 媒体查询匹配时 | 只在特定尺寸下运行的 UI，比如仅移动端的菜单 |

`"media"` 需要配套的查询，因此它只对 [`components.ts` 条目](#registering-islands-in-componentsts)可用——`{ component: Menu, client: "media", media: "(max-width: 50em)" }`。在 `islands/` 文件里声明它会退回到 `"visible"` 并给出警告。

## 框架 [#frameworks]

**React 开箱即用**——一旦你的项目里出现 `.tsx`/`.jsx` 交互岛，Blume 就会自动启用它。

只要启用了 React，[React Compiler](https://react.dev/learn/react-compiler) 就默认开启，因此你的交互岛会被自动 memo 化——不需要手写 `useMemo`/`useCallback`。它随 Blume 一起提供，无需安装任何东西。要关掉它，在 `blume.config.ts` 中：

```ts blume.config.ts
export default defineConfig({
  react: { compiler: false },
});
```

**Vue 和 Svelte** 同样受支持；安装对应的 Astro 集成，Blume 会在看到 `.vue` 或 `.svelte` 交互岛时接好渲染器：

```bash
# Vue
npm install @astrojs/vue vue

# Svelte
npm install @astrojs/svelte svelte
```

```vue islands/Toggle.vue lineNumbers
<script setup>
import { ref } from "vue";
const on = ref(false);
</script>

<template>
  <button @click="on = !on">{{ on ? "On" : "Off" }}</button>
</template>
```

你在 MDX 里传入的属性（`<Counter start={5} />`）会转发给组件，子节点（`<Counter>label</Counter>`）则作为默认插槽传入。

:::tip
交互岛在客户端水合，因此作为属性传入的一切都必须是可序列化的——字符串、数字、纯对象，不能是函数。
:::

## Hooks

交互岛各自独立水合，因此没有 React context 可以用来层层传递项目数据。取而代之，`blume/hooks` 会读取一小份由布局序列化进页面的快照——不需要逐层传属性：

```tsx islands/PageInfo.tsx lineNumbers
import { useBlume, usePage } from "blume/hooks";

export default function PageInfo() {
  const blume = useBlume();
  const page = usePage();
  if (!(blume && page)) {
    return null;
  }
  return (
    <p>
      You're reading <strong>{page.title}</strong> on {blume.config.title}.
    </p>
  );
}
```

| Hook | 返回值 |
| --- | --- |
| `useBlume()` | 站点的 `{ config, navigation }`，挂载前为 `null` |
| `usePage()` | 当前页面的 `{ route, title }`，挂载前为 `null` |
| `useSearch()` | `{ search, results, loading }`——查询已配置的搜索服务 |
| `useAssistant()` | `{ ask, messages, loading, reset }`——从 assistant 接口流式输出 |

`useBlume()` 和 `usePage()` 在交互岛挂载前会返回 `null`（这样服务端与客户端渲染出的首帧一致）——请为此做判断。快照只在携带 React 的页面上输出，因此全静态站点不为此付出任何代价。

在用 `PageLayout` 构建的[自定义页面](/docs/advanced/custom-pages/)上，传入 `clientData`，好让那里的交互岛能读取它：

```astro
<PageLayout
  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title: "Home" } }}
  {/* …other props… */}
/>
```

---

# Meta 配置
Source: https://blume.ndjp.net/docs/content/meta/
English: https://useblume.dev/docs/content/meta

内容目录中的每个文件夹都会成为一个侧边栏分组。在它同级页面的位置放一个 `meta.ts`，就能控制这个分组的外观以及子项的顺序。这一步完全可选：没有它时，分组标签就是「人性化」的文件夹名，其页面按[索引、数字前缀，然后字母序](/docs/content/navigation/)排序。

## 定义 Meta

导出一个 `defineMeta` 对象，即可获得类型完备的配置。把文件放在它所配置文件夹的根目录下——`guides/meta.ts` 配置的是 **Guides** 分组：

```ts meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});
```

每个字段都是可选的——只写你想覆盖的部分。

Blume 只会读取内容所覆盖文件夹中的 `meta.ts`：位于被内容 `exclude` 通配模式跳过的文件夹下、或在所有 `include` 通配模式之外的文件，永远不会被导入。当 `root: "."` 且 `exclude: ["**/_*", "**/.*", "src/**"]` 时，一个无关的 `src/lib/meta.ts` 不会被碰。`exclude` 是替换默认的 `["**/_*", "**/.*"]` 而不是追加，所以要保持 `_` 前缀的局部片段和点号文件不发布，就要把这两条也一并列出。

## 字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `title` | `string` | 分组标签。默认为「人性化」的文件夹名。 |
| `icon` | `string` | 显示在标签旁的图标。 |
| `order` | `number` | 在同级分组和页面中的位置。数字越小越靠前。 |
| `collapsed` | `boolean` | 在 [`group` 显示模式](/docs/content/navigation/)下，该分组是否默认折叠。 |
| `display` | `"flat" \| "group" \| "page"` | 该分组的渲染模式；覆盖全局的 [`navigation.sidebar.display`](/docs/content/navigation/)。 |
| `directory` | `"card" \| "accordion" \| "none"` | 把分组的页面列在它 `index` 页面的内容下方。嵌套文件夹会继承它。参见[目录列表](/docs/content/navigation/)。 |
| `pages` | `string[]` | 按 slug 显式指定分组的子项顺序。 |

`pages` 数组按 slug 列出子项——即去掉数字前缀和括号的文件夹名或文件名（所以 `01-quickstart.mdx` 对应 `"quickstart"`）。列出的每个子项以它在数组中的位置作为顺序（`0`、`1`、`2`……）。没有列出的子项同样会出现，按各自的规则排序：`index` 页面始终排在最前；带有 `sidebar.order`、数字前缀，或带有自己 `meta.ts` 里 `order` 的子项，按该数字在已列出的子项之间排序；这些都没有的子项则排在它们之后。如果这个数组要代表完整顺序，就把每个子项都列出来。

该数组在页面之间排序页面、在分组之间排序分组，但不会在这两类之间交错：在侧边栏顶部（以及每个[标签页](/docs/content/navigation/)区域的顶部），以及任何含有 [`flat`](/docs/content/navigation/) 子分组的分组里——否则那个子分组的标题看起来就像「拥有」了它后面的页面。在这些位置，`pages: ["advanced", "intro"]` 仍然会把 `intro` 页面列在 `advanced` 分组上方。

分组的渲染方式——平铺标题、可折叠展开区，还是可下钻的面板——默认取自整个侧边栏的 `navigation.sidebar.display`；在这里设置 `display` 只会覆盖这一个分组。文件夹的 `index` 页面也能在 frontmatter 里设置它，且优先级高于 `meta.ts`——参见[按分组覆盖](/docs/content/navigation/)。

## 计算式 Meta

由于 `meta.ts` 是一个真正的模块，你可以计算 meta——传入一个函数（同步或 `async`）而不是对象，在扫描时构建它。从外部来源读取页面顺序时，这很方便：

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));
```

## 分组内的顺序

`pages` 数组决定分组子项的顺序，并且优先于已列出页面自身的 `sidebar.order`，也优先于已列出子文件夹自身的 `order`。数组没有涵盖的部分会依次回退到各页面的 frontmatter `sidebar.order`，然后是文件系统（`index` 页面优先，然后数字前缀，然后字母序）。完整的侧边栏优先级规则——包括显式配置的侧边栏——参见[导航 › 排序](/docs/content/navigation/)。

如果想给页面分组却_不_增加 URL 层级，其实完全不需要 `meta.ts`：用带括号的文件夹名即可——参见[页面 › 分组文件夹](/docs/content/)。

## 国际化

在 [i18n](/docs/content/i18n/) 下，文件夹 meta 按语言环境分别解析：把 `meta.ts` 放在 `fr/guides/` 下即可单独排序法语分组。如果没有（或者使用下文的共享 `meta.$.ts`），法语分组会沿用回退语言环境的 `meta.ts`。

如果文件夹 meta 在所有语言里都相同，加上 `$` 标记就能让一个文件服务所有语言环境，无需重复：

```txt
docs/guides/meta.$.ts   （应用于所有语言环境的文件夹 meta）
```

针对特定语言环境的 `meta.ts` 仍会为该语言覆盖共享的 `meta.$.ts`。

## 接下来看什么

**[导航](/docs/content/navigation/)**

侧边栏、面包屑和标签页是怎么构建出来的。

**[Frontmatter](/docs/content/frontmatter/)**

逐页面的元数据，包括 `sidebar` 覆盖项。

---

# 导航
Source: https://blume.ndjp.net/docs/content/navigation/
English: https://useblume.dev/docs/content/navigation

Blume 先根据文件系统构建侧边栏，然后让你随意微调——想调多少就调多少：逐页调整、逐文件夹调整，或者用一份显式配置统管。面包屑、上一页/下一页链接和页内大纲都由同一套模型推导而来，无需任何接线。

## 自动生成的侧边栏

默认情况下，侧边栏与你的内容目录一一对应：

- 文件夹变成**分组**，文件变成**页面**
- 页面的标签取自它的 frontmatter `title`；分组的标签是「人性化」的文件夹名，常见缩写如 API、CLI、SDK 保持大写（`api-reference` 会显示为 "API Reference"）
- 条目先按[数字前缀](/docs/content/)排序，然后按字母序排序，文件夹的 `index` 页面排在最前
- 带 `index` 页面的文件夹，其分组行会链接到该页面，因此点击板块名就会打开该板块的落地页

对很多站点来说这已经足够——下面的一切都是可选项。

## 页面标签、图标与徽标

在页面的 frontmatter 中通过 `sidebar` 调整单个页面在侧边栏中的样子：

```yaml lineNumbers
sidebar:
  label: Quickstart # 覆盖侧边栏中显示的标题
  icon: rocket # Blume 内置图标集中的一个图标
  badge: New # 条目旁的小标签
  order: 1 # 在所属分组内的排序位置
```

完整的页面结构参见 [Frontmatter](/docs/content/frontmatter/)。

## 文件夹分组

每个文件夹都会成为一个侧边栏分组。在它同级页面的位置放一个 [`meta.ts`](/docs/content/meta/)，即可设置该分组的标题、图标、顺序以及子项的顺序：

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

全部字段以及在扫描时计算 meta 的做法，参见[文件夹 Meta](/docs/content/meta/)。

文件夹的 `meta.title` 与它自己 `index` 页面 frontmatter 中的 `title` 是各自独立解析的——在 i18n 下翻译了其中一个却忘了另一个，就会出现侧边栏正确、但落地页自身的 `<title>`/标题仍是旧内容的情况。当二者不一致，且该 index 页面隐藏了自己的侧边栏行（`sidebar.hidden: true`）时，文件夹标题是该页面唯一的侧边栏标签，Blume 会报出 `BLUME_NAV_INDEX_TITLE_MISMATCH` 警告。当 index 行可见时，侧边栏已经同时显示了两个标题，因此把文件夹标题和不同的页面标题配对（「CLI」配「Overview」）没有问题。从回退语言环境填充的未翻译页面不在此列——它们的标题属于回退语言环境，正确的做法是翻译页面，而不是去改它的 frontmatter。

若想给页面分组却_不_增加 URL 层级，请使用带括号的文件夹名——参见[页面](/docs/content/)。

## 显示模式 [#display-modes]

`navigation.sidebar.display` 决定每个侧边栏分组的渲染方式：

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`**（默认）——不可折叠的标题，其页面列在下方。不属于任何分组的页面总是最先列出，位于各分组板块之上，因此不会被误认为某个分组的子项。
- **`group`**——每个分组是一个可折叠的 `<details>` 展开区。分组默认折叠；包含当前页面的分组总是默认展开，这样只有你所在的部分被展开。无论如何都想让某个分组保持展开，可在[文件夹 Meta](/docs/content/meta/)中设置 `collapsed: false`。
- **`page`**——每个分组占一行，点击后侧边栏会滑入一个子面板，只显示该分组的条目，顶部有一个返回箭头。面板能感知当前路由，因此直接访问分组内的某个页面会直接打开到它。

:::tip
`page` 模式能让层级较深的板块保持整洁——当分组下有很多子项，你更想逐层进入而不是一路滚过去时，就用它。
:::

在 `group` 和 `page` 两种模式下，当前页面未展开的板块不会写入该页面的 HTML，而是在首次展开时才获取（当指针或焦点移到它所在行时就会预取，所以展开通常是瞬时的；一旦获取过，本次访问期间就会一直保留）。在大型站点上，这往往是一个页面重量的主要部分：随页面一起下发的只有已展开板块的行。这些行是预渲染片段，位于 `/blume-nav/` 之下，因此不需要任何服务器。不启用 JavaScript 的读者会看到已展开的板块和分组行；而站点地图、上一页/下一页链接和已展开的板块，保证爬虫仍能访问到每个页面。

### 按分组覆盖 [#per-group-overrides]

任何自动生成的分组都可以脱离全局模式——无需配置显式侧边栏。在文件夹的 [`meta.ts`](/docs/content/meta/) 中设置 `display`，或者——当该文件夹有 `index` 页面时——在该页面 frontmatter 的 `sidebar` 下设置，只有该分组会改变：

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

自动生成分组的实际模式按优先级从高到低解析：

1. 该分组自身 `index` 页面 frontmatter 中的 `sidebar.display`
2. 文件夹 `meta.ts` 中的 `display`
3. 全局的 `navigation.sidebar.display`
4. Blume 默认值（`flat`）

分组的 `display` 只作用于该分组本身——嵌套子分组会沿同一条链各自解析自己的值。处于 `page` 模式且带 index 页面的分组依然会下钻到子面板：index 页面会作为面板的第一项列出，直接访问它的 URL 也会直接打开面板。

在其他任何位置，`sidebar.display` 都不起作用——非 index 页面、内容根目录自身的 `index` 页面（根目录不是分组，请用 `navigation.sidebar.display`），以及配置了[显式侧边栏](#explicit-sidebar)时的任何页面（此时各个分组的模式由其条目自己决定）——因此 Blume 会报出 `BLUME_SIDEBAR_DISPLAY_IGNORED` 警告，而不是悄悄把它丢掉。`collapsed` 仍然只对 `group` 模式有效；当分组解析为 `flat` 或 `page` 时它不起作用。

[显式侧边栏](#explicit-sidebar)中的分组会用它自己的 `display` 覆盖全局模式，与前面完全一致。

## 目录列表 [#directory-listings]

分组自己的页面可以在其内容下方列出该分组的其他页面，于是板块的落地页同时充当它的目录。在文件夹的 [`meta.ts`](/docs/content/meta/) 中设置 `directory`：

```ts guides/meta.ts lineNumbers
import { defineMeta } from "blume";

export default defineMeta({
  directory: "card",
});
```

- **`card`** 把每个页面和子分组显示为带图标和描述的卡片。
- **`accordion`** 把页面列为行，每个子分组则是可展开以显示其页面的板块。
- **`none`** 不列出任何内容。这是默认值。

只有拥有自己页面的分组才有地方展示这份列表：文件夹的 `index` 页面，或显式分组中的 `root`。该设置会向下传递到嵌套文件夹，因此在内容根目录的 `meta.ts` 上设置一次 `directory` 就能让每个板块都有列表；而文件夹也可以设置自己的值（包括 `none`）来覆盖继承到的值。[显式侧边栏](#explicit-sidebar)同样以这种方式在其分组上设置 `directory`。

## 排序 [#ordering]

侧边栏自动生成时，顺序按优先级从高到低解析：

1. **配置中的侧边栏**

    显式的 `navigation.sidebar` 会完全取代自动生成的目录树。

2. **文件夹 Meta**

    `meta.ts` 中的 `pages` 数组决定分组的顺序。

3. **Frontmatter**

    页面上的 `sidebar.order`。

4. **文件系统**

    `index` 页面优先，然后数字前缀，然后按标签的字母序。

两个同级项落在相同的显式顺序或数字顺序上时，它们之间会退回按字母序排列——Blume 会报出 `BLUME_DUPLICATE_SIDEBAR_ORDER` 警告，以免这种并列被忽略。

## 隐藏页面 [#hidden-pages]

把页面从侧边栏——以及上一页/下一页翻页——中隐藏，同时仍会构建它、并可通过 URL 访问：

```yaml
sidebar:
  hidden: true
```

文件夹的 `index` 页面既是分组行的链接目标，也是分组内的第一行。隐藏 index 页面会只留下这个带链接的标题：分组行依然会打开落地页，上一页/下一页链接也依然会经过它。

## 标签页 [#tabs]

把顶级板块渲染成页眉中的标签页，适合把大型站点划分为若干独立区域——比如适配器、API 和 AI 指南。当当前路由落在某个标签页的 `path` 之下时，该标签页会高亮：

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

标签页可选的 `icon`（一个[内置图标](/docs/content/components/)名称、图片路径/URL，或内联 SVG）会显示在标签旁，无论在页眉还是在移动端导航抽屉中。

启用后的 [OpenAPI](/docs/references/openapi/)、[AsyncAPI](/docs/references/asyncapi/) 或 [GraphQL](/docs/references/graphql/) 引用会挂载到自己的路由上，但不会自动添加标签页——把某个标签页指向该路由，就能让它出现在页眉中（对原生渲染器而言，还能限定其操作侧边栏的范围），标签文字随你定：

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

标签页的 `path` 是它所在板块的前缀，同时也是链接目标。如果某个板块的 `path` 不是它自己的某个页面——比如没有 `index.mdx` 的文件夹——链接就会指向 404，因此标签页会改为回退到该板块的第一个页面。位于标签页 `path` 上的静态[自定义页面](/docs/advanced/custom-pages/)也算作该板块自己的页面：有了 `pages/guides.astro`，`/guides` 标签页就会落到该页面上，同时 `guides/` 文件夹填充它的侧边栏。自动生成的[更新日志](/docs/advanced/changelog/)索引同样如此，于是 `/changelog` 标签页打开的是时间线，而不是最新一条。

如果你希望标签页落到别处——比如板块内的某个特定页面——就设置 `href`：

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Guides", path: "/guides", href: "/guides/getting-started" },
  ],
}
```

没有设置 `href` 的标签页沿用上述解析规则。

给标签页加上 `items` 就能把它变成下拉菜单。该标签页自身不再指向任何链接：它在页眉中展开由这些条目组成的菜单，在移动端导航抽屉中就地展开它们。它的 `path` 仍然用于限定侧边栏范围并标记当前标签页，`href` 则不再适用。每个条目需要一个 `label` 和一个 `path`，还可以有可选的 `icon`、`description` 和 `tag`，与[选择器](#selectors)的条目一致：

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Guides", path: "/guides" },
    {
      label: "SDKs",
      path: "/sdks",
      items: [
        { label: "JavaScript", path: "/sdks/javascript", description: "Node and the browser" },
        { label: "Python", path: "/sdks/python", tag: "Beta" },
      ],
    },
  ],
}
```

在 [i18n](/docs/content/i18n/) 站点上，标签页的 `label`（以及下拉条目的 `label`）可以是按语言环境映射的对象而不是字符串——优先取当前语言环境的值，其次取默认语言环境的值：

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // 普通字符串在任何语言环境下都原样渲染
  ],
}
```

[选择器](#selectors)的标签不支持映射：它的 `label` 和每个条目的标签都是普通字符串。

标签页还会**限定侧边栏的范围**：当当前路由落在某个标签页的 `path` 之下时，侧边栏只显示该板块的页面——因此 `/adapters/*` 只列出适配器。标签页 `path` 处的文件夹即为该板块，所以除了标签页本身不需要任何额外配置；把内容按每个标签页一个文件夹来组织，再让每个标签页指向它即可。

对于不属于任何标签页的路由（或某个 `path` 为 `/` 的标签页下的路由），侧边栏会显示那些_不_属于任何标签页的页面——每个标签页的文件夹都从它面前隐藏，因为该板块在页眉里已经有自己的标签页了。于是根落地页会列出散落的顶层页面，而带板块的内容则留在各自的标签页后面，这与 Fumadocs 的根文件夹做法一致。如果某个路由没有自己的页面可以这样展示，就会改为显示完整的目录树，因此侧边栏永远不会空白。

## 选择器 [#selectors]

要在一个站点的若干完整分区之间切换——产品、版本，或任何成组的目标集合——可以添加一个 `selector`。每个选择器都会渲染成页眉里的下拉菜单，并显示 `path` 与当前路由匹配的那一项：

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

每个条目需要一个 `label`、一个 `path`，以及可选的 `icon`、`description` 和 `tag`。`kind`（`dropdown`、`product`、`version` 或 `language`）只是提示该选择器的用途；它们渲染出的下拉菜单完全相同。

配置了[版本控制](/docs/content/versioning/)后，Blume 会自动渲染一个版本选择器——在这里声明自己的 `kind: "version"` 选择器会取代自动生成的那个，因此手写的方案仍然可用。

在比桌面侧边栏更窄的屏幕上，选择器、版本选择器和[语言切换器](/docs/content/i18n/)会从页眉移到移动端导航抽屉顶部，各自占满抽屉宽度。

## 置顶链接 [#featured-links]

把链接固定到侧边栏顶部、所有板块之上——比如博客、更新日志、联系或支持页面，这些地方应该永远一键可达。与自动生成的目录树不同，置顶链接**不受标签页限定**：它们在每个路由、每种断点下都会显示。

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

每个链接需要一个 `label`、一个 `href`，以及可选的 `icon`（一个[内置图标](/docs/content/components/)名称、图片路径/URL 或内联 SVG——与其他地方完全相同）。`href` 可以指向任何位置：外部 URL 会在新标签页中打开，而内部路由（如 `/contact`）会在构建时与你的页面校验，若没有任何匹配会给出警告。

## 显式侧边栏 [#explicit-sidebar]

若要完全掌控，可以在 `navigation.sidebar` 中列出显式条目——直接写数组是 `sidebar.items` 的简写，而对象形式则把它们与全局的 [`display`](#display-modes) 组合在一起。一旦设置了条目，Blume 就会原样使用它们，并跳过基于文件系统的生成：

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // 页面，按路由引用
    {
      label: "Guides", // 分组
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // 外部链接
  ],
}
```

每个条目要么是页面路由（字符串），要么是分组（`label` + `items`），要么是链接（`label` + `href`）。分组可以嵌套、可以覆盖全局的 [`display` 模式](#display-modes)、可以默认 `collapsed`，还可以链接一个 `root` 页面，用 [`directory`](#directory-listings) 列出该分组的页面。

对于无法照原样渲染的条目，Blume 会给出警告：匹配不到任何页面的路由（该条目会被略去）、匹配不到任何页面的 `root`（它的链接会 404），以及既没有路由、`href`、`root` 也没有 `items` 的条目（会被略去）。

## 页眉操作 [#header-actions]

`navigation.actions` 把普通链接放进页眉，位于图标按钮左侧；`navigation.cta` 则是唯一的实心按钮：

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

和标签页标签一样，在[多语言](/docs/content/i18n/)站点上，这里的 `label` 也可以是语言环境代码到文本的映射。

`cta` 故意是单数——文档页眉只容得下一件要读者去做的事，而一排按钮什么也没要求。次要链接应放进 `actions`，或者当它们应与侧边栏放在一起时放进 [`featured`](#featured-links)。

`http(s)` 或协议相对的 href 会在新标签页中打开；路由则留在当前标签页，并像 `featured` 链接一样在构建时与你的页面校验——因此由同一主机上另一个应用提供的页面（比如产品站的 `/signup`）应写成绝对 URL。在 `sm` 断点以下，`actions` 会被隐藏，因为那时的页眉只容得下 logo 和导航开关。`cta` 在那里同样隐藏，唯一的例外是没有导航开关的页面——比如没有标签页的 `PageLayout` 落地页——它会保留，因为在手机上没有别的方式能把它呈现出来。

## 仓库链接 [#repository-link]

当你在配置中设置了 [`github`](/docs/configuration/) 后，Blume 会在[页脚](/docs/configuration/)中你的社交资料之前显示一个 GitHub 图标，链接到你的仓库。它默认开启；用 `navigation.repo` 可以隐藏：

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // 隐藏页脚的 GitHub 链接（默认：true）
}
```

只有配置了 `github` 时该链接才会出现，因此没有仓库的项目无论哪种设置都不受影响。

`repo` 也可以接受一个绝对 URL，让 GitHub 标记指向 GitHub 上的任意位置：

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

这适用于文档仓库为私有仓库的项目。`github` 同时驱动逐页面的编辑链接、GitHub 标记和[代理清单](/docs/discoverability/agent-discovery/)中的仓库，因此这类项目必须不设置 `github`——而正是一个 URL 让它仍能显示一个指向公开位置的标记。`footer.socials.github` 中的 URL 会取代这个标记；指向其他主机的链接则应放在页脚的 `links` 或 [`actions`](#header-actions) 中。

## 面包屑与翻页

它们直接来自侧边栏目录树，无需任何配置：

- **面包屑**会在标题上方显示当前页面所属的父分组。
- 每个页面底部的**上一页和下一页**链接遵循侧边栏顺序，并跳过隐藏的页面。在页面的 frontmatter 中设置 [`pagination: false`](/docs/content/frontmatter/) 即可在该页面上取消它们。

## 本页大纲

右侧栏的大纲会根据每个页面的标题自动生成——默认取 `##` 和 `###`——因此长页面依然便于快速浏览。设置 [`toc`](/docs/configuration/) 可以改变标题范围或关闭大纲。在更窄的屏幕上，右栏会隐藏，大纲则折叠成内容上方的「本页大纲」下拉菜单。

## 页面操作 [#page-actions]

在目录下方，每个页面都会显示一组快捷操作：

- **在 GitHub 上编辑**——直接链接到源文件。在配置中设置 [`github`](/docs/configuration/) 后出现。
- **回到顶部**——平滑地把长页面滚回顶部。

另外还有一些把页面交给 AI 工具的操作——**复制为 Markdown** 和**在对话中打开**——参见[面向代理的 Markdown](/docs/discoverability/markdown/)。

反馈则放在页面底部：一个「本页对你有帮助吗？」的是/否评分，它会发送 `feedback` 分析事件，且不需要 `github`——参见[页面反馈](/docs/configuration/)。

开启 [`export`](/docs/configuration/export/) 后，还有一个**导出**操作，让读者可以把页面下载为 PDF 或 EPUB。

---

# 内容来源
Source: https://blume.ndjp.net/docs/content/sources/
English: https://useblume.dev/docs/content/sources

默认情况下 Blume 读取一个装着 `.md`/`.mdx` 文件的文件夹。**内容来源**让你把页面从别处拉进来 —— 远程仓库、CMS，或任意自定义后端 —— 并把多个来源混进同一个站点。来源在构建期读取，Blume 保持静态优先。

## 默认来源

不做任何配置时，Blume 把内容根目录（默认 `docs`）当作一个文件系统来源来扫描。顶层的 `content.root`、`content.include` 与 `content.exclude` 就是这个单一来源的简写 —— 不需要引入任何东西，也不需要改动。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: { root: "docs" },
});
```

## 适配器 [#adapters]

`content.sources` 里的每一项都是一个**适配器**：从 `blume/sources` 引入的工厂函数，返回一个 Blume 在构建期读取的普通描述对象。给 `sources` 加一个数组即可组合多个来源。`sources` 一旦出现就会取代隐式的默认来源，所以要把本地文档包在一个 `filesystem()` 条目里 —— 并把 `root`、`include` 或 `exclude` 移进这个条目。简写与 `sources` 不能同时使用；Blume 会指出该把哪个字段移过去。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, mdxRemote } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      // 站点根目录下的本地文档
      filesystem({ root: "docs" }),

      // 来自 GitHub 仓库的远程 MDX，挂载在 /sdk 下
      mdxRemote({
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      }),
    ],
  },
});
```

除 `filesystem()` 外，每个内置适配器都有自己的页面，而 [`custom()`](/docs/content/sources/custom/) 可以接入任何其他后端：

| 适配器 | 读取内容 | 运行时依赖 | 环境变量 |
| --- | --- | --- | --- |
| [`obsidian()`](/docs/content/sources/obsidian/) | 原地读取 Obsidian 仓库 | — | — |
| [`mdxRemote()`](/docs/content/sources/remote-mdx/) | GitHub 仓库或 raw URL 里的 `.md`/`.mdx` | — | `GITHUB_TOKEN`（私有仓库） |
| [`githubReleases()`](/docs/content/sources/github-releases/) | 某个仓库的 Release，转成更新日志条目 | — | `GITHUB_TOKEN`（私有仓库） |
| [`sanity()`](/docs/content/sources/sanity/) | 对 Sanity 数据集执行 GROQ 查询 | `@sanity/client` | `SANITY_TOKEN`（私有数据集） |
| [`notion()`](/docs/content/sources/notion/) | 一个 Notion 数据库 | `@notionhq/client` | `NOTION_TOKEN` |
| [`contentful()`](/docs/content/sources/contentful/) | 一种 Contentful 内容类型 | — | `CONTENTFUL_ACCESS_TOKEN` |
| [`payload()`](/docs/content/sources/payload/) | 一个 Payload 集合 | — | `PAYLOAD_API_KEY` |
| [`strapi()`](/docs/content/sources/strapi/) | 一种 Strapi 内容类型 | — | `STRAPI_API_TOKEN` |
| [`custom()`](/docs/content/sources/custom/) | 你自己实现的任意 `ContentSource` | — | — |

每个接受选项对象的适配器都支持两个共享选项：

- **`prefix`** 把该来源的路由收进 `/<prefix>/…` 命名空间下，这同时也是诊断信息里的来源名称与它的缓存目录名。如果两个来源解析到同一个路由，Blume 会报 `BLUME_DUPLICATE_ROUTE` 构建错误 —— 给每个来源一个不同的 `prefix`。
- **`pollInterval`**（秒）让远程来源在开发环境按该间隔重新拉取，且只在内容确实变化时才重载。不设置就只拉取一次，并在本次会话内冻结。本地来源（`filesystem()`、`obsidian()`）改为监听文件系统，并忽略这个选项。

适配器的描述对象还会声明它需要的 SDK 与读取的环境变量，因此生成的项目会声明那个包，`blume dev` 与 `blume build` 会在变量未设置时给出警告，`blume doctor` 则会列出已配置的来源。选项在配置加载时校验：缺少必填选项、未知键，或残留的 1.x `{ type: "…" }` 对象都会失败，并给出指明修复方式的提示。

单个 `filesystem()` 来源会以它自己的目录作为生成文档集合的根。多个文件系统来源必须共用一个根，并用 `include` glob 划分范围 —— 第二个根在别处的来源会报 `BLUME_ENTRY_ID_MISMATCH`，以免它的页面悄无声息地 404。

## 缓存与离线构建 [#caching-and-offline-builds]

每个远程来源都会在 `.blume/cache/<source>/` 下保留一份快照。如果拉取失败 —— 一次网络抖动或一次 CMS 故障 —— Blume 会带上警告回退到最近一次可用的快照，而不是让构建失败。预览内容与已发布内容各自持有独立快照，每组不同的来源选项也是，所以构建永远不会回退到用 `--preview` 拉到的草稿；修改某个来源的 `query` 或 `fields` 会重新拉取。缓存位于 `.blume/` 内部，会重新生成，永不提交。

在开发环境中，有快照的远程来源会直接从快照提供，因此重启开发服务器不会重新拉取。运行 `blume sync` 拉取最新内容（正在运行的开发服务器会热重载），或用 `blume sync --force` 先丢掉快照。本地文件系统来源照常热重载。若想按间隔轮询远程来源的变化，给它设置共享的 `pollInterval` 选项（秒）—— 开发服务器会在该间隔重新拉取，且只在内容确实变化时才重载。不设置它可以避免工作时反复请求 API。

## 预览与同步

两个标志控制远程内容的拉取方式与包含范围：

- **`--preview`** 加在 `blume dev` 或 `blume build` 上会渲染草稿并拉取未发布的 CMS 内容 —— Sanity 切换到 `previewDrafts` 视角，Notion 不再按 `Status` 过滤，Contentful 走 Preview API 读取，Payload 与 Strapi 请求草稿。不带该标志的生产构建照常排除草稿，因此预览构建是在内容上线前安全审阅未发布工作的方式。
- **`blume sync`** 重新拉取每个远程来源并重新生成运行时。开发环境是缓存优先 —— 远程来源只拉取一次，重启后从 `.blume/cache` 提供（快速且对离线友好），所以 `blume sync` 才是你在不重启开发服务器的情况下拉取最新 CMS 内容的方式（服务器正在运行时会热重载）。加上 `--force` 可以先丢掉缓存，或给某个来源设置 `pollInterval` 以自动刷新。

```sh
blume dev --preview      # 创作流程：实时看到草稿
blume build --preview    # 渲染完整的预览构建
blume sync               # 立即刷新远程内容
blume sync --force       # ……忽略任何已缓存的快照
```

## 渲染与转义

来源会把自己原生的结构（Portable Text、Notion 块、远程 HTML）归一化成 Markdown/MDX 文本，因此无论页面来自哪里，同一批组件与 Markdown 特性都适用。内置适配器在降级转换富文本时会做转义，所以作者在 CMS 里输入的内容 —— 一个 `{`、一个 `<b>`、一段以 `import` 开头的文字，或 `&copy;` —— 都会按原样渲染。链接只保留 `http(s)`、`mailto:`、`tel:` 与相对目标；其他任何协议（`javascript:`、`data:`）都渲染为链接文字，而来源下载的 SVG 图片会在沙箱中提供。`githubReleases()` 的发布说明与 `mdxRemote()` 的文件被视为你自己的内容：它们的原始 HTML 按原样渲染，因此只把它们指向你信任的仓库。

---

# Contentful
Source: https://blume.ndjp.net/docs/content/sources/contentful/
English: https://useblume.dev/docs/content/sources/contentful

内建的 `contentful()` 适配器通过 Content Delivery API 读取某个内容类型的条目，并把每个条目的富文本正文降级为 Markdown：标题、标记、链接、列表、引用、表格和嵌入资源都会映射到对应的 Markdown 写法；而放在 Markdown 长文本字段里的正文会按原样透传，只有一点例外：不是网页、邮件、电话或相对地址的链接（比如一个 `javascript:` URL）只保留它的文字 —— 在富文本里也是这样。无需安装任何东西 —— 适配器直接对话 REST API。

```ts blume.config.ts
import { defineConfig } from "blume";
import { contentful, filesystem } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      contentful({
        prefix: "guides",
        space: "abc123",
        contentType: "guide",
        // environment: "master", locale: "en-US"
        // 字段 id 默认为 title / description / slug / body，
        // 日期默认为 sys.updatedAt
        fields: { body: "content" },
        // 额外的 Delivery API 查询参数
        params: { "fields.section": "sdk" },
      }),
    ],
  },
});
```

Delivery API 的 token 来自 `CONTENTFUL_ACCESS_TOKEN` 环境变量，适配器声明了它。在 `--preview` 下，适配器通过 Preview API 使用 `CONTENTFUL_PREVIEW_TOKEN` 读取草稿。Preview API 会拒绝 delivery token，所以没有预览 token 的 `--preview` 会以明确的错误失败，而不是回退到 `CONTENTFUL_ACCESS_TOKEN`。资源是从 Contentful 的 CDN 引用的，而不是下载下来 —— 它们的 URL 是稳定的。当一个条目被嵌入时，会通过引擎的 `serializers` 选项（以内容类型 id 为键）映射为 Blume 组件，前提是你直接构造 `contentfulSource` 并把它传给 [`custom()`](/docs/content/sources/custom/)；设置 `serializers` 会以 MDX 写出该来源的页面，让返回的组件得以渲染，而没有 serializer 的嵌入条目会记在一条注释里。指向另一个条目的链接会渲染成纯文本，因为没有可指向的路由。

---

# 自定义内容源
Source: https://blume.ndjp.net/docs/content/sources/custom/
English: https://useblume.dev/docs/content/sources/custom

任何实现了 `ContentSource` 接口的对象都可以传给 `custom()`，借助它，带自定义序列化器的适配器——或任何非内置的后端——都能接入进来，而无需其 SDK 触碰核心安装。

```ts blume.config.ts
import { defineConfig } from "blume";
import { custom, filesystem } from "blume/sources";
import { sanitySource } from "blume/sources/sanity.ts";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      custom(
        sanitySource({
          name: "guides",
          prefix: "guides",
          projectId: "abc123",
          dataset: "production",
          query: `*[_type == "guide"]`,
          // 将自定义 Portable Text 块映射为 Blume 组件
          serializers: {
            callout: (block) => `<Callout>${block.text}</Callout>`,
          },
        })
      ),
    ],
  },
});
```

像上面 `sanitySource` 这样用 Blume 某个引擎工厂构建出来的内容源，会在当前运行的命令上下文中重建，因此它在 `--preview` 下读取草稿，并像内置适配器那样把自己的快照保存在 `.blume/cache` 中。你自己的内容源可以实现 `withContext(ctx)`，并返回在该上下文上重建后的自身，从而获得同样的行为。

`custom()` 接收的是一个 `ContentSource` 实例而不是选项对象，因此[共用选项](/docs/content/sources/)里的 `prefix` 和 `pollInterval` 无处可传。内容源自行设置自己的 `prefix` 属性，而重新拉取的行为则由它的 `watch` 方法实现。它携带的是一个活的实例而非纯数据，因此本身不声明任何运行时依赖或密钥——这些由该实例自行管理。

读取本地文件的自定义内容源，应当在每个条目上设置 `sourcePath`，并在内容源自身上设置 `contentRoot`。`sourcePath` 用于在诊断信息中指明文件，并解析它旁边的相对图片；`contentRoot` 限定了为页面标注日期时所用 git `log` 的范围，因此缺少它时，该内容源的页面就拿不到基于 git 推导出的[“最后更新日期”](/docs/configuration/)。

---

# GitHub Releases
Source: https://blume.ndjp.net/docs/content/sources/github-releases/
English: https://useblume.dev/docs/content/sources/github-releases

内建的 `githubReleases()` 适配器把一个仓库的 release 变成更新日志：每个 release 都成为一条 `type: changelog` 条目，所以你的 release notes _就是_你的更新日志 —— 不需要写两遍。配合生成的[更新日志时间线](/docs/advanced/changelog/)，发布一个 GitHub release 就会顺带发出更新日志条目。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, githubReleases } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "content" }),
      githubReleases({
        prefix: "changelog",
        owner: "acme",
        repo: "sdk",
        // prereleases: false,  // 包含预发布版本（默认关闭）
        // drafts: false,       // 包含草稿（需要写权限 token）
        // limit: 100,          // 限制 release 数量，最新的在前
      }),
    ],
  },
});
```

每个 release 会自动映射到更新日志的各个字段：它的名字（或 tag）成为标题，它的发布日期决定时间线顺序，tag 成为 `changelog.version`，预发布版本会被标记为 `Prerelease`（其余为 `Release`）。说明正文会作为条目正文渲染，但链接有两处改动：不是网页、邮件、电话或相对地址的链接（比如一个 `javascript:` URL）只保留它的文字；而指回你自己的 [`deployment.site`](/docs/deployment/) 的链接会被改写成它的根相对路径，从而跟随预览部署和你的部署基础地址。给这个来源设置一个 `prefix`，它的 release 页面就会嵌套在 `/changelog/v1-2-0` 这样的路由下。

私有仓库通过 `GITHUB_TOKEN` 环境变量认证 —— 与其它 GitHub 功能用的是同一个 token，绝不会内联进你的配置；适配器声明了它，所以缺少它的构建会发出警告。和[每个远程来源](/docs/content/sources/)一样，它会缓存在 `.blume/cache/<source>/` 下，并在 API 不可达时以离线方式提供。由于更新日志只是补充内容，一次无缓存情况下的抓取失败（比如没有 token 的 CI 构建）会退化为一份空更新日志并给出警告，而不是让构建失败 —— 在你的 CI 和部署环境里设置 `GITHUB_TOKEN`，它就会被填充。

---

# Notion
Source: https://blume.ndjp.net/docs/content/sources/notion/
English: https://useblume.dev/docs/content/sources/notion

内建的 `notion()` 适配器把一个 Notion 数据库变成一组页面：每一行变成一个页面，它的属性变成 frontmatter，它的块树变成 MDX。标注框、折叠块、分栏和代码块会映射到对应的 Blume 组件，而你在 Notion 里输入的文本会按原样渲染：页面里的 `{`、`<` 或 Markdown 字符会被转义，而不会被当作 MDX、JSX 或格式语法来解析。当视频块里放的是 YouTube 链接时，它会变成一个 `<YouTube>` 嵌入，否则变成一个 `<video>` 播放器；两种情况都以该块的说明文字作为 `<Frame>` 的 caption。指向视频页面而非媒体文件的链接（比如一个 Vimeo 或 Loom URL）会被报告为构建警告，而它的 `<video>` 播放器仍会指向那个无法播放的页面 —— 请改为从正文中链接到那个视频。适配器把 `@notionhq/client`（v5 或更高版本）声明为运行时依赖 —— 一个可选的 peer；Blume 通过它的第一个数据源读取数据库。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, notion } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      notion({
        prefix: "handbook",
        database: "8f2c1e0a4b7d4f3c9e6a5d2b1c0f9e8d", // 数据库 URL 里的 id
        // 属性名默认为 title 类型的属性 / Description / Slug / Order / Status
        // Status 不等于 publishedValue（默认 "Published"）的页面会导入为草稿
        publishedValue: "Done",
      }),
    ],
  },
});
```

集成 token 来自 `NOTION_TOKEN` 环境变量（把数据库共享给你的集成）；适配器声明了它，所以缺少它的构建会发出警告。

`Status` 属性默认是一个发布闸门。Status（状态或单选属性）的取值不等于 `publishedValue`（默认为 `Published`）时，页面会以 `draft: true` 导入，而生产构建会丢弃草稿。Status 没有取值的页面属于已发布，而缺少该属性的数据库会发布所有页面。Notion 的默认状态选项是 Not started、In progress 和 Done，所以一个使用这些选项的数据库没有 `Published` 取值，也就什么都不发布，直到你设置 `publishedValue: "Done"`（或任何代表已发布的那个选项）。`properties.status` 用来指定一个名字不同的属性；想让所有页面无论状态如何都导入，就把它指向一个数据库里并不存在的属性。

**Notion 的图片和视频 URL 带签名且会过期**，所以适配器会在构建时把它们下载到站点的资源目录并改写引用 —— CMS 的资源永远不会拖垮静态构建。只有服务器报告为图片或视频的文件会被保存（或者当响应没有说明时，URL 指向图片或视频扩展名的文件）；其它一切都会保留原始 URL 并给出构建警告，所以除了媒体之外，不会有任何东西从你的站点源上提供。API 调用通过一个小型请求池限流（每次 3 个，与 Notion 每个集成的速率限制一致），这样有几百个页面的数据库也能导入而不触发 `429` 响应；在来源上设置 `concurrency` 可以调整它。

---

# Obsidian
Source: https://blume.ndjp.net/docs/content/sources/obsidian/
English: https://useblume.dev/docs/content/sources/obsidian

内建的 `obsidian()` 适配器会就地读取一个 [Obsidian](https://obsidian.md) vault。没有导出步骤，也不会有任何东西生成到你的仓库里：这个 vault 始终是内容的唯一真实来源，而 Blume 在加载过程中把 Obsidian 的方言降级为 Markdown。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, obsidian } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      obsidian({
        prefix: "notes",
        vault: "vault",
        // 任意深度都要跳过的 vault 文件夹名，点开头的文件夹之外
        exclude: ["Templates", "Daily"],
      }),
    ],
  },
});
```

`[[Wikilinks]]` 会变成路由链接，按整个 vault 中的笔记名寻址，而不是按路径 —— 这正是 Obsidian 寻址笔记的方式。自定义链接文字（`[[Note|label]]`）、标题锚点（`[[Note#Install]]`）、完整路径（`[[folder/Note]]` 和 `[[folder/Note.md]]`）、Obsidian 默认「尽可能短的路径」设置写出的部分路径（`[[guides/Note]]`），以及 Obsidian 在表格单元格中写下的 `[[Note\|label]]` 形式都能正常工作；而在 frontmatter 中设置了 `slug` 的笔记，会链接到该 slug 发布出来的路由。当两个笔记同名时，完整 vault 路径恰好等于该名字的笔记优先 —— Obsidian 会先把链接解析成路径、再解析成名字 —— 其次是 vault 顺序中靠前的那个（文件夹优先于笔记，不区分大小写，就像 Obsidian 的文件浏览器那样）。只有当一个 wikilink 真的通过这种冲突被解析时，Blume 才会警告；写一条更长的路径来消歧。块引用（`[[Note#^id]]`）会链接到所属笔记但不带锚点：块渲染出来并没有可落点的 id。标题锚点则针对目标笔记的真实标题来解析，匹配方式与 Obsidian 自动补全写出的形式一致（去掉 `**bold**`、`` `code` `` 与链接语法），并由填充页面清单的同一个 `extractHeadings` 流程生成 slug —— 所以指向 `#Install` 的链接会落在标题上，而不是落在一个没有任何页面会输出的 id 上。`[[#Install]]` 指向你正在写的这篇笔记里的某个标题。指向不存在标题的链接会保留页面链接、丢弃锚点并给出警告。

Frontmatter 会保留 Blume 的[页面 schema](/docs/content/frontmatter/)所接受的一切，再加上你在 [`frontmatter.extend`](/docs/content/frontmatter/) 中声明的任意键（或者，对于该 `type` 的笔记，是某个内容类型的 `frontmatter`）；其余所有 Obsidian 属性 —— Dataview 字段、Templater 日期、`publish`，以及 Obsidian 自己的 `tags`、`aliases` 和 `cssclasses` —— 都会在笔记被降级时丢弃，所以一个用 Properties UI 写成的仓库也能在没有 frontmatter 报错的情况下构建。`aliases` 是被丢弃而不是被解析 —— 目前还不支持别名链接目标。笔记旁边的相对 Markdown 图片（`![chart](./chart.png)`）会直接从 vault 中提供；当 vault 位于你的 git 仓库内部时，vault 里的页面会像其他任何页面一样获得从 git 推导出的[「最后更新」日期](/docs/configuration/)。「编辑此页」链接通过 `github.dir` 解析，因此在 monorepo 中与文档应用并列的 vault 依然能链接到自己的文件；位于仓库之外的 vault 不会得到链接。

vault 内的语言目录和版本快照，其读取方式与文件系统来源相同：`fr/Note.md` 在配置了 [i18n](/docs/content/i18n/) 后发布到 `/fr/` 下，`v1.0/Note.md` 在配置了[版本](/docs/content/versioning/)后发布到 `/v1.0/` 下，而指向这些笔记的 wikilink 会指向各自发布出来的路由。

指向 `index` 笔记的链接会落到它所在文件夹的路由上，而不是一个并不存在的 `/index`。**无法解析的 wikilink 会退化为纯文本并给出构建警告，而不是让构建失败**，所以一个正在重构中途的仓库依然能发布。单行 `%%comments%%` 会被剥离，写在 HTML 注释里的 wikilink（`<!-- [[Draft]] -->`）原样保留，因为 Obsidian 也会把它藏起来；frontmatter 中没有 `title` 的笔记会以文件名作为标题 —— 这正是 Obsidian 自己采用的规则。`index` 笔记是唯一的例外：它命名的是一个路由而不是一篇笔记，所以它的标题会回落到 Blume 惯用的推导方式（先取第一个标题，再取人性化处理的路径段）。围栏代码块、缩进代码块和行内代码都逐字保留，所以一篇记录语法的笔记能完好存活。

点开头的文件夹会被跳过，包括 Obsidian 自己的 `.obsidian` 配置目录和 `.trash` —— 开发模式的 watcher 也会忽略它们，所以在应用里挪动一个面板，或者把笔记删进回收站，都不会重建你的站点。而编辑笔记会。内容扫描不会读取的目录（`node_modules`、`dist`、`.git` 等）同样会被跳过，所以一个以项目自身为根的 vault 不会发布依赖包自带的 README。路径中含有 `#` 或 `?` 的笔记会带着一个错误被排除在外，和[内容文件](/docs/content/)一样：Astro 无法加载它的副本，所以给它换个名字。vault 内部的符号链接会被跟随，就像文件系统来源会跟随它们一样，所以链进 vault 的共享文件夹会随之一起发布。位于文件系统来源根目录内部的 vault 必须被排除掉（`filesystem({ root: "docs", exclude: ["**/_*", "**/.*", "vault/**"] })` —— `exclude` 会替换默认的 `["**/_*", "**/.*"]`，而不是追加上去，所以要保留这两项，好让 `_` 前缀的 partial 和点文件保持不发布）；随后 [`blume version <id>`](/docs/cli/version/) 也会把它排除在快照之外，因为这个 vault 会继续把自己的笔记作为当前版本发布。

尚未降级的部分：标注框（`> [!note]`）会渲染成普通引用块，嵌入（`![[image.png]]`）原样透传，多行 `%%comments%%` 保留在原位，并且没有反向链接图。

---

# Payload
Source: https://blume.ndjp.net/docs/content/sources/payload/
English: https://useblume.dev/docs/content/sources/payload

内建的 `payload()` 适配器通过 Payload REST API（`/api/<collection>`）读取一个集合，并把每个文档的 Lexical 正文降级为 Markdown：段落、标题、项目符号列表、编号列表、勾选列表、引用、链接、上传文件和水平分隔线。放在文本字段里的正文会按 Markdown 原样透传，只有一点例外：不是网页、邮件、电话或相对地址的链接只保留它的文字。无需安装任何东西。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, payload } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      payload({
        prefix: "handbook",
        url: "https://cms.example.com",
        collection: "docs",
        // 字段路径默认为 title / description / slug / content / updatedAt
        fields: { body: "richText" },
        // 额外的查询参数：where[...], sort
        params: { sort: "title" },
      }),
    ],
  },
});
```

API key 来自 `PAYLOAD_API_KEY` 环境变量，并以 `users API-Key <key>` 的形式发送；当这个 key 属于另一个启用了认证的集合时，设置 `authCollection`。只有已发布的文档会被导入 —— `--preview` 会请求草稿并以 `draft: true` 暂存它们。文档以 `depth: 1` 抓取，因此上传文件会带上自己的 URL，而相对的上传路径（`/media/x.png`）会相对于 `url` 解析。`block` 或 `inlineBlock` 节点通过引擎的 `serializers` 选项（以 `blockType` 为键）映射为 Blume 组件，前提是你直接构造 `payloadSource` 并把它传给 [`custom()`](/docs/content/sources/custom/)。设置 `serializers` 会以 MDX 写出该来源的页面，让返回的组件得以渲染；放在 Markdown 文本字段里的正文则仍是 Markdown。

---

# 远程 MDX
Source: https://blume.ndjp.net/docs/content/sources/remote-mdx/
English: https://useblume.dev/docs/content/sources/remote-mdx

内建的 `mdxRemote()` 适配器通过 HTTP 抓取原始的 `.md`/`.mdx`。文件列表既可以从 GitHub 仓库的某个子树枚举（`github`），也可以针对一个 raw 基础 URL 显式指定（`url` + `files`）：

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, mdxRemote } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      // acme/sdk 的 docs/ 子树，挂载到 /sdk 下
      mdxRemote({
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      }),
    ],
  },
});
```

如果你想自己列出文件，把 `url` 指向一个 raw 基础 URL：

```ts blume.config.ts
mdxRemote({
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
});
```

私有仓库的 token 从 `GITHUB_TOKEN` 环境变量读取 —— 适配器声明了它，所以未设置时 `blume dev` 和 `blume build` 会发出警告。它绝不会被内联进你的配置或生成的产物中，而且只会发往 GitHub 自己的主机（`api.github.com`、`raw.githubusercontent.com`），绝不会发往自定义的 `url` 基础地址。公共仓库不需要它也能工作。

远程页面以完整的 MDX 加组件保真度渲染：它们的正文会被实体化到一个隐藏的暂存目录中，并通过 Astro 与你的本地文档一起渲染，所以标注框、标签页以及其它所有 Blume 组件都能继续工作。

和每个远程来源一样，抓取到的页面会被缓存以支持离线构建，并用 `blume sync` 刷新 —— 参见[缓存与离线构建](/docs/content/sources/)。

---

# Sanity
Source: https://blume.ndjp.net/docs/content/sources/sanity/
English: https://useblume.dev/docs/content/sources/sanity

内建的 `sanity()` 适配器会执行一条 GROQ 查询，把每个文档的字段映射为 frontmatter，把它 Portable Text 的正文映射为 Markdown。适配器把 `@sanity/client` 声明为运行时依赖 —— 一个可选的 peer，所以只有在你使用这个来源时才需要安装。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, sanity } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      sanity({
        prefix: "guides",
        projectId: "abc123",
        dataset: "production",
        query: `*[_type == "guide"]`,
        // 字段路径默认为 title / slug.current / body / _updatedAt
        fields: { slug: "slug.current", body: "content" },
      }),
    ],
  },
});
```

私有数据集的读取 token 来自 `SANITY_TOKEN` 环境变量，适配器声明了它。自定义 Portable Text 块类型通过引擎的 `serializers` 选项映射为 Blume 组件 —— 当你直接构造 `sanitySource` 并把它传给 [`custom()`](/docs/content/sources/custom/) 时可用。设置 `serializers` 会以 MDX 写出该来源的页面，所以 serializer 返回的组件或指令都能渲染出来。

---

# Strapi
Source: https://blume.ndjp.net/docs/content/sources/strapi/
English: https://useblume.dev/docs/content/sources/strapi

内建的 `strapi()` 适配器通过 Strapi REST API（`/api/<pluralApiId>`）读取一个内容类型，并把每个条目的 Blocks 正文降级为 Markdown：段落、标题、列表、引用、代码块、图片和链接。Markdown 富文本字段会按原样透传，只有一点例外：不是网页、邮件、电话或相对地址的链接只保留它的文字。Strapi 5 的响应会按原样读取，而 Strapi 4 的 `attributes` 外层结构会被摊平，这样同样的字段路径依然适用。无需安装任何东西。

```ts blume.config.ts
import { defineConfig } from "blume";
import { filesystem, strapi } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      strapi({
        prefix: "guides",
        url: "https://cms.example.com",
        contentType: "guides",
        // locale: "en"
        // 字段路径默认为 title / description / slug / content / updatedAt
        fields: { body: "body" },
        // 额外的查询参数：filters[...], sort
        params: { "filters[section][$eq]": "sdk" },
      }),
    ],
  },
});
```

API token 来自 `STRAPI_API_TOKEN` 环境变量，并以 bearer token 的形式发送。条目以 `populate=*` 抓取，因此图片会带上自己的 URL（设置 `populate` 可以收窄它），而相对的上传路径（`/uploads/x.png`）会相对于 `url` 解析。只有已发布的条目会被导入 —— `--preview` 会请求草稿（Strapi 5 上是 `status=draft`，Strapi 4 上是 `publicationState=preview`），并把每个从未发布过的文档以 `draft: true` 暂存；已发布的文档则预览其最新的草稿。

---

# 语法
Source: https://blume.ndjp.net/docs/content/syntax/
English: https://useblume.dev/docs/content/syntax

Blume 以标准 Markdown 和 MDX 为基础，提供一套精选过的 GitHub 风格特性 —— 无需 import，无需配置。像平时一样写内容即可；本页展示了所有受支持的语法，每一项都配有实时预览和对应源码。

## 标题 [#headings]

用标题组织页面结构。Blume 会把 frontmatter 的 `title` 渲染为页面标题，所以正文从 `##` 开始 —— `##` 和 `###` 会成为目录中的条目。`##`–`######` 的每个标题还会被包在一个指向自身锚点的链接里，因此读者可以点击标题来复制、收藏，或分享直达该小节的永久链接（悬停时会显出 `#`）。在 `blume.config.ts` 中设置 `markdown: { headingAnchors: false }` 可关闭这一行为。

```md
## Section

### Subsection

#### Detail
```

### 自定义锚点 [#custom-anchors]

锚点 id 由标题文本生成，所以标题一旦改写，锚点也会跟着变。改为在末尾追加 `[#custom-id]`，就能把锚点固定下来 —— 这个标记不会出现在渲染结果中，而且无论标题怎么写，链接都照常有效。固定锚点在[翻译语言版本](/docs/content/i18n/)中也会保持一致，而自动生成的 id 原本会因语言而异。

```md
## Getting started [#setup]
```

按 `/page#setup` 链接到它。这个语法与 Fumadocs 一致，迁移过来的内容可以原样使用。

Pandoc、kramdown 以及基于 Markdown 的规范工具链所用的 `{#custom-id}` 写法，在 `.md` 文件里同样被接受为等价形式。而在 `.mdx` 里，裸写的 `{…}` 会被当成 JSX 表达式，页面将无法编译 —— `blume check` 会把这个标记报告为 `BLUME_MDX_CURLY_ANCHOR` —— 所以请在 `.mdx` 中写 `[#custom-id]`，或者把花括号转义。转义写法在两种格式里都会固定同一个锚点，因此对于被 `.mdx` 页面[引入](/docs/content/includes/)的片段来说，它是正确的拼写方式：

```md
## Getting started \{#setup\}
```

片段链接也可以指向带 `id` 的原生 HTML 元素（`<a id="setup"></a>`）；`blume validate` 既接受标题锚点，也接受这类写法。

### 目录标记 [#table-of-contents-markers]

还有两个位于标题末尾的标记，用来控制标题在目录中的呈现方式。`[!toc]` 让标题保留在正文中、但不出现在目录里；`[toc]` 则相反 —— 标题只出现在目录中，作为一个不可见的锚点目标，这适合给由组件而非正文构成的小节命名。标记可以按任意顺序叠加使用。有一个例外，这沿袭自 CommonMark：如果某个末尾方括号里的标签在页面任意位置存在链接引用定义（`[toc]: /url`），它就是快捷引用链接而不是标记，会原样留在标题文本中。

```md
## Appears on the page only [!toc]

## Appears in the TOC only [toc]

## Both markers together [toc] [#custom-id]
```

标记总是会被解析 —— 标题若恰好以形似标记的文字结尾，就会被当作加了标记。用反斜杠转义没有用（Markdown 在解析标记之前就已把 `\[` 解析成 `[`）；若要在标题末尾原样显示标记文字，请用行内代码包起来：`` ## 使用 `[toc]` ``。

## 强调 [#emphasis]

用于强调词语、标记删除，以及在句子中间展示代码或按键。

**粗体**、_斜体_、~~删除线~~ 和 `行内代码`。

```md
**Bold**, _italic_, ~~strikethrough~~, and `inline code`.
```

## 键盘按键 [#keyboard-keys]

用于快捷键和按键输入。`<kbd>` 元素会渲染成与搜索对话框所用的按键徽标相同的带边框样式，在 Markdown、MDX 中以及 `<Steps>`、`<Callout>` 这类组件内部都可用。

按 <kbd>⌘</kbd> <kbd>K</kbd> 打开搜索，或按 <kbd>Esc</kbd> 关闭。

```md
Press <kbd>⌘</kbd> <kbd>K</kbd> to open search, or <kbd>Esc</kbd> to close it.
```

## 上标与下标 [#superscript-and-subscript]

用于脚注标记、序数，以及科学或化学记号。

E = mc^2^ 与 H~2~O。

{/* prettier-ignore */}
```md
E = mc^2^ and H~2~O.
```

## 引用块 [#blockquotes]

把引文、提示框旁注或编者按与周围正文区分开。

> 快、AI 友好、零配置的文档 —— 连模板都是如此。

```md
> Documentation that's fast, AI-ready, and zero-config — down to the template.
```

## 列表 [#lists]

无序集合用无序列表，有先后顺序的序列用有序列表，清单和路线图用任务列表。

- 以 Markdown 为先的写作方式
- 默认输出静态站点
  - 按需启用服务端特性
- 产出归你所有

1. 安装 Blume
2. 写一个页面
3. 发布上线

- [x] 搭建项目骨架
- [ ] 写第一篇指南

```md
- Markdown-first authoring
- Static by default
  - Opt into server features
- Own your output

1. Install Blume
2. Write a page
3. Ship it

- [x] Scaffold the project
- [ ] Write the first guide
```

## 表格 [#tables]

把结构化数据整理成表格 —— 配置项、对比矩阵、参数列表。在分隔行里用冒号来对齐列。

| 命令          | 说明                 | 输出     |
| ------------- | -------------------- | :------: |
| `blume dev`   | 启动开发服务器       |    —     |
| `blume build` | 构建静态站点         | `dist/`  |

```md
| Command       | Description           | Output  |
| ------------- | --------------------- | :-----: |
| `blume dev`   | Start the dev server  |    —    |
| `blume build` | Build the static site | `dist/` |
```

如果要做一个没有表头的表格 —— 比如键值对 —— 把表头单元格留空即可。Markdown 在语法上要求存在表头行和分隔行，但 Blume 会从渲染结果中去掉这个空表头。

```md
|                |          |
| -------------- | -------- |
| Current status | E-3 visa |
```

## 链接与图片 [#links-and-images]

链接到其他页面或外部站点。图片可以写内容文件旁边的相对路径、`public/` 下的任意路径（在站点根路径下提供），或远程 URL。

相对页面链接（`./install`、`../guides/setup`）从该页面自身所在的文件夹解析 —— 对于索引页，就是它所引入的那个文件夹 —— 而指向 Markdown 文件的链接（`./setup.md`、`../intro.mdx`）会落到该文件所发布的页面，并带上它的 `slug`。带点的页面名（例如 `node.js.mdx` 页面写作 `./node.js`）只要在那里发布了页面，就算作页面链接；组件上的字符串 `href`（`<Card href="./install">`）也按同样的方式解析。Blume 会把每一条都写成构建后页面中的根相对路由，所以为 GitHub 或 Docusaurus 编写的链接依然有效，[`blume validate`](/docs/cli/validate/) 也用同样的规则来检查它们。

先阅读[快速上手](/docs/quickstart/)开始吧。

```md
Read the [quickstart](/docs/quickstart) to get started.

![Alt text](./screenshot.png)
```

外部链接默认在当前标签页打开。在 `blume.config.ts` 中设置 `markdown: { externalLinks: true }` 就能让它们在新标签页打开 —— Blume 的页头和侧边栏链接已经这样做了：每一条绝对的 `https://` 或 `//host` 链接都会加上 `target="_blank"` 和 `rel="noreferrer"`、在文字后加一个小箭头，并附一条供屏幕阅读器识别的说明，提示它会在新标签页打开。指向你自己页面的链接、`#片段` 以及 `mailto:`/`tel:` 链接仍留在当前标签页，原生 `<a>` 标签也一样 —— 它会保留你写下的属性。

**本地图片请优先使用相对路径** —— 它们会在构建时完成优化：压缩、转换为 WebP，并写入图片自身的 `width`/`height`，这样页面加载时不会发生位移。把图片放在使用它的页面旁边（或放在内容目录下某个共享文件夹里），并用相对路径引用：

```md
![Build output](./images/build-output.png)
```

`public/` 下的绝对路径（`![Alt text](/screenshot.png)`）会原样提供、不做任何优化 —— 请把它留给必须保持字节和 URL 完全一致的文件，比如文档之外引用的 logo。远程图片同样原样透传，除非它们的主机在 [`image` 配置](/docs/configuration/)中被授权。

正文图片默认可以点击放大 —— 读者点击任意一张图都能在灯箱中打开。在 `blume.config.ts` 中设置 `markdown: { imageZoom: false }` 可关闭这一行为，也可以在单张图片上用 `data-no-zoom` 选择退出。

## 分隔线 [#horizontal-rule]

在长页面中分隔主题的大幅转换。

---

```md
---
```

## 代码块 [#code-blocks]

围栏代码块带语法高亮，页眉会显示语言 —— 已知语言还会带品牌图标 —— 并提供复制按钮。在语言之后加一个**标题**（通常是文件名），它会替换页眉中的语言标签。

```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```

````md
```ts blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
});
```
````

行内代码同样可以高亮：在反引号跨度里加上 `{:lang}` 标记，它就会像一小段代码块那样着色 —— 例如 `useState(){:js}` 或 `T extends object{:ts}`。只有你加上标记时它才会生效，因此普通的行内代码不受影响 —— 无需任何开关。

高亮默认使用 `github-light`/`github-dark` 主题。用 `markdown.code.theme` 可以按色彩模式换成任意一个[内置 Shiki 主题](https://shiki.style/themes) —— 它会一次性为所有代码表面着色（围栏、行内片段、`<CodeBlock>` 和 `<Diff>`）：

```ts blume.config.ts
export default defineConfig({
  markdown: {
    code: {
      theme: { light: "github-light", dark: "vesper" },
    },
  },
});
```

你也可以直接提供自定义的 [Shiki 主题定义](https://shiki.style/guide/load-theme)。导入一个兼容 VS Code 的主题 JSON 文件（如果运行时要求，就使用 import attribute），再把它赋给任一色彩模式；内置名称与自定义定义可以混用：

```ts blume.config.ts
import darkTheme from "./themes/acme-dark.json" with { type: "json" };

export default defineConfig({
  markdown: {
    code: {
      theme: { light: "github-light", dark: darkTheme },
    },
  },
});
```

### 行号 [#line-numbers]

追加 `lineNumbers` 可以渲染行号栏 —— 单独使用，或与标题一起使用：

```ts server.ts lineNumbers
import { createServer } from "node:http";

createServer().listen(3000);
```

````md
```ts server.ts lineNumbers
import { createServer } from "node:http";

createServer().listen(3000);
```
````

### 长行与长代码块 [#long-lines-and-long-blocks]

追加 `wrap` 可以让单个代码块里的长行自动换行，而不是横向滚动：

```ts client.ts wrap
const client = createClient({
  baseUrl: "https://api.example.com/v1",
  retries: 3,
  timeout: 10_000,
  headers: { "x-client": "docs" },
});
```

````md
```ts client.ts wrap
const client = createClient({
  baseUrl: "https://api.example.com/v1",
  retries: 3,
  timeout: 10_000,
  headers: { "x-client": "docs" },
});
```
````

给较长的代码块追加 `expandable`，会先显示它的前几行，下方配一个**展开更多**开关。展开后代码块完整显示，内部不会出现滚动。少于 16 行的代码块按常规渲染，因为几乎没内容可藏。

```ts routes.ts expandable
import { defineRoutes } from "./router";

export default defineRoutes({
  home: "/",
  docs: "/docs",
  guides: "/docs/guides",
  reference: "/docs/reference",
  changelog: "/changelog",
  blog: "/blog",
  pricing: "/pricing",
  about: "/about",
  careers: "/careers",
  contact: "/contact",
  privacy: "/legal/privacy",
  terms: "/legal/terms",
  security: "/security",
  status: "https://status.example.com",
});
```

````md
```ts routes.ts expandable
import { defineRoutes } from "./router";

export default defineRoutes({
  // …every route
});
```
````

两者都可以与标题和 `lineNumbers` 一起使用。若想让所有代码块都换行，改为设置 `markdown.code.wrap`。

### 高亮 [#highlighting]

用 GitHub 风格注释标注代码，可以把注意力引向特定的行、词和改动。这些注释会从渲染结果中剥离，因此代码复制粘贴后依然干净。以下四种全部默认开启 —— 无需配置。

用 `// [!code highlight]` 标记某一行，为它加上高亮背景：

```ts
const config = defineConfig({
  title: "My docs", // [!code highlight]
});
```

用 `// [!code ++]` 表示新增、`// [!code --]` 表示删除，渲染为绿/红色的 diff：

```ts
export default defineConfig({
  title: "My docs", // [!code --]
  title: "Blume docs", // [!code ++]
});
```

用 `// [!code word:createServer]` 高亮该行中某个词的每一处出现：

```ts
import { createServer } from "node:http"; // [!code word:createServer]

createServer().listen(3000);
```

用 `// [!code focus]` 标记的行保持清晰，其余内容全部变暗（悬停时恢复锐利）：

```ts
export default defineConfig({
  title: "My docs", // [!code focus]
  description: "Built with Blume",
});
```

也可以按**行号**而不是按注释来高亮 —— 在你无法编辑代码时这很有用。在语言之后写一个花括号范围；单行、逗号列表和 `start-end` 区间都可以：

```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```

````md
```ts {1,4-5}
import { defineConfig } from "blume";

export default defineConfig({
  title: "My docs",
  description: "Built with Blume",
});
```
````

### 类型展示 [#display-types]

给 TypeScript 代码块加上 `twoslash` 标记，即可直接展示编译器给出的真实类型 —— 由 [Twoslash](https://shiki.style/packages/twoslash) 提供支持。把鼠标悬停在任意 token 上即可查看推断出的类型；再补一条行内 `^?` 查询，就能把某个类型钉在该行下方。

```ts twoslash
const config = {
  title: "My docs",
  version: 1,
};

config.title;
//     ^?
```

````md
```ts twoslash
const config = { title: "My docs", version: 1 };

config.title;
//     ^?
```
````

### TypeScript 与 JavaScript 标签页 [#typescript-and-javascript-tabs]

给 `ts` 或 `tsx` 代码块加上 `ts2js` 标记，就会把它渲染成一对标签页：你的 TypeScript 与自动生成的 JavaScript 版本并列展示，你只需维护一份代码片段，读者自选方言。转换会去掉类型语法和纯类型导入，同时完整保留你的格式、注释和 JSX —— 而且标签页是同步的，所以在页面上任意一处切到 JavaScript，所有代码块对都会一起切换。和图表、数学公式一样，这是仅 MDX 可用的特性 —— 在 `.md` 文件中，该代码块会渲染为普通的 TypeScript 围栏。

```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```

````md
```ts ts2js
import { defineConfig } from "blume";

interface Author {
  name: string;
}

const author: Author = { name: "Hayden" };

export default defineConfig({
  title: `${author.name}'s docs`,
});
```
````

其他围栏元信息可以组合使用：`title="..."` 会在两个标签页上都显示，而 `{1,4-5}` 这样的行号范围只作用于 TypeScript 标签页（去掉类型后行号会偏移）。唯一的例外是 `twoslash` —— 悬停类型无法带到生成的代码里，因此同时标注两者的代码块仍然是普通的 Twoslash 代码块。

:::note
在 `blume.config.ts` 中设置 `markdown: { code: { icons: false, wrap: true } }`，可以隐藏语言图标，或让长行换行而不是横向滚动。
:::

## 包安装 [#package-install]

`package-install` 代码块能把一条安装命令变成 npm、pnpm、yarn、bun、nub 和 aube 六种选项卡形式的代码片段 —— 读者复制与自己的环境匹配的那一条即可。和图表、数学公式一样，这是仅 MDX 可用的特性 —— 在 `.md` 文件中，该代码块会渲染为普通的代码围栏。

```package-install
npm i blume
```

````md
```package-install
npm i blume
```
````

## 图表 [#diagrams]

`mermaid` 代码块可以直接从文本渲染出 [Mermaid](https://mermaid.js.org) 图表。围栏内的内容会原样传给 Mermaid，因此 Mermaid 支持的任何图表类型在这里都能用。图表会跟随当前色彩主题，并在主题变化时重新渲染。用 `mermaid` 围栏包住源码即可编写：

````md
```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```
````

图表在客户端渲染，因此这是仅 MDX 可用的特性；而且 Mermaid 库只会在包含图表的页面上加载 —— 站点里没有图表就完全不会带上它。图表默认使用 Mermaid 的 dagre 布局和 classic 外观；要让单个图表改用其他布局或外观，可以通过 Mermaid front matter（一个带 `layout: elk` 或 `look: neo` 的 `config:` 块）来选择，而 ELK 引擎也只会为需要它的图表加载。本节其余部分是常见类型的图库 —— 完整列表请见 [Mermaid 文档](https://mermaid.js.org/intro/)。

### 流程图 [#flowchart]

```mermaid
flowchart LR
  A[Markdown] --> B{blume build}
  B --> C[Static HTML]
  B --> D[llms.txt]
```

### 时序图 [#sequence-diagram]

```mermaid
sequenceDiagram
  participant R as Reader
  participant B as Blume
  R->>B: Request /docs
  B-->>R: Prerendered HTML
```

### 类图 [#class-diagram]

```mermaid
classDiagram
  class Page {
    +string title
    +string route
    +render()
  }
  Page <|-- Doc
  Page <|-- Changelog
```

### 状态图 [#state-diagram]

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: build
  Published --> [*]
```

### 实体关系图 [#entity-relationship]

```mermaid
erDiagram
  PAGE ||--o{ HEADING : contains
  PAGE {
    string title
    string route
  }
```

### 用户旅程图 [#user-journey]

```mermaid
journey
  title Publishing a page
  section Write
    Draft MDX: 5: Author
  section Ship
    blume build: 4: Author
    Deploy: 3: Author
```

### 甘特图 [#gantt]

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Docs
    Draft   :a1, 2026-01-01, 7d
    Review  :after a1, 3d
```

### Git 提交图 [#git-graph]

```mermaid
gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit
```

### 饼图 [#pie-chart]

```mermaid
pie title Content types
  "Docs" : 70
  "Blog" : 20
  "Changelog" : 10
```

### 思维导图 [#mindmap]

```mermaid
mindmap
  root((Blume))
    Content
      MDX
      Markdown
    Build
      Static HTML
      llms.txt
```

### 时间线 [#timeline]

```mermaid
timeline
  title Blume milestones
  2025 : Prototype
  2026 : 1.0 release
```

## 提示框 [#callouts]

提示框用于把读者的注意力引向背景信息、建议或风险。写作时使用 `:::type` 指令；可以在方括号里加一个标题，比如 `:::warning[注意]`。这些指令是仅 MDX 可用的特性 —— 在 `.md` 文件里，`:::note` 这一行只会保留为普通文本。

### Note [#note]

中性的补充背景，读者应当留心记住。

:::note
Blume 每次运行都会重新生成 `.blume/` —— 切勿手动编辑它。
:::

```md
:::note
Blume regenerates `.blume/` on every run — never edit it by hand.
:::
```

### Tip [#tip]

不是必需、但能让事情更轻松的便捷技巧或最佳实践。

:::tip
设置 `deployment.site`，让站点地图和 Open Graph 图片使用绝对 URL。
:::

```md
:::tip
Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
:::
```

### Success [#success]

确认一个正向结果，或确认某一步已按预期完成。

:::success
你的文档构建成功，可以部署了。
:::

```md
:::success
Your docs built successfully and are ready to deploy.
:::
```

### Warning [#warning]

标出需要小心处理的地方，以免出错或出现意外行为。

:::warning[注意]
服务端输出需要先从 `blume/deploy` 引入一个宿主适配器才能部署。
:::

```md
:::warning[Heads up]
Server output needs a host adapter from `blume/deploy` before you can deploy.
:::
```

### Danger [#danger]

指出破坏性、或会造成不兼容变更且难以撤销的操作。

:::danger
`blume eject` 是一条单行道 —— 生成的 Astro 项目从此归你所有。
:::

```md
:::danger
`blume eject` is a one-way step — the generated Astro project becomes yours.
:::
```

### Info [#info]

信息性的旁注；一个便于用别名替代、语气中立的默认选项。

:::info
核心主题不包含任何客户端框架 JS。
:::

```md
:::info
The core theme ships no client framework JS.
:::
```

`caution`、`error`、`important` 和 `warn` 这几个名字会分别作为 `warning`、`danger`、`note` 和 `warning` 的别名被接受。

其它名字则不是提示框。它的内容照样会渲染 —— 位于那两行 `:::` 之间，而这两行会按原样留在页面上 —— 所以从别的文档工具沿用过来的 `:::details`，或像 `:::warnig` 这样的拼写错误，都不会把里面的内容藏起来。`blume dev`、`blume build` 和 `blume check` 会以 `BLUME_UNKNOWN_DIRECTIVE` 提示这一点，并列出上面那些提示框类型。

要把一个提示框放进另一个里面，就把外层的围栏加长：

```md
::::note
Blume regenerates `.blume/` on every run.

:::tip
Commit `blume.config.ts`, not `.blume/`.
:::
::::
```

## 数学公式 [#math]

用 KaTeX 渲染 LaTeX，适合数学公式密集或偏科学的文档。把 `$$…$$` 单独放在一行，可以得到居中的块级公式：

$$
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

```md
$$
a^2 + b^2 = c^2
$$
```

或者把 `$$…$$` 写在句子中间，用作行内公式，比如欧拉恒等式 $$e^{i\pi} + 1 = 0$$：

```md
Like Euler's identity $$e^{i\pi} + 1 = 0$$.
```

:::note
数学公式是自动开启的：写了 `$$…$$` 就会渲染，一个不写就绝不会加载 KaTeX 的样式表。块级公式和行内公式都用两个美元符号。单个 `$`（货币、shell 变量、代码）永远按字面文本处理，所以 "$5 and $10" 不会被当成公式；也不需要转义定界符，更没有开关可切。数学公式是仅 MDX 可用的特性。渲染出的标记里的类名（`.katex-html`、`.katex-base` 等）是 KaTeX 自身的内部实现，而不是 Blume 承诺保持稳定的样式契约 —— 它们可能随 KaTeX 升级而变化，所以自定义样式请作用在 `.katex-display` 外层上。
:::

## 智能标点 [#smart-punctuation]

Blume 会在你写作时把直角引号和连字符转换成排印符号中对应的字符，因此正文读起来像是经过排版 —— 无需任何特殊字符。

"引号" 会变成弯引号，-- 变成连接号（en dash），--- 变成破折号（em dash），... 变成省略号。

```md
"Quotes" become curly, -- becomes an en dash, --- an em dash, and ... an ellipsis.
```

---

# 变量
Source: https://blume.ndjp.net/docs/content/variables/
English: https://useblume.dev/docs/content/variables

只需定义一次值，即可在每个页面中使用。版本号、API 主机或产品名写在 `blume.config.ts` 里，页面中的 `{{name}}` 会读取它的值：

```ts blume.config.ts lineNumbers
export default defineConfig({
  variables: {
    version: "2.1.0",
    "api-url": "https://api.example.com",
  },
});
```

```mdx docs/quickstart.mdx
Install version {{version}}, then call {{api-url}}.

## What's new in {{version}}

<Card title="Release {{version}}" href="{{api-url}}/changelog" />
```

引用在散文中、标题里、链接中、代码块中、行内代码里以及组件属性里都有效，`.md` 和 `.mdx` 页面以及它们 [include](/docs/content/includes/) 的文件都不例外。花括号里加空格也没问题（`{{ version }}`）。在配置中改掉这个值，下一次构建时每个页面都会取到新值。

名称可包含字母、数字、`_` 和 `-`。值是单行的纯文本。

## 生效范围

变量会在任何内容读取页面之前完成替换，因此渲染出的 HTML、[搜索](/docs/configuration/search/)、页面的 [`.md` 镜像](/docs/discoverability/markdown/) 和 `llms-full.txt` 里显示的都会是替换后的值。

frontmatter 保持原样：其中含 `{{version}}` 的 `title` 或 `description` 会原样显示花括号。

## 未定义的名称

散文中出现未定义的 `{{name}}` 会导致构建错误 `BLUME_UNDEFINED_VARIABLE`，并在其所在行报告，这样拼写错误不会传到读者手里。在代码块或行内代码中，未定义的名称会保持原样，因为那里常有 Handlebars `{{title}}` 这类模板示例。

想在散文中展示一个引用但不定义它，就把它放进行内代码：`` `{{name}}` ``。

没有定义任何变量的站点不受影响：其页面中的 `{{…}}` 会保持原样。

---

# 版本管理
Source: https://blume.ndjp.net/docs/content/versioning/
English: https://useblume.dev/docs/content/versioning

Blume 按照发布本身的运作方式来管理文档版本：最新文档位于内容根目录，使用干净、无前缀的 URL；每个历史版本都是各自文件夹中的一份冻结快照。发布时切出一份快照，Blume 就会为你接好版本切换器、“旧版本”提示、搜索范围、SEO 以及面向 agent 的接口。它是可选的：没有 `versions` 块，一切保持原样。

## 启用

添加一个 `versions` 块，声明当前文档以及任何已归档的快照：

```ts blume.config.ts lineNumbers
versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}
```

`current` 用来在切换器中标注那棵无前缀的目录树（可搭配一个可选的 `badge`）。每个归档条目的 `id` 既是快照的目录名，也是它的 URL 片段——id 必须以字母开头（`v1.0`，而不是 `1.0`），这样才永远不会与[数字排序前缀](/docs/content/navigation/)冲突。归档版本按从新到旧排列；这个顺序就是切换器里的顺序。

## 切出一个版本

发布时，用一条命令冻结当前文档：

```bash
blume version v1.0
```

它会把你的内容目录复制到 `docs/v1.0/`（已有的快照不参与复制），重写副本内部以根路径开头的链接，让它们留在该快照之内（`/guides/x` 变成 `/v1.0/guides/x`，围栏代码和行内代码不受影响），并在 `blume.config.ts` 中注册这个 id——首次切出版本时会自行补上 `versions` 块，并把线上文档标记为 "Latest"——如果你的配置写法它不会改动，则改为给出警告并打印出可供粘贴的条目。指向不属于被复制目录树的页面链接——生成的 API 参考、像更新日志这样的远程源——仍会指向线上页面，因为快照里并没有它们的副本。不带 id 运行 `blume version` 可列出已配置的版本。

像对待其他内容一样审阅并提交这个新目录。重启 `blume dev` 即可识别它。

```txt
docs/
  index.mdx               ->  /              (最新)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (冻结)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart
```

**归档意味着冻结。** 后续的修改属于线上目录树；快照就是当时的文档。Blume 正是依赖这一点：快照保留各自的文件夹元数据和翻译，[`blume translate`](/docs/cli/translate/) 永远不会重新翻译它们，而配置中的显式侧边栏只对当前文档生效——快照的侧边栏永远来自它自己的文件。

## 切换器与提示条

配置了版本后，头部会自动长出一个版本下拉菜单。切换时，若目标版本中存在同一页面就落到它，否则落到该版本的根（设置 `switcher.redirect: "root"` 可始终落到根）。如果你在 [`navigation.selectors`](/docs/content/navigation/) 中声明了自己的 `kind: "version"` 选择器，它会取代自动生成的那个。

每个归档页面还会显示一条不可关闭的提示，带有指向该页线上对应页面的“Go to latest”链接。可以按版本定制或关闭它：

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0", banner: "These docs cover the 1.x SDK." },
    { id: "v0.9", banner: false },
  ],
}
```

## SEO

旧文档是搜索引擎最爱踩的坑：过时的页面排在现行的前面，或者两者互相争位。Blume 默认采用 SEO 指南推荐、而其它文档框架都不自动做的方案——归档页面仍可被索引，但会把**最新对应页面声明为自己的 canonical**，于是线上页面是权威版本，而仅存在于某个版本中的内容（在最新文档里已不存在的页面）则用自身 canonical 保持可被找到。

你可以按版本选择不同的处理方式：

```ts blume.config.ts
versions: {
  current: { label: "v2.0" },
  archived: [
    { id: "v1.0" }, // canonical → 最新（默认）
    { id: "v0.9", canonical: "self" }, // 每个页面都是权威
    { id: "v0.8", noindex: true }, // 完全不收录
  ],
}
```

站点地图与此保持一致：canonical 指向线上对应页面的归档页面会被排除，`noindex` 版本被整体排除，仅存在于某个版本的页面则继续列出。页面自身的 `seo.canonical` frontmatter 始终优先。

## 搜索

搜索对话框会把结果限定在当前浏览的版本上，语言切换器旁边还有一个“All versions”开关（按读者记住）。跨版本命中的结果会在结果行里标出它所属的版本。Orama（默认）、FlexSearch、Algolia 和 Typesense 都遵守这一范围限定——托管记录带有 `version` 分面，当前文档以 `"current"` 上传。Pagefind、Orama Cloud 和 Mixedbread 不按版本限定：它们的结果横跨所有版本，对话框也不会显示那个开关。

## Agent 接口

面向 agent 的接口是感知版本的——这是其它文档框架都做不到的：

- MCP 的 `search_docs` 和 `list_pages` 工具默认检索当前文档，并接受 `version`：一个归档 id（`"v1.0"`）或 `"all"`。按需调用 `get_navigation` 可返回某个归档快照的目录树。
- `llms.txt` 会把归档版本排在当前文档之后，用该版本的 `label` 或 `id` 加上 `(archived)` 作为标注——上面那个 `{ id: "v1.0" }` 对应 `v1.0 (archived)`——这样读取索引的 agent 就知道哪些文档已冻结。
- `llms-full.txt` 只包含当前版本——这份平铺的转储不会把同一页面的冻结副本交叉混排进来。
- [助手](/docs/configuration/assistant/)会以读者正在浏览的版本为依据来作答——当前文档，除非读者停在归档页面上——这样页面的冻结副本不会把正在读的那一份挤掉。
- 原始 Markdown 镜像（`.md` URL）与其它路由一样，为每个版本的页面都存在。

## 与 i18n 一起使用

版本管理可以与[国际化](/docs/content/i18n/)组合使用。在磁盘上版本文件夹位于最外层——快照自然包含它自己的语言文件夹；而在 URL 里语言仍位于最外层，与站点其余部分保持一致：

```txt
docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
```

语言回退在每个版本内部各自生效：未翻译的快照页面会在本地化 URL 上渲染回退语言的内容，`hreflang` 备选链接也按版本分组。版本 id 不能与已配置的语言代码冲突——Blume 会直接拒绝这种配置。

## 不参与版本管理的内容

版本管理覆盖的是文档内容目录树。博客、更新日志、从 OpenAPI 规范生成的 API 参考以及自定义页面始终是当前版本。还有两点行为值得知道：头部标签页是针对当前文档定义的，因此在归档目录树内部侧边栏渲染时不受标签页限定；而大型站点要注意每个快照都是一份完整副本——内容、搜索索引条目和导航数据都会随版本增长。

---

# 部署
Source: https://blume.ndjp.net/docs/deployment/
English: https://useblume.dev/docs/deployment

## 部署到任意平台（静态）

`blume build` 会把你的文档编译成纯 HTML、CSS 和一份位于 `dist/` 的本地搜索索引。不需要运行任何服务器 —— 把任意静态托管指向这个文件夹即可。

| 配置项 | 值 |
| --- | --- |
| 构建命令 | `blume build` |
| 输出目录 | `dist` |
| Node 版本 | 22.12 或更新版本 |

这些设置在 Vercel、Netlify、Cloudflare Pages、GitHub Pages、Amazon S3 + CloudFront，以及任意存储桶或 CDN 上都适用。确保 `blume` 是一个依赖项，这样托管平台才能执行构建。

一次静态构建包含：

- 每一个文档页和自定义页，都是静态 HTML
- 一份本地搜索索引（默认 Orama，可选 Pagefind）
- 站点 URL 已知时的 [`sitemap.xml`](/docs/discoverability/sitemap-and-robots/)
- [`robots.txt`](/docs/discoverability/sitemap-and-robots/)，在站点 URL 已知时指向 sitemap
- 面向 AI 工具的 `llms.txt` 和 `llms-full.txt`
- 重定向页面
- 开启 `seo.og.enabled` 时预渲染的 [Open Graph 图片](/docs/discoverability/open-graph/)

### 设置站点 URL [#set-your-site-url]

Sitemap、canonical 标签、RSS 和 Open Graph 图片都需要一个绝对来源地址。在 **Vercel**、**Netlify** 和 **Cloudflare Pages** 上，Blume 会在构建时从平台环境中检测它 —— 无需任何配置。

设置 `site`（一个绝对的 `http://` 或 `https://` URL）可以覆盖检测到的值，也可以为那些不暴露该信息的托管平台（GitHub Pages、S3、自建 CDN）补上一个。对静态构建来说，那就是普通的 `deployment` 对象：

```ts blume.config.ts lineNumbers
deployment: {
  site: "https://docs.example.com",
}
```

在 Vercel 和 Netlify 上，自动检测会优先使用你稳定的生产域名，而不是每次部署的预览 URL，这样 canonical 来源地址在多次部署之间保持不变。Cloudflare Pages 只暴露当前部署的 URL（`CF_PAGES_URL`），它每次部署都会变，所以请在那里设置 `site`。

在 `blume dev` 期间，如果没有设置站点 URL，它会回退到你的本地开发服务器（例如 `http://localhost:4321`），这样依赖站点的功能 —— Open Graph 图片、canonical、sitemap —— 开箱即用。构建永远不会使用这个回退值，因此生产产物绝不会指向 localhost。

## 在本地预览

发布之前，先像静态托管那样原样预览生产构建：

```bash
blume build
blume preview
```

`blume preview` 可以提供静态构建，以及 `node()` 和 `cloudflare()` 的服务端构建。Vercel 和 Netlify 适配器没有本地预览服务器，所以在 `vercel()` 或 `netlify()` 的服务端构建之后，它会直接报错停止。请改用 `blume dev` 试用站点，或者用 `vercel deploy`、`netlify deploy` 部署一个预览。

## 子路径部署 [#subpath-deploys]

想把文档挂在 `example.com/docs` 这样的路径下？设置 `base` —— 在 GitHub Pages 项目站上很常见。整个站点（连根路径一起）都会移到 base 之下，内部链接和资源也会被改写成包含它。

```ts blume.config.ts lineNumbers
deployment: {
  base: "/docs",
}
```

`base`（以及 `site`）同样是每个托管适配器的选项：`vercel({ base: "/docs" })`。

每个页面在 base 之下都保留自己的路径，即使它位于一个与 base 同名的内容文件夹里：设 `base: "/docs"` 时，`docs/setup.md` 会提供在 `/docs/docs/setup`，它的 canonical URL、侧边栏链接和 `llms.txt` 条目也都指向那里。你写的以 base 开头的根相对链接会被视为已包含它，并原样保留，所以请用相对链接（`./docs/setup`）或完整路径（`/docs/docs/setup`）来链接那个页面。

## 把文档挂载到某个路径下 [#mount-the-docs-under-a-path]

`basePath` 会把每一个生成的路由挂载到某个路径段之下（`/docs/getting-started`），同时完全不动侧边栏 —— 顶层依然是你的各个板块，而不是一个包裹用的分组。当文档位于 `/docs/*` 而站点根目录仍归你所用时，就用它（类似于 Docusaurus 的 `routeBasePath` 或 Fumadocs 的 `baseUrl`）。

```ts blume.config.ts lineNumbers
basePath: "/docs",
```

链接按挂载在根目录来写（`/getting-started`）；Blume 会改写它们，以及重定向、sitemap、canonical URL、Open Graph 图片、`llms.txt` 和搜索索引。公共资源（图片、`public/` 下的文件）仍留在站点根目录；如果你设置了 [`base`](#subpath-deploys)，则位于它之下。

这与上面两个路径是不同的概念：

- 按来源设置的 [`prefix`](/docs/content/sources/) 为**一个**来源添加命名空间，并且**确实会**新增一个侧边栏分组。
- `deployment.base` 是**整个**应用所从其提供的托管子目录。两者可以叠加 —— 两者都设置时，一个页面会落在 `{deployment.base}/{basePath}/page`。

## 服务端渲染 [#server-rendering]

静态产物足以覆盖大多数文档。当你需要按请求处理的功能时，切换到服务端输出 —— 最典型的是 [assistant](/docs/configuration/assistant/) 端点和 [MCP server](/docs/discoverability/mcp/)。做法是指定托管平台：`deployment` 接受一个从 `blume/deploy` 导入的适配器。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { vercel } from "blume/deploy";

export default defineConfig({
  deployment: vercel(),
});
```

每个适配器都接受相同的具名选项 —— `site`、`base` 和 `output` —— 其余任何内容都会原样透传给底层的 `@astrojs/*` 适配器，所以即使某个选项 Blume 没有具名列出，它依然能传下去：

```ts blume.config.ts lineNumbers
deployment: vercel({
  site: "https://docs.example.com",
  // Passed straight to @astrojs/vercel.
  isr: { expiration: 60 },
}),
```

| 适配器 | 包 | 适用场景 |
| --- | --- | --- |
| `vercel()` | `@astrojs/vercel` | Vercel —— 打磨得最好的一条路 |
| `netlify()` | `@astrojs/netlify` | Netlify Functions |
| `node()` | `@astrojs/node` | 自托管 Node 服务器、容器 |
| `cloudflare()` | `@astrojs/cloudflare` | Cloudflare Workers 和 Pages |

`vercel()` 和 `node()` 随 Blume 一起提供 —— 选一个就能用。`netlify()` 和 `cloudflare()` 需要在项目里装上对应的包（例如 `bun add -d @astrojs/netlify`）。如果缺少它，`blume build` 会停下并给出适合你包管理器的安装命令，`blume dev` 会给出警告，[`blume doctor`](/docs/cli/doctor/) 会把它报告出来。用 pnpm 10 或更新版本时，还需要在 `pnpm-workspace.yaml` 的 `allowBuilds` 下批准这些包带来的构建脚本（`sharp`，以及 Cloudflare 的 `workerd`），否则 pnpm 会中止安装。

指定一个适配器会把构建切换为服务端输出。如果你想在该托管平台上仍然保持静态构建 —— 保留它的站点检测以及它会读取的平台文件 —— 传入 `output: "static"`：

```ts blume.config.ts lineNumbers
deployment: netlify({ output: "static" }),
```

服务端构建包含静态构建的全部内容，外加你添加的任何 Astro endpoint 或中间件。`node()` 适配器会产出一个独立服务器，你可以用 `node dist/server/entry.mjs` 直接运行。除非在启动时设置 `HOST` 和 `PORT` 环境变量（`HOST=0.0.0.0 PORT=8080 node dist/server/entry.mjs`），它会监听 `localhost:4321`；传给 `node()` 的 `host` 和 `port` 不起作用，因为 `@astrojs/node` 会用 Astro 自己的服务器设置替换它们。这个服务器通过指向你项目中 `node_modules` 的链接来解析它的包，所以部署时要带上项目和已安装的依赖，而不能只部署 `dist/`。当站点要发布发现文件、提供内容源下载的图片，或配置了重定向时，Blume 会在 Astro 的入口前放一个小的包装层（把原入口移到旁边的 `astro-entry.mjs`）。它会带上正确的媒体类型和 CORS 头发送 `.well-known` 发现文件，并以沙箱方式提供下载的 SVG —— 这些事情独立服务器的静态处理器自己做不到 —— 同时按各自配置的状态码响应每一次重定向。

在 `blume build` 之后，`cloudflare()` 的服务端构建可以用 `npx wrangler deploy` 从项目根目录部署：Blume 会把重定向过的 Wrangler 配置写到 `.wrangler/deploy/`（并把 `.wrangler/` 加进 `.gitignore`），并用你的项目给 Worker 命名 —— 取 `package.json` 的 `name`，否则取站点主机名，再否则取文件夹名 —— 除非项目根目录下你自己的 `wrangler.jsonc` 设置了 `name`。

在 Vercel 和 Cloudflare 上，服务端构建还会开启 [`Accept: text/markdown` 内容协商](/docs/discoverability/markdown/)，这样一个带上该请求头、来请求任意内容页面的 agent，会在同一个 URL 上收到它的原始 Markdown 镜像。在 Vercel 上，Blume 会把按请求头条件生效的重写规则植入部署的路由配置；在 Cloudflare 上，它会在 Astro 那个 Worker 之前生成一个小 Worker，并把 `assets.run_worker_first` 指向除带指纹的构建产物以及原始 `.md`、`.txt`、`.json`、`.well-known` 文件之外的每一条路径 —— 否则平台会在任何服务器代码运行之前就返回预渲染的页面（以及某个无页面支撑的 URL 对应的 `404.html`）；这些豁免掉的文件则保留它们的零 Worker 快速路径。这个 Worker 还会在针对预渲染的逐页 JSON 文档（`/api/docs/pages/{route}.json`）的请求抵达时，从资源绑定中给出响应，因为否则 Astro 会把它路由到 `/api/` 这个 catch-all。

:::note
`vercel` 和 `cloudflare` 同时也是两个[分析适配器](/docs/configuration/analytics/)的名字。当同一份配置里两者都用到时，给其中一个导入起别名：`import { cloudflare as cloudflareDeploy } from "blume/deploy"`。
:::

:::note
服务端功能有自己的配置 —— 例如 assistant 需要一个模型 API key。设置方法见 [assistant 指南](/docs/configuration/assistant/)。
:::

## 私有文档

Blume 自己不带登录系统。静态构建就是一堆普通文件，任何能访问该托管平台的人都能取走 `dist/` 里的任何内容。要让站点保持私有，请打开你所用托管平台的访问保护，它会在提供文件之前检查每一个请求：

- **Vercel**：[Deployment Protection](https://vercel.com/docs/deployment-protection)，作用域选 **All Deployments**，这样生产环境也被覆盖，而不只是预览。Vercel Authentication 允许你的 Vercel 团队成员进入；Password Protection 允许持有共享密码的任何人进入，需要付费方案。
- **Netlify**：在所有部署上开启[密码保护](https://docs.netlify.com/manage/security/secure-access-to-sites/password-protection/)，用共享密码，或在 Enterprise 方案上用团队登录。
- **Cloudflare**：在提供站点的 Worker 上开启 [Cloudflare Access](https://developers.cloudflare.com/workers/configuration/cloudflare-access/)（**Workers & Pages**，然后是你的 Worker，然后是 **Access**），它会覆盖该 Worker 响应的一切域名。你可以选择按邮箱地址、邮箱域名或 Cloudflare 账号成员身份来登录。
- **GitHub Pages**：在 GitHub Enterprise Cloud 上以组织身份私有发布站点，只有对仓库有读权限的人才能查看。
- **你自己的服务器**：把认证放在 `dist/` 前面，比如 nginx 的 `auth_basic` 或一个具备身份识别能力的代理。

托管平台的保护对[服务端构建](#server-rendering)同样有效。它覆盖整个站点：如果想让部分页面保持公开，把它们作为单独的站点发布。

Blume 写入 `dist/` 的一切都在这层保护之后，包括页面、搜索索引、`.md` 副本、`llms.txt` 和 Open Graph 图片。有几个功能会伸到它之外：

- 托管的[搜索服务](/docs/configuration/search/)（Algolia、Orama Cloud、Typesense 或 Mixedbread）会在那个服务上保留你自己的一份内容副本。内置的 Orama、FlexSearch 和 Pagefind 索引是 `dist/` 里的文件，因此它们保持私有。
- 保护范围之外的服务读不到你的页面。**Open in chat** 会把一个打不开的链接交给 ChatGPT 或 Claude，Slack 或 X 的链接预览无法显示你的 Open Graph 卡片，agent 也读不到 `llms.txt` 或 MCP server。设置 `ai.openInChat: false` 可以隐藏这些对话操作。

## 重定向 [#redirects]

在 `blume.config.ts` 里把旧 URL 映射到新 URL：

```ts blume.config.ts
redirects: [{ from: "/old", to: "/new", status: 301 }],
```

`status` 接受 `301`、`302`、`307` 或 `308`（默认 `301`）。服务端构建在请求时按配置的状态码响应重定向。静态构建既会输出重定向页面**和**托管平台会读取的平台文件，因此会发出真正的 HTTP 重定向：`netlify()` 和 `cloudflare()` 用 `_redirects`，`vercel()` 用 `vercel.json`；而没有指定托管平台时，上述两者都会输出，外加一份 `blume-redirects.json` —— 那是给其它任何东西（nginx/Apache 规则、边缘 Worker）用的结构化清单。你自己放在 `public/` 里的 `_redirects` 或 `vercel.json` 不会被改动。

有两个托管平台需要的不止那个文件：

- **Netlify** 会优先提供实际存在的文件，而不是重定向规则 —— 除非强制该规则生效，而静态构建在每个 `from` 处都有一个重定向页面。`netlify()` 的 `_redirects` 会强制其规则（`/old /new 301!`）。Cloudflare 拒绝这个标志，所以没有指定托管平台的构建所写出的文件会略过它，在 Netlify 上那种构建会改为返回重定向页面；用 `netlify({ output: "static" })` 指定托管平台即可获得 HTTP 重定向。
- **Vercel** 从项目根目录读取 `vercel.json`，绝不从输出目录读取，所以 `dist/` 里的那份只有在你用 Vercel CLI 直接部署该文件夹时才生效（`vercel deploy dist`）。通过 Git 关联的项目永远不会读取它：它会提供重定向页面，但不会提供[内容类型](#content-types)里的任何响应头。把 `dist/vercel.json` 中的 `redirects` 和 `headers` 复制到项目根目录的 `vercel.json` 里，或者服务端构建改用 `vercel()`，它的路由配置会带上重定向和这些发现相关的响应头。

:::note
`from` 和 `to` 都要按挂载在根目录来写，也就是以 `/` 开头（`to` 也可以是完整的 `https://` URL）—— 无论在 [`base`](#subpath-deploys) 还是 [`basePath`](#mount-the-docs-under-a-path) 之下，Blume 都会替你改写两侧，所以重定向会落在 base 之内。若 `to` 指向 `public/` 里的一个文件（`/files/guide.pdf`），它会加上 `base` 但不会加 `basePath`，因为那个文件就是从那里提供的。你已经手动写进 `to` 里的 base 会被保留，而不是被叠加两次。
:::

### 模式重定向 [#pattern-redirects]

一个 `from` 可以一次覆盖多条路径，写法与 Mintlify 和 `vercel.json` 相同：

```ts blume.config.ts
redirects: [
  { from: "/beta/:slug*", to: "/v2/:slug*" },
  { from: "/blog/:slug", to: "/articles/:slug" },
  { from: "/articles/concepts-*", to: "/concepts" },
  { from: "/old/article-*", to: "/new/article-*" },
],
```

- `:name` 匹配一个完整的路径段：`/blog/:slug` 覆盖 `/blog/hello`，但不覆盖 `/blog/a/b`。
- 作为最后一个路径段的 `:name*` 匹配路径的其余部分，段数不限：`/beta/:slug*` 会把 `/beta/guides/setup` 送到 `/v2/guides/setup`，并把 `/beta` 本身送到 `/v2`。最后一段写成 `*` 效果相同。
- 路径段末尾的 `*` 匹配从那里开始的路径其余部分：`/articles/concepts-*` 覆盖 `/articles/concepts-overview`。

`to` 按名称读取捕获组，可以是完整路径段（`/:slug*`、`/:slug`），也可以用一个 `*` 来对应 `from` 中的 `*` 所匹配到的内容（`:splat`，`_redirects` 里的拼法，同样也能读到它）。没有读取任何捕获组的 `to` 会把该模式覆盖的所有路径都送到同一个页面。精确重定向优先于覆盖同一路径的模式，而模式会按你列出的顺序依次尝试。

每个托管平台都会拿到自己语法下的模式：`_redirects` 里的 splat、`vercel.json` 里的 `path-to-regexp` 源，以及 `vercel()` 或 `netlify()` 服务端构建的路由配置。`node()` 和 `cloudflare()` 服务器会自行匹配，`blume dev` 也一样。静态构建不会为模式写出重定向页面 —— 那需要为该模式覆盖的每一条路径各写一个 —— 所以不读取这些文件的托管平台（比如 GitHub Pages）只会应用精确重定向；`blume-redirects.json` 则按你书写的形式列出模式。

一个模式不能同时匹配到一个页面：各托管平台对这两者中哪个该胜出意见不一，所以构建会停下并报 `BLUME_REDIRECT_MATCHES_PAGE`，同时指明是哪个页面。请把模式收窄到真正改动了的路径。

## 内容类型 [#content-types]

在托管平台会读取某个文件的地方，构建还会输出一个 `_headers` 文件，为那些面向 AI 的原始端点固定 `charset=utf-8` —— 即 `/<route>.md`、`/<route>.mdx` 以及那些 `.txt` 文件（`llms.txt`、`llms-full.txt`）。这些响应本身是合法的 UTF-8，但许多静态托管平台会以 `text/markdown` / `text/plain` 且**不带** charset 的方式提供它们，于是浏览器回退到 Windows-1252 —— 直接打开原始 URL 时，含非 ASCII 字符的文档（日语、带变音的拉丁字母等）就会显示成乱码。HTML 页面不受影响，因为它们带有 `<meta charset>`。Netlify 在静态部署时会读取 `_headers`，Cloudflare（Pages 以及 Workers 静态资源）在静态和服务端构建时都会读取，所以这些适配器以及未指定托管平台的静态托管都能得到该文件；Vercel（响应头走路由配置）和 Node（服务器忽略该文件）则不会。Netlify 的服务端构建改为把同样的规则写进它 Frameworks API 配置（`.netlify/v1/config.json`）的 `headers` 里。Vercel 的静态构建则改为把同样的规则写进 `dist/vercel.json`，而通过 Git 关联的项目不读取它（见[重定向](#redirects)）。你自己放在 `public/` 里的 `_headers` 不会被改动。

## 环境变量

当某个功能需要运行时密钥时，如果它缺失，Blume 会在 `blume dev`/`build` 时发出警告 —— 这样问题会尽早暴露，而不是等到第一次请求：

| 功能 | 变量 |
| --- | --- |
| Assistant（AI Gateway） | `AI_GATEWAY_API_KEY`（或 Vercel OIDC） |
| Assistant（其它适配器） | 该适配器的默认密钥环境变量（`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`GEMINI_API_KEY`、`XAI_API_KEY`、`OPENROUTER_API_KEY`、`LLMGATEWAY_API_KEY`、`INKEEP_API_KEY`），或你传给它的 `apiKeyEnv` |
| Mixedbread 搜索 | `MIXEDBREAD_API_KEY` |
| [内容源](/docs/content/sources/) | `NOTION_TOKEN`（`notion()`）、`SANITY_TOKEN`（`sanity()`）、`CONTENTFUL_ACCESS_TOKEN`（`contentful()`）、`PAYLOAD_API_KEY`（`payload()`）、`STRAPI_API_TOKEN`（`strapi()`）、`GITHUB_TOKEN`（`githubReleases()`，以及从 GitHub 读取的 `mdxRemote()`） |

本地开发把它们放在 `.env.local`，生产环境放在你所用托管平台的环境变量里。内容源会在抓取时读取自己的密钥，在 `blume dev` 和 `blume build` 期间都会如此，所以要把它设在你的站点构建时能读到的地方。搜索索引同步（Algolia、Orama Cloud、Typesense）所需的构建时密钥，会在同步步骤中单独给出警告。

## 构建缓存 [#build-cache]

Blume 保留两份缓存供构建复用。Astro 和 Vite 的缓存在 `.blume/.cache/` 下（其中包括内容存储和图片转换）。已渲染的 [OG 卡片](/docs/discoverability/open-graph/) 位于 `node_modules/.cache/blume/og`，所以重新构建时只会渲染那些标题、描述或品牌信息发生变化的卡片。某个平台是否在多次部署之间保留该目录，情况各不相同：

- **Vercel** 会从构建缓存里恢复 `node_modules/**`，所以卡片会延续（缓存上限 1 GB，保留一个月，按分支做 key —— 新分支从生产缓存开始）。
- **Netlify** 会恢复 `node_modules`，所以卡片会延续。
- **Cloudflare Workers Builds** 只保留包管理器缓存，以及针对被识别为 Astro 项目的 `node_modules/.astro` —— 绝不会保留 `node_modules/.cache` —— 所以在那里每次部署都会渲染全部卡片。
- **GitHub Actions** 以及你自己管理的其他 runner 不会保留任何东西，除非你自己缓存这个目录：

```yaml
- uses: actions/cache@v4
  with:
    path: node_modules/.cache/blume/og
    key: blume-og-${{ runner.os }}-${{ hashFiles('**/bun.lock', '**/package-lock.json', '**/pnpm-lock.yaml') }}
    restore-keys: blume-og-${{ runner.os }}-
```

卡片按内容做 key，所以 key 不精确也没关系：恢复的缓存只可能省下渲染，永远不会提供错误的卡片。

有一个安装命令会在所有平台上丢弃缓存：`npm ci` 会在安装前删除 `node_modules`。请保持用 `npm install`、`bun install` 或 `pnpm install` 作为安装命令，才能享受缓存复用。

## 构建摘要

每次构建都会打印一份摘要 —— 输出模式、适配器、解析出的站点 URL、搜索服务、重定向数量、sitemap 和 `llms.txt` 状态，以及任何已启用的服务端功能 —— 这样你可以在部署前确认（发布）了什么，包括所有自动检测到的内容。

---

# 可发现性
Source: https://blume.ndjp.net/docs/discoverability/
English: https://useblume.dev/docs/discoverability

搜索引擎和 AI agent 对你的文档期待的是同一样东西：一份干净、机器可读的说明，讲清每个页面说了什么、页面之间如何关联、以及是谁发布的。Blume 把两者视为同一层可发现性。元数据、社交卡片、订阅源和结构化数据服务于给你排名的爬虫；`llms.txt`、原始 Markdown、一个 JSON API、一个 MCP server 和各种发现清单服务于那些回答关于你的问题的 agent —— 而介于其间的那些文件（`robots.txt`、sitemap、JSON-LD）则两者都会读。

其中几乎全部默认开启，无需任何配置。开关位于 `blume.config.ts` 的两个键下：`seo` 决定搜索引擎和社交平台看到什么，`agents` 决定 agent 看到什么。

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
  x: { handle: "@acme" },
},
agents: {
  llmsTxt: true,
  mcp: { enabled: false },
},
```

其中大部分在拿到绝对站点 URL 后才更完整 —— 设置 [`deployment.site`](/docs/deployment/)，订阅源、OG 图片、canonical 来源地址、sitemap、JSON-LD 以及每一份 agent 清单就能输出完整 URL。有几个输出面 —— Open Graph 图片、sitemap、RSS 订阅源和 AI 目录 —— 在设置之前保持关闭。

## 构建产出什么 [#what-the-build-emits]

| 输出面 | 位置 | 默认 | 说明 |
| --- | --- | --- | --- |
| `<head>` 元数据、canonical 来源地址、X 卡片 | 每个页面 | 开启 | [元数据](/docs/discoverability/metadata/) |
| 社交分享图片 | `/og/<route>.png` | 有站点 URL 时开启 | [Open Graph 图片](/docs/discoverability/open-graph/) |
| schema.org JSON-LD | 每个页面 | 开启 | [结构化数据](/docs/discoverability/structured-data/) |
| RSS 订阅源 | `/<type>/rss.xml` | 有站点 URL 时开启 | [RSS 订阅源](/docs/discoverability/rss/) |
| `sitemap.xml`、`robots.txt`、内容信号 | 站点根目录 | 开启 | [Sitemap 与 robots](/docs/discoverability/sitemap-and-robots/) |
| `llms.txt`、`llms-full.txt` | 站点根目录 | 开启 | [`llms.txt`](/docs/discoverability/llms-txt/) |
| 原始 Markdown 镜像、内容协商、Copy as Markdown、Open in chat | `/<route>.md` | 开启 | [面向代理的 Markdown](/docs/discoverability/markdown/) |
| JSON API 及其 OpenAPI 描述 | `/api/docs/…`、`/openapi.json` | 开启 | [JSON API](/docs/discoverability/json-api/) |
| MCP server | `/mcp` | 需手动开启，且需要服务端输出 | [MCP server](/docs/discoverability/mcp/) |
| `agent-readability.json`、`Link` 响应头、API 目录、AI 目录（ARD）、WebMCP | 站点根目录、`/.well-known/…` | 开启 | [Agent 可发现性](/docs/discoverability/agent-discovery/) |
| Agent skills、Web Bot Auth 密钥 | `/.well-known/…` | 需手动开启 | [Agent 可发现性](/docs/discoverability/agent-discovery/) |

每一个生成的文件都会让位于你自己提供的版本：把 `robots.txt`、`sitemap.xml`、`llms.txt`、`openapi.json` 或 `agent-readability.json` 放进 `public/`，Blume 就会用你的文件代替它生成的那一份。

页面内的 **assistant** 是唯一一个在别处记录的 AI 功能：它是面向读者的产品特性，而不是一种发现输出面，因此在 `ai` 下配置，文档位于[助手](/docs/configuration/assistant/)。

## 检查你的成果 [#checking-your-work]

[`blume audit`](/docs/cli/audit/) 会抓取构建好的站点，报告标题、描述、canonical 来源地址、Open Graph 与 X 卡片、hreflang、sitemap、`robots.txt` 和结构化数据的情况。用 `--url` 指向某个部署，还可以一并检查响应头和[基于 DNS 的 agent 可发现性](/docs/discoverability/agent-discovery/)。

---

# 智能体发现
Source: https://blume.ndjp.net/docs/discoverability/agent-discovery/
English: https://useblume.dev/docs/discoverability/agent-discovery

发布 `llms.txt`、Markdown 镜像、JSON API 和 MCP 服务器只是做了一半 —— 智能体还得找得到它们。Blume 通过智能体真正会去探测的那些约定，把整片界面广告出去：站点根目录下的一份清单、`Link` 响应头与 `<link>` 标签、well-known 文件，以及浏览器自带的模型上下文。这里的一切都默认开启，并从你已经启用的功能推导而来。

## 智能体可读性 [#agent-readability]

Blume 会在你的站点根目录写入一份 **`/agent-readability.json`** 清单，为本节描述的面向智能体的界面建立索引 —— 智能体因此只需一次抓取就能发现它，而不必去猜约定或解析 HTML。和 `llms.txt` 一样，它默认开启：

```ts blume.config.ts lineNumbers
agents: {
  agentReadability: true,
}
```

清单只列出你已启用的东西 —— [原始 Markdown](/docs/discoverability/markdown/) 镜像模式、[JSON API](/docs/discoverability/json-api/) 及其 OpenAPI 描述、[`llms.txt`](/docs/discoverability/llms-txt/) 和 `llms-full.txt`、[MCP 服务器](/docs/discoverability/mcp/) 及其发现文档、[assistant](/docs/configuration/assistant/) 端点、[sitemap](/docs/discoverability/sitemap-and-robots/) 以及 [RSS 订阅源](/docs/discoverability/rss/) —— 外加你的站点名称、描述、源码仓库，以及 [content-signal](/docs/discoverability/sitemap-and-robots/) 使用策略。设置了 [`deployment.site`](/docs/deployment/) 时 URL 为绝对地址，否则为根相对地址：

```json agent-readability.json
{
  "artifacts": {
    "markdown": {
      "contentNegotiation": "text/markdown",
      "pattern": "https://docs.example.com/{route}.md"
    },
    "api": {
      "openapi": "https://docs.example.com/openapi.json",
      "pages": "https://docs.example.com/api/docs/pages.json",
      "search": "https://docs.example.com/api/docs/search"
    },
    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
    "llmsTxt": "https://docs.example.com/llms.txt",
    "mcp": {
      "discovery": "https://docs.example.com/.well-known/mcp.json",
      "url": "https://docs.example.com/mcp"
    }
  },
  "description": "Docs for the Acme API.",
  "generator": "blume@2.0.0",
  "name": "Acme Docs",
  "site": "https://docs.example.com",
  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
  "repository": "https://github.com/acme/docs"
}
```

`contentNegotiation` 字段只有在部署后的站点确实遵守 `Accept: text/markdown` 头时才会出现 —— 参见[内容协商](/docs/discoverability/markdown/)；其它任何部署上，清单都只声明 `.md` 镜像模式。

把 `agents.agentReadability` 设为 `false` 即可跳过；也可以自行提供 `public/agent-readability.json` 来接管 —— Blume 绝不会覆盖你放在 `public/` 里的文件。

## Discovery Link 头 [#discovery-link-header]

会去探测站点的智能体并不知道该找这份清单 —— 所以 Blume 还通过首页上一个 [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` 响应头声明它，使用的是 IANA 已注册的关系类型：

```http
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"",
  </.well-known/ai-catalog.json>; rel="ai-catalog"; type="application/ai-catalog+json",
  </openapi.json>; rel="service-desc"; type="application/json",
  </agent-readability.json>; rel="describedby"; type="application/json",
  </llms.txt>; rel="describedby"; type="text/plain",
  </index.md>; rel="alternate"; type="text/markdown"
```

每个条目只在其对应功能开启时才出现。`alternate` 链接指向首页的 Markdown 镜像 —— 当首页路由是内容页面时，是该页自己的[原始 Markdown](/docs/discoverability/markdown/)；若它是落地页，则回退为合成的 `llms.txt`。`service-desc` 链接（[RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)）指向 [JSON API](/docs/discoverability/json-api/) 的 OpenAPI 描述，`api-catalog` 指向[生成的 API catalog](#api-catalog)，`ai-catalog` 指向 [AI catalog](#ai-catalog)。这个头出现在 Blume 控制的每个界面上：静态构建通过生成的 `_headers` 文件（Netlify 和 Cloudflare），Vercel 上的服务端构建通过部署的路由规则，以及开发服务器（用 `curl -I localhost:4321` 检查）。开发服务器的头只列出它自己提供的东西 —— `service-desc` 和 `alternate` 两个链接 —— 因为 `blume build` 才会把各份 catalog、`agent-readability.json` 和 `llms.txt` 写进构建产物。

不过并非每个智能体都从根目录进入 —— 有的顺着搜索结果或分享链接落到深层页面上，根本看不到首页那个头。所以每个渲染出的页面也在它的 HTML `<head>` 里带上同样的发现链接，使用同一批 IANA 已注册的关系：

```html
<link
  rel="describedby"
  href="/agent-readability.json"
  type="application/json"
/>
<link rel="describedby" href="/llms.txt" type="text/plain" />
<link
  rel="ai-catalog"
  href="/.well-known/ai-catalog.json"
  type="application/ai-catalog+json"
/>
<link rel="ard" href="/.well-known/ard.json" type="application/json" />
<link rel="alternate" href="/docs/example.md" type="text/markdown" />
```

这里的 `alternate` 链接指向_该页面自己的_[原始 Markdown 镜像](/docs/discoverability/markdown/)，智能体因此可以直接从落脚的 HTML 跳到省 token 的版本。由于这些 head 链接随预渲染的 HTML 一起走，它们在那些完全忽略 `_headers`、根本无法发送自定义响应头的主机上同样有效（GitHub Pages、S3）—— 无论智能体是从哪个页面进来的。

## API catalog [#api-catalog]

当站点发布 API 时，Blume 会在 `/.well-known/api-catalog` 生成一份 [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog —— 一个 [linkset](https://www.rfc-editor.org/rfc/rfc9264)，让智能体仅凭域名就能枚举出你的 API，并带着其已注册的 `application/linkset+json` 媒体类型和该 RFC 的 `profile="https://www.rfc-editor.org/info/rfc9727"` 参数，在每个构建界面上对外提供。这里没有可配置项：这份 catalog 由 `blume.config.ts` 中已有的内容推导而来。每个 [OpenAPI、AsyncAPI 或 GraphQL 参考](/docs/references/openapi/) 都会成为一个条目，锚定在它渲染出的文档路由上，`service-doc` 指向那些文档，若规范位于可抓取的 URL 则 `service-desc` 指向规范本身；站点自己的 [JSON API](/docs/discoverability/json-api/) 会成为一个由其 `/openapi.json` 描述的条目；[MCP 服务器](/docs/discoverability/mcp/) 则成为一个以自身发现文档作为服务描述的条目：

```json .well-known/api-catalog
{
  "linkset": [
    {
      "anchor": "https://docs.example.com/reference",
      "service-doc": [
        { "href": "https://docs.example.com/reference", "type": "text/html" }
      ],
      "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
    },
    {
      "anchor": "https://docs.example.com/api/docs",
      "service-desc": [
        {
          "href": "https://docs.example.com/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    },
    {
      "anchor": "https://docs.example.com/mcp",
      "service-desc": [
        {
          "href": "https://docs.example.com/.well-known/mcp.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://docs.example.com/", "type": "text/html" }
      ]
    }
  ]
}
```

没有 API 参考、没有 MCP 服务器、又关掉了 [JSON API](/docs/discoverability/json-api/) 的站点不会产出 catalog —— 里面也无处可放。和其它地方一样，你自行提供的 `public/.well-known/api-catalog` 文件会覆盖生成的那份。

## AI catalog [#ai-catalog]

API catalog 列出的是 API。**AI catalog** 列出的则是智能体能从这个站点拿到的所有东西 —— MCP 服务器、每个已发布的 skill、JSON API、每个渲染出的 API 参考，以及 `llms.txt` —— 采用智能体注册表用于索引的格式：一份位于 `/.well-known/ai-catalog.json` 的 [AI Catalog](https://github.com/Agent-Card/ai-catalog) 文档，它同时也是 [Agentic Resource Discovery（ARD）](https://agenticresourcediscovery.org/) 消费方所解析的那份清单。每个条目都带一个锚定域名的 `urn:air:<host>:<namespace>:<name>` 标识符、一个显示名、一行描述、该构件的媒体类型、它的 URL，以及若干条 `representativeQueries` —— 资源能回答的示例问题，注册表会把它们嵌进去做语义搜索。下面是一个标题为 “Acme”、开启 MCP 服务器并发布了一个 skill 的站点的 catalog：

```json .well-known/ai-catalog.json
{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme",
    "identifier": "did:web:docs.example.com",
    "documentationUrl": "https://docs.example.com/"
  },
  "entries": [
    {
      "identifier": "urn:air:docs.example.com:mcp:acme",
      "displayName": "Acme",
      "description": "Model Context Protocol server over the Acme documentation: full-text search, page Markdown, the page index, and the navigation tree.",
      "type": "application/mcp-server-card+json",
      "url": "https://docs.example.com/.well-known/mcp/server-card.json",
      "capabilities": [
        "search_docs",
        "get_page",
        "list_pages",
        "get_navigation"
      ],
      "representativeQueries": [
        "search the Acme documentation",
        "get a page of the Acme docs as Markdown",
        "list every page in the Acme docs"
      ]
    },
    {
      "identifier": "urn:air:docs.example.com:skill:acme",
      "displayName": "acme",
      "description": "Set up an Acme project and call its API.",
      "type": "application/agent-skills+md",
      "url": "https://docs.example.com/.well-known/agent-skills/acme/SKILL.md",
      "representativeQueries": [
        "load the acme agent skill",
        "how do I use acme"
      ]
    },
    {
      "identifier": "urn:air:docs.example.com:api:docs",
      "displayName": "Acme docs API",
      "description": "REST API over the Acme documentation: the page index, each page as JSON or Markdown, and the navigation tree, described by this OpenAPI document.",
      "type": "application/vnd.oai.openapi+json",
      "url": "https://docs.example.com/openapi.json",
      "representativeQueries": [
        "fetch a page of the Acme docs as JSON",
        "list the pages in the Acme docs",
        "get the navigation tree of the Acme docs"
      ]
    },
    {
      "identifier": "urn:air:docs.example.com:docs:llms-txt",
      "displayName": "Acme llms.txt",
      "description": "llms.txt index of the Acme documentation: every page with a one-line summary, plus the agent-facing resources on this site.",
      "type": "text/plain",
      "url": "https://docs.example.com/llms.txt",
      "representativeQueries": [
        "what is Acme",
        "overview of the Acme documentation"
      ]
    }
  ]
}
```

ARD 当前版本从 `/.well-known/ard.json` 读取清单，并把 `ai-catalog.json` 称作它的前代路径，因此 Blume 把同一份文档写到两处，在每个页面的 head 里用两种链接关系（`ai-catalog` 和 `ard`）声明它，并在 `llms.txt` 和 `agent-readability.json` 中列出它。这份 catalog 及其 `.well-known` 邻居（API catalog、MCP 发现文件）在每个构建界面上都以 `Access-Control-Allow-Origin: *` 提供，因此从另一个 origin 读取它们的注册表不会受阻。

条目标识符锚定在你的域名上，因此这份 catalog 需要一个 [`deployment.site`](/docs/deployment/) —— 没有它就不会产出任何东西。它默认开启；`agents.catalog: false` 可以关掉它。生成的查询由站点标题和每个条目自身的名称推导而来。若要为某个条目自定义，用标识符的尾部（`<namespace>:<name>`）作为键：

```ts blume.config.ts
export default defineConfig({
  agents: {
    catalog: {
      queries: {
        "mcp:acme": ["how do I install Acme", "search the Acme docs"],
        "skill:acme": ["set up an Acme project", "write an Acme plugin"],
      },
    },
  },
});
```

一个列表会替换掉该条目自动生成的查询；你没点名的条目保留自己的。和其他地方一样，你自行提供的 `public/.well-known/ai-catalog.json`（或 `ard.json`）会覆盖生成的那份。

## WebMCP

[WebMCP](https://webmachinelearning.github.io/webmcp/) 是一项正在兴起的浏览器 API，让页面可以直接把工具注册到智能体浏览器上 —— 不需要单独连接服务器。每个 Blume 页面都会把文档的只读界面注册到页面的模型上下文上：`search_docs`（站内搜索）、`get_page`（某个页面的[原始 Markdown](/docs/discoverability/markdown/)）和 `list_pages`（那份 [`llms.txt`](/docs/discoverability/llms-txt/) 索引）。这段脚本很小，在真正调用某个工具之前不会加载任何搜索机制；在所有还没有该 API 的浏览器里它都会静默失效 —— 目前除 [Chrome 的早期预览](https://developer.chrome.com/blog/webmcp-epp)之外，所有浏览器都属于这一类。它注册到仍在变动的规范所暴露的界面上（`navigator.modelContext` 或 `document.modelContext`），通过 `provideContext` 或按工具的 `registerTool` 来完成。

它默认开启；设置 `webmcp: false` 即可退出：

```ts blume.config.ts lineNumbers
agents: {
  webmcp: false,
}
```

## 你站点的 skill [#your-sites-skill]

每次构建都会为你的文档写一份 [agent skill](https://agentskills.io)，即一份编码智能体可以安装、用来配合你的产品工作的 `SKILL.md`。它在 `/skill.md` 提供，并列在 [skills 索引](#skills-discovery)中。Blume 用它已经了解的站点信息来构建它，不调用任何模型，因此零成本，而且你的文档一改它就跟着变。它包含：

- 站点的标题和描述，以及智能体何时该使用这个 skill
- 如何把任意页面当作 Markdown 读取，以及在站点提供它们时，`llms.txt`、`llms-full.txt`、[MCP 服务器](/docs/discoverability/mcp/)、JSON API 和更新日志
- 你的 API 参考
- 一份按侧边栏顺序排列的文档地图，每个页面都链到它的 Markdown，并附一行描述

这个 skill 以你站点的 `title` 命名（`Acme Docs` 会变成 `acme-docs`）。它覆盖默认语言下的当前版本，不含 API 操作页和更新日志条目（它们各自在地图上方有一行说明），最多列出 200 个页面，其余的指向 `llms.txt`。链接是绝对地址，因此这个 skill 需要 [`deployment.site`](/docs/deployment/)；没有它的构建会跳过这一步。

自动生成的这份 skill 是一份通往你文档的指南，而不是你产品的摘要。若要一份真正教会智能体使用你产品的 skill —— 安装配置、核心概念、常见任务和坑 —— 可以让你的编码智能体根据文档来写：

```bash
blume skill --claude   # 或 --codex
```

`blume skill` 会让 Claude Code 或 Codex 打开 [`blume-write-skill`](/docs/advanced/skills/) 这个 skill，它会在你的 [`agents.skills`](#skills-discovery) 文件夹下（未设置时为 `./skills`，同时把它写进你的配置）写出一份以站点命名的 `SKILL.md`，从而替换掉自动生成的那份。你像对待其它文件一样审阅并提交它；它只花掉你智能体一次 token，而不是每次构建都花一次。文档有大改动后要再跑一次，因为手写的 skill 不会自己更新。不带参数时，`blume skill` 会打印这个 skill 将放到哪里，以及如何让另一个智能体指向它。

`agents.skills` 里任何同名的 skill —— 不论你怎么写 —— 都会替换索引里自动生成的那份；若它是一个单独的 `SKILL.md`，在 `/skill.md` 上也一样被替换。你自行提供的 `public/skill.md` 两者都能压过。要关掉这个 skill：

```ts blume.config.ts lineNumbers
agents: {
  skillMd: false,
}
```

## Skills 发现 [#skills-discovery]

如果你的项目提供了 [agent skills](https://agentskills.io) —— [Blume 自己的仓库就提供了](/docs/advanced/skills/) —— 那就把 `agents.skills` 指向存放它们的目录，构建就会依照 [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) 发布它们以便被发现：

```ts blume.config.ts lineNumbers
agents: {
  skills: "./skills",
}
```

这个路径从你的项目根目录解析，每个含 `SKILL.md` 的子目录都会成为一个已发布的 skill。只含单个 `SKILL.md` 的 skill 会被逐字复制到 `/.well-known/agent-skills/<name>/SKILL.md`（`type: "skill-md"`）；带配套资源（`scripts/`、`references/`、`assets/`）的 skill 则被打包成一个确定性的 `.tar.gz`（`type: "archive"`），使其相对引用在解压后依然可用，并保留脚本的可执行位。位于 `/.well-known/agent-skills/index.json` 的发现索引带有 v0.2.0 的 `$schema`，并为每个 skill 记录其名称、类型、描述（取自 `SKILL.md` 的 frontmatter）、构件 URL，以及客户端校验下载所用的 SHA-256 摘要。

`name`/`description` 缺失或不符合规范的 skill 会被跳过并给出构建警告，而不是带着问题发布；而你自行提供的 `public/.well-known/agent-skills/index.json` 会接管整个界面。已发布的 skill —— 包括[你站点自己的那份](#your-sites-skill) —— 也会列在 [`llms.txt`](/docs/discoverability/llms-txt/) 里。

## 基于 DNS 的发现（DNS-AID） [#dns-based-discovery-dns-aid]

[DNS for AI Discovery](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) 是一份正在兴起的 IETF 草案，它让智能体在发出任何一个 HTTP 请求之前，通过在一个众所周知的 DNS 入口查询 ServiceMode 的 [SVCB/HTTPS 记录](https://www.rfc-editor.org/rfc/rfc9460)来发现站点的 AI 界面。DNS 记录存在于你的区域里，而不在构建里，所以这是 Blume 唯一无法替你发布的发现界面 —— 请改为在你的 DNS 服务商处添加一条记录：

```txt
_index._agents.docs.example.com. 3600 IN HTTPS 1 docs.example.com. alpn=h2
```

如果你的服务商提供 `HTTPS` 记录类型就用它（Vercel DNS 提供；它不支持普通的 `SVCB` 类型），否则用带 `alpn` 和 `port` 参数的 ServiceMode `SVCB` 记录。该草案还建议用 DNSSEC 对区域签名，好让做验证的解析器返回经过认证的答案 —— Cloudflare 之类的服务商一键就能启用，而有些服务商（包括 Vercel DNS）则完全不支持。

`blume audit --url <origin>` 会替你检查这件事：当 [`deployment.site`](/docs/deployment/) 已设置时，网络这一层会通过 DNS-over-HTTPS 查询该入口，若记录不存在就报告应当发布的确切记录，还会说明答案是否经过 DNSSEC 认证。如果你的网络屏蔽了公共解析器（Google、Cloudflare），设置 `BLUME_DOH_URL` 把查询指向你自己的解析器。

## Web Bot Auth

[Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/) 朝相反的方向工作：它不是关于智能体读取你的文档，而是关于**你的组织的智能体在别处发起请求时表明身份**。你的智能体用 [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) 为请求签名，接收方站点则用一个发布在你域名上的公钥目录来验证。如果你的组织在运行智能体，而你的 Blume 站点恰好位于它们声明的那个域名上，就发布它们的公钥：

```ts blume.config.ts lineNumbers
agents: {
  webBotAuth: {
    keys: [{ kty: "OKP", crv: "Ed25519", x: "JrQLj5P_89iXES9-vFgrIy29c…" }],
  },
}
```

随后 Blume 会在每个构建界面上，以其已注册的媒体类型在 `/.well-known/http-message-signatures-directory` 提供 JWKS。这个目录按定义就是公开的，因此配置只接受公钥 —— 含有私钥材料（`d`、`p`、`q`……）的 JWK 会在校验时报错，而不会把泄露的凭据发出去。用下面的命令生成一对 Ed25519 密钥：

```bash
node -e 'const { generateKeyPairSync } = require("node:crypto"); const { publicKey, privateKey } = generateKeyPairSync("ed25519"); console.log("public: ", JSON.stringify(publicKey.export({ format: "jwk" }))); console.log("private:", JSON.stringify(privateKey.export({ format: "jwk" })))'
```

公钥 JWK 放进上面的配置里；私钥那份则放到你运行签名智能体的位置（密钥管理器，绝不要进仓库）。如果你的组织不运营智能体，跳过这一步 —— 一个空的目录没什么值得验证的东西可声明。

由于 `blume.config.ts` 会在构建时执行，这个密钥不必写死在里面 —— 从构建时的环境变量读取，可以让配置不含密钥内容，也能在不提交的情况下轮换：

```ts blume.config.ts lineNumbers
const webBotAuthKey = process.env.WEB_BOT_AUTH_PUBLIC_JWK;

export default defineConfig({
  agents: {
    webBotAuth: {
      keys: webBotAuthKey ? [JSON.parse(webBotAuthKey)] : [],
    },
  },
});
```

没有该变量的环境不会发布任何目录，而这样加载进来的密钥与内联密钥的校验方式完全相同 —— 包括私钥材料检查。（公钥并不是秘密，因此直接提交在配置里同样没问题；环境变量只是出于便利，而非出于安全考虑。）

---

# JSON API
Source: https://blume.ndjp.net/docs/discoverability/json-api/
English: https://useblume.dev/docs/discoverability/json-api

每个 Blume 站点还会把文档以一个小型只读 **JSON API** 提供出来 —— 它是 [MCP 服务器](/docs/discoverability/mcp/)那套工具的 REST 版本，基于同一份页面快照，服务于那些说普通 HTTP 而非 MCP 的智能体和函数调用框架。它默认开启，无需任何配置：

| 端点 | 返回 |
| --- | --- |
| `/api/docs/pages.json` | 每个页面及其路由、标题、描述、内容类型、locale、facets，以及渲染版、Markdown 版和 JSON 版的 URL。未翻译页面的 i18n 回退副本会被排除；在服务端输出上，缺失页面的 JSON 会以 `404` 和 `PAGE_NOT_FOUND` 作答。 |
| `/api/docs/pages/{route}.json` | 单个页面：它的索引条目加上面向智能体的 Markdown（与 `get_page` 返回的内容相同）。`{route}` 是不带前导斜杠的页面路由，首页用 `index`。 |
| `/api/docs/navigation.json` | 导航树 —— 页眉标签页和侧边栏层级。 |
| `/api/docs/search?q=` | 全文搜索，作用域参数与 `search_docs` 相同：`limit`、`contentTypes`、`locale`、`version` 和 `filters[key]`。仅服务端输出。 |
| `/openapi.json` | 整个机器可读界面的 OpenAPI 3.1 描述。 |

页面索引、逐页面文档和导航都是预渲染的，因此静态站点可以从任意托管平台以文件形式提供它们。搜索是一个实时端点，只存在于[服务端输出](/docs/deployment/)下，它使用与 `search_docs` 相同的索引。

## 错误

错误采用 [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 的 problem details（`application/problem+json`），带一个稳定的 `code`、一个 `detail`，以及一个 `resolution` 提示，告诉智能体下一步该去哪 —— 页面缺失、搜索词为空，或者在服务端输出上任何没有端点响应的 `/api/…` URL：

```json
{
  "code": "API_ROUTE_NOT_FOUND",
  "detail": "No API route exists at /api/nope.",
  "instance": "/api/nope",
  "links": [
    {
      "href": "https://docs.example.com/openapi.json",
      "label": "OpenAPI description"
    },
    {
      "href": "https://docs.example.com/api/docs/pages.json",
      "label": "Page index"
    }
  ],
  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
  "status": 404,
  "title": "API route not found",
  "type": "about:blank"
}
```

## OpenAPI 描述

`/openapi.json` 处的 **OpenAPI 文档**在每次构建时依据你的配置生成，因此它描述的只有已部署站点实际提供的内容：每个 JSON 端点及其唯一的 `operationId`、带类型的参数和响应 schema，此外还有旁边的纯文本入口 —— [`.md` 镜像](/docs/discoverability/markdown/)、[`llms.txt`](/docs/discoverability/llms-txt/) 和 `llms-full.txt`、[`agent-readability.json`](/docs/discoverability/agent-discovery/) —— 以及启用时的 [MCP 端点](/docs/discoverability/mcp/)。那些依据 OpenAPI 描述来构建工具的框架，得到的触达能力与 MCP 客户端相同。该文档会被 [API catalog](/docs/discoverability/agent-discovery/)、[可读性清单](/docs/discoverability/agent-discovery/)、首页的 `Link` 头（`rel="service-desc"`）以及 `llms.txt` 链出。

这一切都不会影响你自己的 [API 参考](/docs/references/openapi/)：被记录的规范会被渲染成页面，绝不会在 `/openapi.json` 提供，而 catalog 会同时列出两者。你自己发布的 `public/openapi.json` 会接管该路由（JSON 端点仍然保留）。当某个文档分区从 `/api` 命名空间提供（`content/api/overview.md`），或某个自定义页面在 `/api/` 下拥有自己的 rest 路由时，`/api/…` 这个兜底路由会让位，因此这些页面依然优先。

## 关闭

设置 `agents.api` 为 `false` 就不发布其中任何内容：

```ts blume.config.ts lineNumbers
agents: {
  api: false,
}
```

---

# llms.txt
Source: https://blume.ndjp.net/docs/discoverability/llms-txt/
English: https://useblume.dev/docs/discoverability/llms-txt

Blume 会输出机器可读版本的文档，供编码智能体和聊天助手消费。它默认开启；设置 `llmsTxt: false` 即可关闭：

```ts blume.config.ts lineNumbers
agents: {
  llmsTxt: false,
}
```

启用期间，`blume build` 会向站点根目录写出两个文件：

- **`/llms.txt`** —— 一份紧凑索引：先是站点标题和描述，然后是每个页面的带链接列表并附上摘要，按与侧边栏对应的分区组织 —— 文件夹和分组会变成标题，因此智能体看到的是文档的结构，而不是一整块平铺的内容。
- **`/llms-full.txt`** —— 全部内容合集：每个页面的完整 Markdown 正文，连同它的源 URL，集中在单个文件里。

草稿、在侧边栏中隐藏的页面（`sidebar.hidden`，或顶层的 `hidden` 简写）以及 `noindex` 页面都会被排除 —— 唯独生成的 API 参考页例外，它们在这两个文件中的去留由下面的 `openapi` 决定，而不是由 `noindex` 决定。设置 [`deployment.site`](/docs/deployment/)，让链接和源 URL 解析为绝对地址。

## 选项

`llmsTxt` 也可以写成对象形式，用各个开关控制文件包含什么。如果你的 [API 参考](/docs/references/openapi/)记录的是一份占位或示例用的规范，设置 `openapi: false` 让它生成的页面不进这两个文件：

```ts blume.config.ts lineNumbers
agents: {
  llmsTxt: {
    enabled: true, // 默认值
    openapi: false, // 排除生成的 API 参考页
  },
}
```

对象形式还接受 `details`：放在 `llms.txt` 中标题和摘要之后、页面分区之前的 Markdown —— 即 [llms.txt 规范](https://llmstxt.org)中那个自由格式的 “details” 块。这里正是告诉智能体_何时_该用你的产品、以及怎么调用它的地方，就绪度扫描工具会显式查找这些内容；安装命令和包名也该写在这里。规范允许在那里放任意 Markdown，唯独不允许标题（标题要留给后面的链接分区），所以请写成段落或列表：

```ts blume.config.ts lineNumbers
agents: {
  llmsTxt: {
    details:
      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
  },
}
```

## 自动生成的分区 [#generated-sections]

`llms.txt` 以两个自动生成、无需任何配置的分区收尾。**Agent skills** 列出[站点自己的 skill](/docs/discoverability/agent-discovery/)，以及每个通过 [`agents.skills`](/docs/discoverability/agent-discovery/) 发布的 skill 及其描述（skill 会在描述里说明何时该用）。**Agent resources** 链出构建输出的每一件机器可读产物 —— `llms-full.txt`、逐页面的[原始 Markdown](/docs/discoverability/markdown/)镜像、[MCP 服务器](/docs/discoverability/mcp/)及其发现文档、skills 索引、[API catalog](/docs/discoverability/agent-discovery/)、[AI catalog](/docs/discoverability/agent-discovery/)、[`agent-readability.json`](/docs/discoverability/agent-discovery/) 以及 [sitemap](/docs/discoverability/sitemap-and-robots/) —— 每一项都只在它存在时才出现，因此只读 `llms.txt` 的智能体依然能找到整个界面。

## 排除某个页面 [#excluding-a-page]

要把某个页面排除在这两个文件之外，在它的 frontmatter 里设置 `ai.exclude`：

```mdx
---
title: Internal notes
ai:
  exclude: true
---
```

该页面照常渲染、照常被搜索收录，也照常留在 sitemap 里 —— 只有 `llms.txt` 系列文件会跳过它。

## 自带文件

想完全掌控其中某个文件，就把你自己的 `llms.txt` 或 `llms-full.txt` 放进 `public/` 目录。就像自定义 favicon 一样，它会被自动识别并代替生成的文件发布 —— 覆盖其中一个，Blume 仍会生成另一个。

---

# 面向智能体的 Markdown
Source: https://blume.ndjp.net/docs/discoverability/markdown/
English: https://useblume.dev/docs/discoverability/markdown

HTML 是给浏览器用的。智能体和 LLM 用你的页面所写的 Markdown 表现更好 —— token 更少、没有界面装饰，组件也以模型能读懂的形式渲染。Blume 在开发和生产环境下都为每个页面提供这份 Markdown，无需任何配置。

## 原始 Markdown [#raw-markdown]

在任何页面 URL 后加上 `.md` 或 `.mdx`，即可取到它的 Markdown 源码 —— 非常适合 LLM、编码智能体和“复制为 Markdown”这类工作流。

| URL | 返回 |
| - | - |
| `/quickstart` | 渲染后的页面 |
| `/quickstart.md` | 纯 Markdown，组件已转换 |
| `/quickstart.mdx` | MDX 源码，组件保持原样 |

嵌套路由同理（`/content/syntax.md`），首页则在 `/index.md` 提供。

`.md` 变体会把组件_降级_为纯 Markdown，以适配无法解释 JSX 的消费方：`<TypeTable>` 变成 Markdown 表格，`<Callout>` 变成带标签的引用块，`<Steps>` 变成有序列表，`<Tabs>` 变成加粗标题的小节，`<Card>` 变成“标题作为链接、正文在下方”（`<CardGroup>` 则变成其中的卡片），`<Accordion>` 变成加粗的问题加对应答案，`<FileTree>` 变成它的列表，`<CodeGroup>` 变成带标题的代码块，`<YouTube>` 变成一个链接，其它每个内置组件 —— Columns、Frame、Expandable、Badge、Tooltip 等 —— 都变成它可读的内容。需要类型检查器的 `<AutoTypeTable>` 保持原样，从文件读取两侧内容的 `<Diff>`（`src`，或 `before` 与 `after`）和缺少 `owner`、`repo` 的 `<GithubInfo>` 也是如此。生成的 [API 参考](/docs/references/openapi/)页面由哪些组件构成，也一样会被降级：`<Operation>` 变成用其规范自身写法表示的接口（`GET /pets/{id}`、`SEND user/signup`、`query pets`）并带上弃用标记，`<ApiTagOperations>` 变成这些接口的列表，连到各自页面并附摘要，`<ApiOverview>` 变成 API 的版本和基础 URL —— 于是阅读参考页的智能体知道该调用什么，站内搜索也能匹配到接口路径。属性按字面数据读取，绝不执行 —— 字符串、数字、布尔值、数组、对象和模板字符串，还有对页面 `frontmatter` 的引用，因此像 `title={frontmatter.status}` 这样的属性会解析成渲染页面所显示的同一个值。任何无法忠实转换的东西 —— 自定义组件，或由函数调用、import 计算出来的属性 —— 都原样保留；代码里的组件标记，无论是围栏代码块还是行内代码，都不会被改动。同样的转换也适用于 [`llms-full.txt`](/docs/discoverability/llms-txt/) 和 [MCP 服务器](/docs/discoverability/mcp/)的 `get_page` 工具，因此每个面向智能体的入口读到的都是干净的 Markdown。

如果你要的就是 MDX 本身，用 `.mdx` 变体：它的组件保持原样，其余部分像 `.md` 变体一样，为按 URL 阅读它的智能体做好准备。[Includes](/docs/content/includes/) 会被拼接进来，[`<Visibility>`](/docs/content/components/) 会按对智能体的方式解析（`for="web"` 的内容被移除，保留 `for="agents"` 的内容），相对图片指向它们实际提供的位置，相对页面链接指向它所指的路由，而根相对链接（`/guides/install`）会带上站点的 `deployment.base` 和 `basePath`，在翻译过的页面上还会移入该页面的 locale，就像渲染页面的链接那样。根相对图片以及指向 `public/` 中文件的链接（`/spec.pdf`）只加上 `deployment.base`，因为那些文件正是在那里提供的。

### 内容协商 [#content-negotiation]

智能体不需要知道 `.md` 这个约定：请求页面本身的 URL 并带上 [`Accept: text/markdown`](https://acceptmarkdown.com) 头，就会在同一地址拿到 Markdown 变体，同时带 `Vary: Accept`，让缓存把两者分开。开发服务器开箱即用地遵守这个头，而 [Vercel 或 Cloudflare 的服务端构建](/docs/deployment/)会自动把同样的协商接进部署 —— Vercel 上是路由规则，Cloudflare 上是生成的 Worker —— 无需任何配置。首页始终参与协商，即便它是自定义落地页而非内容页面：它的 Markdown 镜像会回退到 [`llms.txt`](/docs/discoverability/llms-txt/) 索引，因此向站点根请求 Markdown 的智能体拿到的是整个站点的机器可读地图。Markdown 响应还会带上 `x-markdown-tokens` 头 —— 一个估算的 token 数（每个 token 约 4 个字符），遵循 [Cloudflare 的 Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) 的约定 —— 在 Blume 能控制响应头的每个入口上：开发服务器、服务端渲染的响应，以及 Vercel 和 Cloudflare 上参与协商的首页。其它部署目标从静态层提供预渲染页面，没有请求时钩子，因此那里的智能体要直接抓取 `.md` URL；[智能体可读性清单](/docs/discoverability/agent-discovery/)只在真正遵守该头的部署上才声明 `contentNegotiation`。

缺失的页面同样参与协商。默认的 [404 页面](/docs/advanced/custom-pages/)在 `/404.md` 有一个 Markdown 双胞胎 —— 先是未找到提示，然后是指向每个顶层分区、sitemap 和 `llms.txt` 的补救链接 —— 并且在 Vercel 或 Cloudflare 的服务端构建上，请求一个不存在的 URL 且偏好 Markdown 时，返回的是这段正文加上真实的 `404` 状态，而不是 HTML 外壳。在 Vercel 上，任何背后没有页面的 `.md` URL 同理。你自己的 404 页面（`pages/404.astro`，或 `/404` 处的一个内容页面）会连同它的 `/404.md` 双胞胎一起替换掉默认页面，此后缺失的页面就用你的 HTML 页面作答。

### 自定义组件序列化器

用 `agents.markdownComponents` 给你自己的组件一个 Markdown 形态 —— 一张从 JSX 名字到序列化器的映射。每个序列化器会收到该组件的 `props`（按字面数据从 MDX 属性中读取，其中 `frontmatter` 引用已被解析）、它的 `children`（已降级为 Markdown）以及页面的 `frontmatter` 数据，并返回替换后的内容 —— 或返回 `null` 让 JSX 保持原样：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import type { ComponentMarkdown } from "blume";

const chart: ComponentMarkdown = ({ props }) =>
  `![${props.title}](/charts/${props.slug}.png)`;

export default defineConfig({
  agents: {
    markdownComponents: {
      Chart: chart,
    },
  },
});
```

对容器组件，`childComponents("Name")` 按标签取出直接子元素 —— 内置 `<Steps>` 序列化器正是这样收集它的 `<Step>` 条目的 —— 而 `childBlocks()` 按顺序返回每一个直接子元素，组件和普通段落都算，每个都已降级为一块 Markdown（内置的 `<CardGroup>` 序列化器不过就是把这些块用空行连起来）。同名条目会替换内置序列化器，因此你可以改变 `<Callout>` 的降级方式 —— 或返回 `null` 把它整个排除掉。

序列化器写在 `blume.config.ts` 里，而不是 `components.tsx`：配置文件会在构建时执行，而组件文件只做静态分析（它可能 import `.astro` 文件，那些文件无法在站点构建之外运行）。你的组件本身仍照旧在 `components.tsx` 中注册 —— `markdownComponents` 只是额外提供了它们面向智能体的 Markdown 形态。

## 复制为 Markdown [#copy-as-markdown]

每个页面都有一个**复制为 Markdown** 操作 —— 位于目录下方的[页面操作](/docs/content/navigation/)里 —— 它会把页面的 Markdown 源码复制到剪贴板。它就是上面[`.md` URL](#raw-markdown)所提供的那份源码，可以直接粘贴给 LLM、贴进 issue，或存进你的笔记。它在每个页面、在开发和生产环境下都可用，无需任何配置。

在剪贴板 API 不可用或浏览器拒绝授权时 —— 应用内浏览器、WebView、不安全的来源 —— 该操作会回退到传统的复制命令；如果剪贴板里仍然什么都没进去，按钮会提示**复制失败**（通过 `actions.copyFailed` 本地化），而不是默默无反应。Blume 渲染的每个复制按钮都共用这层回退。

## 在对话中打开

**在对话中打开**操作会在 AI 助手中打开当前页面 —— v0、ChatGPT、Claude、T3 Chat、Scira 或 Cursor —— 并预填一段提示词，指向该页面的 Markdown 源码，让它能回答你正在读的内容的问题：

> Read `https://your-site/this-page.md` so I can ask you questions about this page.

和复制为 Markdown 一样，它无需任何设置。助手通过页面的公开 URL 抓取内容，因此页面一部署就能用。

这段提示词属于[界面文案字典](/docs/content/i18n/)（`actions.openInChatPrompt`），因此本地化站点会以自己的语言发送它，`i18n.ui` 也可以覆盖其措辞 —— 请保留 `{url}` 占位符，它会被替换成该页面的 Markdown 源码 URL。

想定制这个操作，设置 `ai.openInChat`。`false` 会完全隐藏它；一个提供方键的数组 —— `"v0"`、`"chatgpt"`、`"claude"`、`"t3"`、`"scira"`、`"cursor"` —— 则只显示你列出的这些提供方，并按你列出的顺序排列：

```ts blume.config.ts lineNumbers
ai: {
  openInChat: ["claude", "chatgpt", "cursor"],
}
```

如果想在内容中内嵌一段现成可复制的提示词 —— 而不是整页操作 —— 请使用 [Prompt 组件](/docs/content/components/)，它会渲染一行带标签的内容，含一个**复制提示词**按钮和一个可选的“在 Cursor 中打开”链接。

---

# MCP 服务器
Source: https://blume.ndjp.net/docs/discoverability/mcp/
English: https://useblume.dev/docs/discoverability/mcp

托管一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，让编码智能体（Claude Code、Cursor、VS Code、claude.ai 连接器）能直接检索和阅读你的文档 —— 无需抓取解析。它需要手动开启：

```ts blume.config.ts lineNumbers
agents: {
  mcp: {
    enabled: true,
    route: "/mcp", // 服务器挂载的位置
  },
}
```

| 选项 | 默认值 | 说明 |
| -------------- | ------- | ------------------------------------------------- |
| `enabled`      | `false` | 生成并托管 MCP 服务器。                 |
| `route`        | `/mcp`  | Streamable-HTTP 端点挂载的路径。  |
| `name`         | title   | 展示给客户端的服务器名称（默认为 title）。 |
| `instructions` | —       | 传给连接方智能体的可选系统提示。 |

如果该路由已被某个内容页或自定义页面占用，服务器就不会被生成：构建会给出警告，`llms.txt` 和其它[发现文档](/docs/discoverability/agent-discovery/)也会把它排除。

## 工具与资源

服务器暴露一组只读工具 —— `search_docs`、`get_page`、`list_pages` 和 `get_navigation` —— 并把每个页面作为一个 MCP resource 暴露（`resources/list` 按页面实际提供的 URL 枚举它们，类型为 `text/markdown`，未翻译页面的 i18n 回退副本与 `list_pages` 一样被排除；`resources/read` 返回页面的[面向智能体的 Markdown](/docs/discoverability/markdown/)，与 `get_page` 的输出相同），因此那些按 URI 附加上下文的客户端无需调用任何工具就能浏览文档。它在 `/.well-known/mcp.json` 和 `/.well-known/mcp/server-card.json` 发布发现文档。这份服务器卡片遵循 [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) 的 Server Card 扩展 schema（反向 DNS 形式的 `name`、`remotes` 传输端点），并带有 initialize 形状的兼容字段（`serverInfo`、`capabilities`、`transports`），供按该提案早期版本构建的扫描器使用。每个页面的**连接到 MCP**菜单都提供面向 Claude Code、Cursor、VS Code 和 Codex 的“复制即用”安装方式（当 [`deployment.site`](/docs/deployment/) 已设置后出现）。

`search_docs` 使用自己的全文索引，因此无论你的[搜索](/docs/configuration/search/)提供方是什么它都能工作 —— 即使设了 `search: false` 也可以。MCP 服务器与页面内搜索是两个彼此独立的功能。

同一套工具也以普通 HTTP 的形式作为 [JSON API](/docs/discoverability/json-api/) 提供，服务于那些不会说 MCP 的框架。

该端点最多只读取 64 KB 的请求体，更大的请求一律以 `413` 应答。调用不存在的工具，或 `arguments` 不是对象的调用，会得到 JSON-RPC 的 Invalid params 错误（`-32602`）。

## 按内容类型和 facets 限定范围

`search_docs` 和 `list_pages` 都接受可选的 `contentTypes` 过滤器，把结果收窄到 frontmatter 中 [`type`](/docs/content/frontmatter/) 为指定值的页面 —— `["rfc"]`、`["blog", "changelog"]` —— 因此面对一个把文档与 RFC、运行手册或规范混在一起的站点的智能体，可以把检索限定在它需要的那类页面上。每条结果都会标出它的内容类型，`list_pages` 的输出也会显示正在使用的类型。

两个工具还都接受一个 `filters` 对象，用于匹配站点按内容类型声明的 facets（[`content.types.<type>.facets`](/docs/configuration/)）—— 也就是那些值会变成可过滤元数据的自定义 frontmatter 键：

```json
{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}
```

`filters` 中的每一项都必须匹配（结果会带上自己的 facet 值，`list_pages` 也会显示每个页面的值），因此知识库无需自建服务器，就能驱动渐进披露式的智能体工作流 —— 先列出强制标准，再只在其中检索。

## 需要服务端输出

MCP 服务器是一个实时端点（`/mcp`），因此无法运行在静态构建上。指定一个来自 `blume/deploy` 的宿主适配器即可切换到服务端输出：

```ts blume.config.ts lineNumbers
import { node } from "blume/deploy"; // 也可以是 vercel、netlify、cloudflare

export default defineConfig({
  deployment: node({ site: "https://docs.example.com" }),
});
```

在开启 `agents.mcp.enabled` 的情况下做静态构建会立刻失败，并提示你设置一个宿主适配器。可用适配器参见[部署](/docs/deployment/)。部署完成后，在 Claude Code 中这样连接：

```bash
claude mcp add --transport http my-docs https://docs.example.com/mcp
```

---

# 元数据
Source: https://blume.ndjp.net/docs/discoverability/metadata/
English: https://useblume.dev/docs/discoverability/metadata

每个页面都会根据你的配置和 frontmatter 渲染标准的 `<head>` 标签 —— 无需任何配置。凡是可以调整的值，都放在 `blume.config.ts` 的 `seo` 键下，或页面的 frontmatter 的 `seo` 下。

- `<title>` —— 页面标题加上你的站点 `title`。
- `<meta name="description">` 和 `og:description` —— 页面的 `description`，回退到站点的 `description`。
- `og:title` 和 `og:site_name` —— 页面标题和你的站点 `title`。
- `<link rel="canonical">` 和 `og:url` —— 页面的绝对 URL（当 [`deployment.site`](/docs/deployment/) 已设置时）。
- `og:type` —— blog 文章和更新日志条目为 `article`，其他页面为 `website`。文章页面还会根据页面的 `date` 和最后修改时间输出 `article:published_time` 与 `article:modified_time`。
- `og:image` —— 该页面的 [OG 图片](/docs/discoverability/open-graph/)。生成的卡片同时会声明自己的 `og:image:width`、`og:image:height`、`og:image:type` 和 `og:image:alt`，这样爬虫不必先抓取就能完成排版；你自己提供的 `seo.image` 则不声明这些，因为它的尺寸和格式未知。
- `twitter:card`、`twitter:title`、`twitter:description`、`twitter:image` —— X 卡片。有图片的页面会得到宽版的 `summary_large_image`；没有图片的页面仍会得到紧凑的 `summary` 卡片，而不是渲染成一条裸链接。

## X 归属

X 从 `og:*` 标签读取卡片上的其他一切内容，因此它唯一无法推断的就是要署名的账号。把它们设在 `seo.x` 下，Blume 会输出 `twitter:site`（你的站点账号）和 `twitter:creator`（作者的账号）。`@` 是可选的 —— `acme` 和 `@acme` 都可以。

```ts blume.config.ts lineNumbers
seo: {
  x: { handle: "@acme", creator: "@jane" },
}
```

页面可以指定自己的作者，客座文章正需要这样做：

```yaml lineNumbers
---
title: How we shipped it
seo:
  x:
    creator: "@guestauthor"
---
```

## 你自己的标签

对于 Blume 没有提供设置的一切，在 `seo.metatags` 下添加标签，每个页面都会带上它们 —— 自定义页面和 API 参考页也不例外。它适合放来自 Google、Bing 或 Facebook 的站点验证令牌、一个 `theme-color`，或者应用横幅：

```ts blume.config.ts lineNumbers
seo: {
  metatags: {
    "google-site-verification": "abc123",
    "msvalidate.01": "def456",
    "theme-color": "#0b5fff",
    "apple-itunes-app": "app-id=123456789",
  },
}
```

每个键是标签名，每个值是它的内容。Open Graph 系列（`og:`、`fb:`、`article:` 等）按协议规定用 `property` 渲染，其他一切用 `name`。Blume 自己写出的那些标签（列在本页顶部）不能在这里设置，因此一个页面永远不会为同一个标签带上两个值。构建结果会指出控制每个标签的设置：`og:image` 来自 [`seo.og`](/docs/discoverability/open-graph/) 或页面的 `seo.image`，而 `robots` 来自页面的 `seo.noindex`。

## 逐页面覆盖 [#per-page-overrides]

用 `seo` frontmatter 逐页面覆盖其他任意标签：

```yaml lineNumbers
---
title: Pricing
description: Plans and pricing for every team size.
seo:
  title: Plans and pricing
  canonical: https://acme.com/pricing
  noindex: false
---
```

| 属性 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `seo.title?` | `string` | - | 替换 `<title>`、`og:title` 和 `twitter:title` 中的页面标题。站点标题仍会追加在后面：在标题为 Acme Docs 的站点上，上面的例子会渲染成 “Plans and pricing - Acme Docs”。 |
| `seo.description?` | `string` | - | 覆盖 meta 和 `og:description`。 |
| `seo.image?` | `string` | - | 自定义社交图片（参见 Open Graph 图片）。 |
| `seo.canonical?` | `string` | - | 覆盖 canonical URL。 |
| `seo.noindex?` | `boolean` | - | 输出 robots noindex 并跳过结构化数据。 |
| `seo.x.creator?` | `string` | - | 把这个页面署名给某个 X 账号（`twitter:creator`），覆盖配置里的 `seo.x.creator`。 |

标记为 `noindex` 的页面也会退出 [sitemap](/docs/discoverability/sitemap-and-robots/)，并跳过[结构化数据](/docs/discoverability/structured-data/)。

---

# Open Graph 图片
Source: https://blume.ndjp.net/docs/discoverability/open-graph/
English: https://useblume.dev/docs/discoverability/open-graph

得益于 [Takumi](https://takumi.kane.tw)，Blume 能在构建时为每个页面渲染一张 1200×630 的社交卡片 —— 不需要无头浏览器，因此构建依然很快。当 [`deployment.site`](/docs/deployment/) 已设置或被自动检测到时它默认开启（`og:image` 的 URL 必须是绝对地址，对爬虫才有用），否则关闭。无论哪种情况，都可以设置 `enabled` 来覆盖这个默认行为：

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // 或设为 false，即使已设置站点也退出
}
```

## 为生成的卡片打上品牌

设置一个本地 SVG 和一套配色，让生成的卡片与你的品牌一致。logo 可以放在 `public/` 下或项目根目录。配色中任何一项留空即保留默认值。

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

默认情况下，每张卡片都由你的内容和主题推导而来 —— 以**页面标题**作为大标题，以**页面描述**作为副标题（与它的 `og:description` 是同一段文字，因此 `seo.description` 优先于 `description`），并用主题的 **accent** 作为标记；在你还没有设置 logo 时，标记里显示的是**站点标题**的首字母。图片以 `/og/<slug>.png` 提供，与每条路由一一对应；即使在服务端模式下也会预渲染为静态文件：

| 页面路由 | 图片 URL |
| - | - |
| `/` | `/og/index.png` |
| `/quickstart` | `/og/quickstart.png` |
| `/guides/deploy` | `/og/guides/deploy.png` |

用 `seo.image` 为任意页面覆盖生成的卡片 —— `public/` 下的文件或一个外部 URL 都可以。它的优先级高于生成的卡片，即使 `og` 关闭也照样生效，因此你可以把自定义图片和生成的图片混用：

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
每个配色项都接受任意 CSS 颜色 —— hex、`oklch(…)`、`rgb(…)` 等等。accent 还接受命名预设（`blue`、`teal`……），与 [`theme.accent`](/docs/configuration/theming/) 一致。渲染器无法解析的颜色会让构建失败，而不是悄悄输出一张默认配色的卡片。
:::

页面标题或站点标题中的 emoji 会渲染成 [Twemoji](https://github.com/jdecked/twemoji) 字形，在卡片渲染时从 CDN 抓取 —— 因此标题含 emoji 的构建需要网络访问。不过每个字形每次构建只抓取一次，无论多少页面用到它。

## 显示、隐藏或覆盖卡片图层

除大标题之外，卡片还带有三个可选图层：左上角的**品牌标记**（你的 logo，或一个填有站点标题首字母的 accent 色块）、大标题下方的**副标题**（页面的 `description`；没有时用站点的 `description`），以及一个包含你的仓库短名（来自 `github`）和站点 URL 的**页脚** —— 即部署站点的 host 加上 [`deployment.base`](/docs/deployment/)，因此一个 GitHub Pages 项目站会显示 `user.github.io/repo`。其中任意一项都可以用你自己的字符串覆盖，或用 `false` 隐藏：

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // 页脚的 URL 文字，或设为 false 隐藏它
    description: false, // 在每张卡片上隐藏副标题；给字符串则替换站点回退值
    logo: false, // 完全不要品牌标记 —— 连首字母色块也没有
  },
}
```

## 卡片字体 [#card-fonts]

默认情况下，卡片使用 Takumi 的内置字体渲染，它只覆盖基本的拉丁字形 —— 单靠它，日语、中文、韩语、阿拉伯语、印地语、俄语等其它文字的标题会渲染成豆腐块（空方框）。

**默认覆盖所有文字体系。** 在内置字体之后，卡片带有一组 Google Noto 字体的回退栈，每种文字体系一个：西里尔文、希腊文、越南文和带附加符号的拉丁文用 `Noto Sans`，然后是 `Noto Sans JP`、`Noto Sans Arabic`、`Noto Sans Devanagari` 等等。日语或印地语标题无需任何配置就能正确渲染，即使站点没有配置任何 [locales](/docs/content/i18n/)。回退按字形生效，因此拉丁文本仍使用内置字体。只有当卡片文字中出现内置字体画不出的字形时，它才会去 Google Fonts 抓取，而且只抓这些字形所需的子集：一张纯英文的卡片什么都不抓，因此只有拉丁文字的站点依然可以离线构建。除非设置 `og.fonts`（它会接管整份列表），否则都用上面这组回退栈。

中文、日文和韩文共用大部分汉字，但其中一些字的写法不同，而卡片默认使用日文字形。每个已配置的 locale 会把对应的字族排到最前面，因此带 `zh` locale 的站点会用简体字形渲染汉字，`zh-Hant` 或 `zh-TW` 则用繁体字形。

**设置 [`theme.fonts`](/docs/configuration/theming/)，卡片就会跟着它走。** 当你的配置挑选了自己的字体时，生成的卡片会自动用 display 字体渲染大标题，用 body 字体渲染描述和页脚，于是分享出去的链接与站点保持一致 —— 非拉丁文字的覆盖也自动包含在内，这里无需任何配置。（来自非 Google 提供方的字族会被跳过 —— 卡片渲染器只能从 Google Fonts 抓取 —— 但本地字体文件是可用的。）

如果想让卡片用上与站点不同的字体，请显式设置 `og.fonts`。它总是优先于从主题推导出的字体，并替换掉那组文字体系回退，因此请把卡片需要的每个字族都列出来：

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

每一项要么是一个 Google Fonts 字族名，要么是一个对象，用来固定它的 `weight`（一个数字、一个列表，或像 `"100..900"` 这样的可变区间）和 `style`（`"normal"`、`"italic"`，或两者同时），要么是一个本地字体文件 —— `src` 从项目根目录解析；当不希望由文件自身元数据来决定时，可以附带可选的 `weight` 和 `style`。

Google 字族是在构建时抓取的 —— 因此用到它们的构建需要网络访问 —— 而且渲染器只会拉取每个标题实际用到的字形子集。回退按字形生效，因此新增一个字族只影响其它字体画不出的字形。

显式写出 `og.fonts: []` 则是完全退出：即使设置了 `theme.fonts`、或标题需要文字体系回退，卡片也仍然使用内置字体。

## 卡片缓存 [#card-cache]

渲染好的卡片会在构建之间缓存到磁盘，缓存键由所有决定其像素的因素构成：页面标题和描述、品牌文字、logo、配色、页脚文字和字体（本地字体文件按其内容计算），再加上 Blume 版本。重新构建时只渲染输入发生变化的卡片，其余直接从缓存读回；构建日志会报告复用了多少张。缓存位于 `node_modules/.cache/blume/og`；在构建之间保留 `node_modules` 的平台上（Vercel 和 Netlify 会，Cloudflare 不会），或者会缓存该目录的 CI runner 上（参见[构建缓存](/docs/deployment/)），只改动少数页面的部署就只会重新渲染少数几张卡片。没有任何页面用到的卡片会在每次构建后被删除，因此这个目录里始终只有当前站点的卡片。

## 自定义页面标题

自定义的 [`.astro` 页面](/docs/advanced/custom-pages/)没有 frontmatter 可读，因此它生成的卡片标题来自对其路由最后一段 URL 做“人类化”处理 —— `/getting-started` 会变成 “Getting Started”，而 `/cli` 会变成 “Cli”。用 `og.titles` 按路由显式指定这些卡片的标题（`"/"` 对应首页，它的卡片默认带的是站点标题）：

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

这些条目只对自定义页面生效 —— 内容页面的卡片大标题始终取自页面标题，所以那些页面请在 frontmatter 里改标题。

`seo.image` 是 frontmatter，所以它只覆盖 Markdown 和 MDX 内容。若想让自定义的 [`.astro` 页面](/docs/advanced/custom-pages/)拥有自己的社交图片 —— 营销首页或落地页，以及只给首页定制分享图的方式 —— 给 `PageLayout` 传入 `ogImage` 属性。

---

# RSS 订阅源
Source: https://blume.ndjp.net/docs/discoverability/rss/
English: https://useblume.dev/docs/discoverability/rss

Blume 会为 `seo.rss.types` 中每一个有页面的内容类型构建 RSS 订阅源 —— 默认是 `blog` 和 `changelog` —— 访问路径为 `/<type>/rss.xml`。如何撰写带日期的 blog 和更新日志条目，参见[订阅源](/docs/content/)。

订阅源中的链接必须是绝对的，因此订阅源需要一个站点 URL：设置 [`deployment.site`](/docs/deployment/)，或者部署到 Blume 能自动检测到它的托管平台（Vercel、Netlify、Cloudflare）。没有站点 URL 时，构建完全不会输出任何订阅源。在 `blume dev` 期间会由本地服务器的 URL 顶替，所以在那儿订阅源总是能看到。

```ts blume.config.ts lineNumbers
seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}
```

| 选项 | 默认值 | 说明 |
| - | - | - |
| `enabled` | `true` | 生成订阅源。 |
| `types` | `["blog", "changelog"]` | 各自获得一个订阅源的内容类型。 |
| `limit` | `50` | 每个订阅源最多条目数，最新的在前。 |

Blume 会注入 `<link rel="alternate">` 标签，让浏览器和订阅源阅读器自动发现这些订阅源，并把它们列在[智能体可读性清单](/docs/discoverability/agent-discovery/)里，让智能体也能找到。每个条目都指向该页面的绝对 URL。

---

# Sitemap 与 robots
Source: https://blume.ndjp.net/docs/discoverability/sitemap-and-robots/
English: https://useblume.dev/docs/discoverability/sitemap-and-robots

搜索爬虫和 AI 爬虫都从站点根目录的同两个文件入手。Blume 每次构建都会写出这两个文件，而 `robots.txt` 承载着 AI 爬虫会去找的内容使用信号 —— 因此这里是可发现性的搜索侧与智能体侧的交汇点。

## Sitemap [#sitemap]

Blume 在构建时写出一份包含每个可索引页面的 `sitemap.xml`。它需要一个绝对的 [`deployment.site`](/docs/deployment/)，并列出除草稿、隐藏和 [`noindex`](/docs/discoverability/metadata/) 页面之外的所有页面。在[带版本](/docs/content/versioning/)的站点上，canonical 指向线上对应页面的归档页面也会被排除 —— 该被索引的是线上页面。默认开启：

```ts blume.config.ts lineNumbers
seo: {
  sitemap: true,
}
```

放入自己的 `public/sitemap.xml` 即可接管 —— Blume 绝不会覆盖你放在 `public/` 里的文件。

## Robots [#robots]

Blume 写出的 `robots.txt` 允许所有爬虫访问，声明你的[内容信号](#content-signals)，并在有 sitemap 时加上一行指向它的 `Sitemap:`。默认开启：

```ts blume.config.ts lineNumbers
seo: {
  robots: true,
}
```

```txt robots.txt
User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://docs.example.com/sitemap.xml
```

### 内容信号 [#content-signals]

`Content-Signal` 这一行 —— 正在成形的内容使用约定 —— 声明 AI 爬虫可以如何复用你的文档。Blume 默认输出它，**且每个信号都设为 `yes`**，这与它「文档对人和智能体一律开放」的立场一致：

- `search` —— 传统搜索与 AI 搜索索引
- `aiInput` —— 回答时的 grounding / RAG
- `aiTrain` —— 模型训练

把任一信号设为 `false` 即可限制它；不写的那些仍为 `yes`：

```ts blume.config.ts lineNumbers
agents: {
  contentSignals: {
    aiTrain: false, // 退出训练，保留搜索与 grounding
  },
}
```

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

设置 `contentSignals: false` 即可完全去掉这行声明：

```ts blume.config.ts lineNumbers
agents: {
  contentSignals: false,
}
```

| 属性 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `agents.contentSignals?` | `boolean \| object` | - | `Content-Signal` 声明。为 `true` 或不写时所有信号都输出为 yes；为 `false` 时删掉这一行；为对象时逐个设置信号。 |
| `contentSignals.search?` | `boolean` | - | 允许用于搜索索引（`search`）。默认 `true`。 |
| `contentSignals.aiInput?` | `boolean` | - | 允许在回答时用于 AI grounding / RAG（`ai-input`）。默认 `true`。 |
| `contentSignals.aiTrain?` | `boolean` | - | 允许用于 AI 模型训练（`ai-train`）。默认 `true`。 |

内容信号表达的是一种偏好，而不是访问控制：它告诉守规矩的爬虫你希望内容被如何使用，而是否遵守由爬虫自己负责。同一份策略会以 `contentUsage` 的形式镜像在[智能体可读性清单](/docs/discoverability/agent-discovery/)里，因此从不读 `robots.txt` 的智能体也能看到它。

放入自己的 `public/robots.txt` 即可接管。

---

# 结构化数据
Source: https://blume.ndjp.net/docs/discoverability/structured-data/
English: https://useblume.dev/docs/discoverability/structured-data

Blume 会在每个页面的 `<head>` 中输出 [schema.org](https://schema.org) JSON-LD，让搜索引擎理解你的内容。默认开启：

```ts blume.config.ts lineNumbers
seo: {
  structuredData: true,
}
```

每个页面包含：

- 一个用于标识站点的 **WebSite** 节点，
- 把页面本身作为 **article** —— blog 文章为 `BlogPosting`，更新日志和文档为 `TechArticle` —— 带上它的描述和发布日期，
- 一个由导航路径构建的 **BreadcrumbList**。

当 [`deployment.site`](/docs/deployment/) 已设置时，URL 是绝对的。标记了 [`seo.noindex`](/docs/discoverability/metadata/) 的页面会被跳过。当 [`lastModified`](/docs/configuration/) 开启时，每个页面的日期还会作为 `dateModified` 输出。

## 站点标识

WebSite 节点只说明存在这样一个站点；它没说这是_什么_，也没说由_谁_运营 —— 而 AI 智能体在推荐或引用你之前，读 JSON-LD 正是为了这些。有两个可选配置块可以补上这些信息，它们都需要 `deployment.site`（这些节点带的是绝对标识符）：

```ts blume.config.ts lineNumbers
seo: {
  organization: {
    name: "Acme", // 默认为站点标题
    email: "hello@acme.com",
    telephone: "+1 555 0100",
    address: { addressLocality: "Sydney", addressCountry: "AU" },
    logo: "/logo.svg",
    sameAs: ["https://github.com/acme", "https://x.com/acme"],
  },
  software: {
    license: "MIT",
    operatingSystem: "Node.js 22+",
    price: 0, // 输出为 Offer；0 表示免费
    sameAs: ["https://www.npmjs.com/package/acme"],
  },
}
```

`organization` 会给每个页面加上一个 **Organization** 节点 —— WebSite 和 article 节点把它作为 `publisher` 引用 —— 其中邮箱和电话组成一个 `ContactPoint`（`contactType` 默认为 `"customer support"`），地址作为一个 `PostalAddress`，商业信息核验查的就是这两项。`name` 和 `url` 默认为站点的值；根相对的 `logo` 会像任何页面 URL 一样被转成绝对地址。

`software` 会给首页加上一个 **SoftwareApplication** 节点：产品名称和描述（默认取站点的）、`applicationCategory`（默认 `"DeveloperApplication"`）、操作系统、许可证、设置了 `price` 时的 `Offer`，以及 `sameAs` 中的注册表或仓库 URL。传入 `software: true` 即可采用全部默认值。若配置了 organization，它会作为该节点的 `publisher` 被引用。

## 自定义页面

通过 `PageLayout` 渲染的自定义 [`.astro` 页面](/docs/advanced/custom-pages/)会输出同样的 `WebSite` 图谱，因此营销首页不会是唯一没有结构化数据的那个 URL。传入 `structuredDataEnabled={config.structuredData}` 让它与本设置保持同步，或传入 `structuredDataEnabled={false}` 单独为该页面关闭。

---

# 常见问题
Source: https://blume.ndjp.net/docs/faq/
English: https://useblume.dev/docs/faq

这里汇集经常被问到的问题的答案。还没找到你要的？[提一个 issue](https://github.com/haydenbleasel/blume/issues)，或者问问页面内的 assistant。

## Blume 与 Mintlify、Fumadocs 等有什么不同？

大多数文档工具都落在两个极端之一。像 Mintlify 这样的**托管平台**能很快给你一个打磨好的结果，但构建和托管都是他们的服务 —— 你在他们的系统里写作，部署到他们的基础设施上。像 Fumadocs、Nextra 或 Docusaurus 这样的**组件库和 starter** 是开源且灵活的，但他们会塞给你一个应用（一个 Next.js 或 React 项目），你得在写第一个字之前和之后都去脚手架、接线并维护它。

Blume 走第三条路：**框架就是模板。** 你把一个装满 Markdown 的文件夹指给它，它就生成并驱动整个站点 —— 导航、搜索、主题、Open Graph 图片、SEO 和 AI 端点 —— 你不需要拥有任何应用。它完全开源且可自托管，所以既没有托管服务也没有厂商锁定，但同样也没有样板代码要维护。

|  | Blume | Mintlify | Fumadocs / Nextra / Docusaurus |
| --- | --- | --- | --- |
| **模式** | 零配置框架；只有内容 | 托管平台 | 库 + 你要搭脚手架的应用 |
| **源码** | 开源（MIT） | 闭源核心 | 开源 |
| **托管** | 任意位置 —— 静态或服务器函数 | 他们的托管基础设施 | 任意位置；你自己构建和部署 |
| **你要维护** | 你的 Markdown | 你的 Markdown + 平台配置 | 你的 Markdown + 围绕它的那个应用 |
| **渲染** | Astro；核心主题零客户端 JS | 他们的运行时 | React/Next.js 运行时 |
| **AI 功能** | `llms.txt`、原始 Markdown、页面内 assistant、MCP —— 内置，无托管服务 | 内置（托管） | 自备 |

有几点后果值得单独指出：

- **产物归你所有。** `blume build` 产出的是一个普通站点，你可以把它托管在 Vercel、Netlify、Cloudflare、S3 或你自己的机器上。没有任何数据回传。
- **没有锁定，两条出路。** 你的内容是可移植的 Markdown，而 `blume eject` 会把项目变成一个独立的 Astro 应用，在你想完全掌控时它依然使用 `blume` 包。
- **默认就快。** 核心主题不含 React 并渲染静态 HTML，所以页面无需调优就能在 Core Web Vitals 上拿到好成绩。只有在需要时你才会开启服务端功能（assistant、MCP）。
- **类型安全的配置。** `blume.config.ts` 和每一个 `meta.ts` 都是由 schema 校验的真正 TypeScript —— 而不是弱类型的 YAML。

:::note
这并不是「比什么都好」—— 当你想要一个托管好的产品，或想要对应用的完全掌控时，托管平台和完整框架才是正确选择。Blume 是给那些既不想要拥有平台、也不想拥有管道设施，却仍需要一个生产级文档站的团队。
:::

更长的版本见[为什么会有 Blume](/docs/)。

## Blume 免费且开源吗？

是的 —— Blume 采用 MIT 许可，免费。你安装 `blume` 包，把内容留在自己的仓库里，并把构建产物托管在任何你喜欢的地方。没有付费档、没有按人计费，也不需要注册账号。源码在 [GitHub](https://github.com/haydenbleasel/blume)。

## 我需要了解 Astro、React 或 Tailwind 吗？

不需要。一个装满 Markdown 的文件夹就是一个完整站点 —— 导航、搜索和主题要么被推断出来，要么用几个 token 设定。只有当你想做定制时才会触及底层技术栈：[交互岛](/docs/content/islands/)（React）、[组件覆盖](/docs/configuration/customization/) 或[主题 token](/docs/configuration/theming/)（Tailwind）。即便如此，[`blume.config.ts`](/docs/configuration/) 也是有类型的，所以你的编辑器会引导你。

## 我可以用 React 组件和 MDX 吗？

可以。任意页面都可以是 `.md` 或 `.mdx`，而 MDX 让你[无需 import](/docs/content/components/)就能放入内置组件。你还可以添加自己的 `.tsx`/`.jsx` [交互岛](/docs/content/islands/)。只有当你的项目用到 React 时，Blume 才会开启它 —— 项目里存在任何 `.tsx` 或 `.jsx` 文件（包括你的交互岛）、一个 React 的 [`<Component>`](/docs/content/components/) 示例、一处[组件覆盖](/docs/configuration/customization/)，或[assistant](/docs/configuration/assistant/) —— 所以没有这些的站点不会带上任何框架 JavaScript。

## 我能部署到哪里？

任何地方。`blume build` 默认输出静态 HTML，你可以从任意静态托管或 CDN 提供它 —— Vercel、Netlify、Cloudflare Pages、GitHub Pages、S3 或你自己的服务器。仅服务端的特性（assistant、MCP server、按需渲染）需要服务端输出：把来自 `blume/deploy` 的一个托管适配器 —— `vercel()`、`netlify()`、`cloudflare()` 或 `node()` —— 指定为 `deployment`。见[部署](/docs/deployment/)。

## 搜索需要托管服务吗？

不需要。[Orama](/docs/configuration/search/) 会构建一份本地索引，在开发和生产环境中都能工作，没有任何东西需要托管或付费。对于非常大的站点，[Pagefind](/docs/configuration/search/) 只需换一个适配器：`search: pagefind()`。无论用哪一个，索引都会随你的站点一起发布。

## 我该怎么定制外观？

从[主题 token](/docs/configuration/theming/) 开始 —— 强调色、字体、圆角，以及一个用于处理 Tailwind 能表达的一切其它样式的 `theme.css`。想更进一步，可以[覆盖内置组件](/docs/configuration/customization/)或添加[自定义页面](/docs/configuration/customization/)。当你想要 Astro 项目本身时，[`blume eject`](/docs/configuration/customization/) 会交给你一个独立应用，且它依然使用 `blume` 包。

## 为什么 oxfmt / Ultracite 会把我的指令压成一行？

如果你用 [Ultracite](https://www.ultracite.ai)（它跑的是 oxlint + [oxfmt](https://oxc.rs)）来格式化 Markdown —— Blume 自己也这么做 —— 你可能会发现容器指令在一次格式化之后被压成了单行：

```md
:::note
用 blume dev 重新生成项目。
:::
```

变成了

```md
:::note 用 blume dev 重新生成项目。 :::
```

一旦开头的 `:::note` 围栏和正文连成了一行，它就不再是指令，于是会作为字面文本渲染，而不是一个[提示框](/docs/content/syntax/)。

### 为什么会这样

这是 oxfmt 的 Markdown 格式化器里的一个 bug（继承自 Prettier 的 Markdown printer —— 见 [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)）。当它换行正文时，会把 `:::` 围栏行当成普通文本，并把它们与相邻行连起来，于是指令就坏了。它影响所有类型的容器指令 —— `:::note`、`:::tip`、`:::info`、`:::warning`、`:::danger`、`:::success`。

我们在上游的 [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096) 报告了它；在那里修好之前，下面的补丁是变通方案。

### 修复办法

给 oxfmt 打补丁，让它保留紧挨着 `:::` 围栏的那个换行。Blume 在自己的仓库里带了同样的修复，你可以把它应用到任何项目里。

1. 把补丁保存为 `patches/oxfmt@0.67.0.patch`：

   ```diff patches/oxfmt@0.67.0.patch
   diff --git a/dist/markdown-BMigo7Hm.js b/dist/markdown-BMigo7Hm.js
   index bc9037f6c0de5516b139d8cdb195b1e25cd33bc0..a02c284e28bb535f9964a8a086ebb6549657e416 100644
   --- a/dist/markdown-BMigo7Hm.js
   +++ b/dist/markdown-BMigo7Hm.js
   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
   		case "sentence": return Oh(e, r);
   		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
   		case "whitespace": {
   -			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   +			let { next: a, previous: oxfmtFencePrev } = e;
   +			// Preserve line breaks that sit directly against a `:::` container
   +			// directive fence, so `proseWrap: "never"` keeps the opening/closing
   +			// fence on their own lines instead of joining them into the prose (which
   +			// breaks the directive). Ordinary prose still wraps per proseWrap.
   +			// See prettier/prettier#19040.
   +			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
   +			// linkReference between two sentence nodes at the paragraph level: the
   +			// fence word ends the sentence before the reference, and the body's
   +			// leading newline opens the sentence after it. So when this whitespace
   +			// starts its sentence, climb to the paragraph and check whether the two
   +			// preceding siblings are a (link) reference and a sentence ending in a
   +			// `:::` fence word.
   +			let oxfmtPrevIsTitledFence = !1;
   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
   +				if (oxfmtSentIdx >= 2) {
   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
   +				}
   +			}
   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
   +			// words, so the whole directive is one sentence. For a newline
   +			// whitespace, walk back to the start of its visual line within the
   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
   +				let oxfmtLineFirst = null;
   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
   +					let oxfmtSib = e.parent.children[oxfmtJ];
   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
   +					oxfmtLineFirst = oxfmtSib;
   +				}
   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
   +			}
   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
   			return ou(e, n.value, u, !1, t);
   		}
   		case "emphasis": {
   ```

2. 用包管理器的 `patchedDependencies` 注册它。用 Bun 的话，在 `package.json` 里加上：

   ```json package.json
   {
     "patchedDependencies": {
       "oxfmt@0.67.0": "patches/oxfmt@0.67.0.patch"
     }
   }
   ```

   用 pnpm 的话，加到 `pnpm-workspace.yaml`（pnpm 11 及更新版本不再从 `package.json` 读取设置）：

   ```yaml pnpm-workspace.yaml
   patchedDependencies:
     oxfmt@0.67.0: patches/oxfmt@0.67.0.patch
   ```

3. 重新安装，让补丁被应用：

   ```package-install
   bun install
   ```

:::warning[版本已固定]
该补丁针对某个特定的 oxfmt 构建 —— 它的 diff 引用了一个文件名按版本做哈希的文件（`dist/markdown-*.js`）。当你升级 oxfmt 时，请重新生成补丁（例如 `bun patch oxfmt`），或先确认上游的修复是否已经落地、补丁是否已不再需要。
:::

## 为什么 Knip 报告我的 `blume.config.ts` 依赖未被使用？

[Knip](https://knip.dev) 只会跟踪它已知入口文件的导入，而它是从内置插件里学到这些入口的。目前还没有 Blume 插件，而 Knip 的 Astro 插件也不会因此打开开关：它在你的 `package.json` 里找 `astro`，但 Blume 项目依赖的是 `blume`，且生成的 `.blume/` Astro 项目被 gitignore 了，所以 Knip 从来看不到它。没有任何地方引用 `blume.config.ts`，于是它导入的每个包都会被报告为未使用。

把 Blume 从你的项目根目录加载的那些文件注册为入口。在 `knip.json` 里：

```json knip.json
{
  "entry": [
    "blume.config.{ts,mjs,js}",
    "components.{ts,tsx}",
    "islands/**/*.{ts,tsx}",
    "pages/**/*"
  ]
}
```

在 monorepo 里，请把同一份 `entry` 列表放到 `workspaces` 中 docs workspace 之下。凡是你不用的约定都把对应那行删掉 —— 用于[组件覆盖](/docs/configuration/customization/)的 `components.ts`、用于[交互岛](/docs/configuration/customization/)的 `islands/`，以及用于[自定义页面](/docs/configuration/customization/)的 `pages/`（如果你改过 `content.pages`，最后那行要相应调整）。

Knip 只能跟踪真实的导入。一个只出现在字符串里的包 —— 比如一个调用 `injectScript("page", "import('some-package')")` 的 [Astro 集成](/docs/configuration/customization/) —— 仍然需要一条 `ignoreDependencies` 条目。

---

# Blume 文档
Source: https://blume.ndjp.net/docs/
English: https://useblume.dev/docs

把 Markdown 或 MDX 丢进一个文件夹，运行 `blume dev`，就得到一个生产级文档站 —— 导航、搜索、主题、Open Graph 图片，以及一套丰富的组件库 —— 完全不需要编写或维护任何应用样板代码。

**[快速上手](/docs/quickstart/)**

几分钟内安装 Blume 并发布你的第一个页面。

**[配置](/docs/configuration/)**

调整标题、主题、搜索和部署。

## 为什么会有 Blume

文档应该快速、对 AI 友好、且零配置 —— 甚至连 starter 模板都不需要。有些文档工具在你写第一个字之前，就先塞给你一整套需要维护的代码库。另一些会围绕你的内容生成模板，却把你锁定在它们的托管服务里。

Blume 两头的好处都要。框架本身就是模板，所以你唯一会去碰的永远只有内容本身。当你想定制时，可以从替换内置组件开始，也可以修改那一个配置文件，甚至可以直接 eject，拿到原始的 Astro 站点。[FAQ](/docs/faq/) 会讲清楚这与 Mintlify、Fumadocs 等方案相比究竟如何。

## Blume 有何不同

### 默认就快

Blume 构建在 Astro 和 Vite 之上，默认渲染静态 HTML —— 快、易缓存、托管成本低。核心主题不携带任何客户端框架 JS，因此页面开箱即得就能在 Core Web Vitals 上拿到好成绩。开发服务器启动和热重载都是原生的 Vite 体验，只有在需要时你才会主动开启服务端功能。

### 开箱即地对 AI 友好

每一个 Blume 站点都能流利地与机器对话。它会输出 [`llms.txt` 和 `llms-full.txt`](/docs/discoverability/llms-txt/)，在任意页面 URL 后加 `.md` 即可拿到该页的原始 Markdown，提供一个[由 OpenAPI 描述的 JSON API](/docs/discoverability/json-api/)，并在每个页面上给读者提供 **Copy as Markdown** 和 **Open in chat** 操作。你还可以加一个可选的页面内 **assistant**，或托管一个 [**MCP server**](/docs/discoverability/mcp/)，让 Claude Code、Cursor 之类的编码 agent 直接搜索和阅读你的文档 —— 无需抓取，也不依赖托管服务。你的 Markdown 对人类和模型同时是唯一事实来源。

### 零配置 —— 连模板也是

一个文档文件夹就是一个完整项目。没有 starter 需要 clone，没有 Astro 或 Tailwind 需要配置，也没有模板需要维护。导航从你的文件推断得出，[search](/docs/configuration/search/) 在开发和生产环境都能工作且不依赖托管服务，主题不过是几个 token。所有东西都有合理的默认值；配置是你需要时才去找的东西，而不是你必须先做的事情。

### 类型安全贯穿内核

你的 [`blume.config.ts`](/docs/configuration/) 和每一个 [`meta.ts`](/docs/content/meta/) 都是真正的 TypeScript —— 由 schema 校验，用 `defineConfig` 和 `defineMeta` 编写。你的编辑器会自动补全每一个选项，并在你输入时就捕获拼写错误、非法取值和缺失字段，远早于构建。配置是你可以重构、计算并信赖的代码 —— 而不是弱类型的 YAML。

## 全部包含

- **组件** —— 提示框、卡片、步骤、标签页、折叠面板、徽章、文件树和参数表，在 MDX 中[无需 import](/docs/content/components/)即可使用。
- **本地搜索** —— Orama 在开发与生产环境都能工作；站点规模大时，Pagefind 只需换一个适配器（`search: pagefind()`）。不依赖托管索引。
- **AI** —— [`llms.txt`、原始 Markdown URL、带 OpenAPI 描述的 JSON API、Copy as Markdown、Open in chat 和托管的 MCP server](/docs/discoverability/)，外加可选的[页面内 assistant](/docs/configuration/assistant/)。
- **导航** —— 从文件推断，可用 `meta.ts` 或配置微调。
- **SEO** —— 元数据、Open Graph 图片、RSS 订阅源和 JSON-LD，[全部内置](/docs/discoverability/)。
- **定制** —— 组件覆盖、React 交互岛、自定义页面、主题 token，以及通过 `blume add` 安装的源组件注册表。
- **Eject** —— `blume eject` 生成一个独立的 Astro 项目，且仍然使用 `blume` 包。

## 工作原理

Blume CLI 会发现你的内容、构建内容图谱，并在 `.blume/` 下生成一个隐藏的 Astro 项目，由它驱动开发和构建。生成的运行时是一个实现细节 —— 你只写 Markdown，其余交给 Blume —— 直到你选择 eject 并彻底接管它。

## 下一步

**[配置](/docs/configuration/)**

调整标题、主题、搜索和部署。

**[组件](/docs/content/components/)**

探索内置组件库。

**[可发现性](/docs/discoverability/)**

发布 `llms.txt`、社交卡片和一个 MCP server。

**[CLI](/docs/cli/)**

每一条 `blume` 命令和参数。

---

# 迁移到 Blume
Source: https://blume.ndjp.net/docs/migrating/
English: https://useblume.dev/docs/migrating

把一个文档站迁移到地道的 Blume，需要 codemod 无法替代的判断力：哪些已声明的导航应该变成文件夹，哪些组件应该变成指令，以及哪些东西在 Blume 里没有对应物。所以 `blume migrate` 把这件事交给一个编码 agent，它依据 Blume 的迁移手册来完成，你只需逐处审阅它的修改。

## 一条命令完成迁移

在你要迁移的文档项目根目录里运行：

```package-install
npx blume migrate fumadocs --codex
```

把 `fumadocs` 换成你自己的框架，把 `--codex` 换成 `--claude` 即可使用 Claude Code。在 pnpm 12 上，要在 `pnpm dlx` 后面加 `--allow-build=esbuild`，因为 pnpm 12 未经批准不会运行 esbuild 的安装脚本。agent 会在你的终端里交互式打开，因此每一次修改都走它自己的权限流程。它就地工作，所以请从干净的工作区开始，并把整次迁移当作一个 diff 来审阅。

## 迁移来源

写明你要从哪个框架迁移，或者留空、由 Blume 从项目自身的文件里检测。当你写明了某个来源、而项目看起来像另一个时，Blume 会给出警告，并继续使用你写明的那个：

| 来源 | 检测依据 |
| --- | --- |
| `mintlify` | `docs.json` 或 `mint.json` |
| `fumadocs` | `source.config.ts`，或 `package.json` 里的 `fumadocs-core`、`fumadocs-ui`、`fumadocs-mdx` |
| `docusaurus` | `docusaurus.config.*` |
| `starlight` | `package.json` 里的 `@astrojs/starlight` |
| `nextra` | `package.json` 里的 `nextra` |

每个来源在手册里都有各自的映射参考。用别的东西构建的站点同样能迁移：不写来源地运行该命令，agent 会先给整个仓库做一份清单，然后依据手册里的通用规则动手。

## agent 会做什么

agent 会按手册的工作流，从来源的配置一路走到一次通过的构建：

1. 写入 `blume.config.ts`，只映射你来源里声明过的部分，其余交给 Blume 的默认值覆盖。
2. 把内容重组为[文件系统导航](/docs/content/navigation/)，把按文件夹排序的文件（Fumadocs 的 `meta.json`、Nextra 的 `_meta`）转成 `meta.ts`。
3. 重写页面：frontmatter 转成 Blume 的 schema，callout 提示框转成[指令](/docs/content/syntax/)，图标换成 Lucide，代码片段改为内联。
4. 为每一个改动的 URL 添加一个[重定向](/docs/deployment/)，这样不会有任何链接失效。
5. 把 `package.json` 的脚本指向 `blume dev` 和 `blume build`，并用 `blume` 替换掉旧框架的依赖。
6. 反复运行 `blume build` 和 `blume validate`，直到两者都通过。

最后它会给出一份总结，说明哪些内容被迁移了、被丢弃了，或只是做了近似处理 —— 比如页脚链接或导航栏按钮在 Blume 里没有对应物 —— 这样你可以逐项决定怎么处理。

## 其它 agent

不加 `--codex` 或 `--claude` 时，该命令会报告它检测到的来源，打印手册的路径 —— 即随包一起分发的 `blume-migrate` [skill](/docs/advanced/skills/) —— 然后不做任何修改就退出。把那个 `SKILL.md` 指向任意其它 agent，或者用它打印出来的命令把该 skill 安装到你的 agent 查找 skill 的位置：

```bash
npx skills add haydenbleasel/blume --skill blume-migrate
```

## 先做对比

[常见问题](/docs/faq/)里把 Blume 与 Mintlify、Fumadocs 等工具逐项对比，并说明了迁移到 Blume 时每个框架的映射关系。

---

# 快速上手
Source: https://blume.ndjp.net/docs/quickstart/
English: https://useblume.dev/docs/quickstart

用几条命令，从一个空文件夹走到一个跑起来的文档站。Blume 需要 **Node.js 22.12 或更新版本**，以及一个至少包含一个 `.md` 或 `.mdx` 文件的 `docs/` 文件夹 —— 除此之外没有任何需要配置的东西。

## 安装并运行

1. **创建项目**

    `blume init` 会问几个问题 —— 项目建在哪里、你的文档站叫什么、用哪个模板、内容放在哪里 —— 然后生成最小的一套东西：一个内容文件夹、一个配置文件，以及一个带 `dev` 和 `build` 脚本的 `package.json`。它会用运行它的那个包管理器来安装依赖。传 `--yes` 可以跳过交互、直接采用默认值，或传 `--no-install` 只写文件不安装。

    ```package-install
    npx blume init
    ```

    在 pnpm 12 上，要在 `pnpm dlx` 后面加 `--allow-build=esbuild`（`pnpm dlx --allow-build=esbuild blume init`）：pnpm 12 拒绝运行 esbuild 的安装脚本，而 Astro 依赖它。如果在一个已有的 pnpm workspace 内部，新文件夹必须列在 workspace 的 `packages` 下（pnpm 不会安装其他任何东西，所以在列进去之前 `init` 会跳过安装），并且还需要在 workspace 的 `pnpm-workspace.yaml` 里为 esbuild 加上 `allowBuilds: { esbuild: true }`；`init` 会提醒你这两件事。用 Yarn 2 或更新版本时，`init` 会写一个 `.yarnrc.yml`，把 Yarn 切换到 `node_modules` 安装方式，这是 Blume 需要的；在 Yarn 1 上，请运行 `npx blume init`。

    ```txt
    docs/
      index.mdx
    .gitignore
    blume.config.ts
    package.json
    ```

2. **启动开发服务器**

    在项目目录里，Blume 会生成运行时，并以热重载的方式提供你的文档。

    ```package-install
    npm run dev
    ```

3. **构建生产版本**

    静态 HTML 会写入 `dist/`，并在它之上构建一份本地搜索索引。

    ```package-install
    npm run build
    ```

想在已有 `package.json` 的项目里加上 Blume？`blume init` 不会改动已有文件，也会跳过安装，所以请自行安装 Blume（`npm install blume`），然后在 scripts 里加上 `"dev": "blume dev"` 和 `"build": "blume build"`，或者直接运行 `npx blume dev`。`init` 最后打印的后续步骤里，对你的包管理器来说这两条命令都有。

:::tip
Blume 可以配合任意包管理器使用，绝不需要你自己去配置 Astro 或 Tailwind。
:::

## 写你的第一个页面

每个页面都是带一点 frontmatter 的 Markdown 或 MDX —— `title` 和 `description` 会自动渲染成页面标题和引言。把下面这段放进 `docs/index.mdx`：

```mdx docs/index.mdx lineNumbers
---
title: 引言
description: 欢迎来到我的文档。
---

欢迎！使用 **Markdown** 和内置组件 —— 无需任何 import：

:::note
Blume 自带提示框、卡片、标签页、步骤等等。
:::
```

保存后，开发服务器会立刻重载。随着你不断添加文件，导航、搜索和页面元数据都会从中推断出来 —— 继续写，站点就跟得上。

## 下一步

**[配置](/docs/configuration/)**

调整标题、主题、搜索和部署。

**[组件](/docs/content/components/)**

探索内置组件库。

**[可发现性](/docs/discoverability/)**

发布 `llms.txt`、社交卡片和一个 MCP server。

**[部署](/docs/deployment/)**

部署到任意静态托管平台。

---

# API 页面
Source: https://blume.ndjp.net/docs/references/api-pages/
English: https://useblume.dev/docs/references/api-pages

并非每个 API 都有 OpenAPI 规范，有些端点手写反而更清楚。一个带 `api` frontmatter 的页面记录一个端点：它的[字段](/docs/content/components/)描述请求与响应，[OpenAPI 参考](/docs/references/openapi/)页面的其余部分则由 Blume 依据这些字段生成 —— 顶部是 HTTP 方法与路径，内容旁边一列是 Try it 面板和请求示例，以及钉在它们下方的任何[请求与响应示例](/docs/content/components/)。

````mdx docs/users/create.mdx lineNumbers
---
title: Create a user
api: POST /workspaces/{workspaceId}/users
---

Creates a user and sends them an invite.

<ParamField path="workspaceId" type="string" required>
  The workspace to add the user to.
</ParamField>

<ParamField body="email" type="string" required placeholder="ada@example.com">
  The user's email address.
</ParamField>

<ParamField body="role" type="string" default="member">
  One of `owner`, `admin`, or `member`.
</ParamField>

<ResponseField name="id" type="string" required>
  The new user's ID.
</ResponseField>

<ResponseExample>

```json 201
{ "id": "usr_8f2k", "status": "invited" }
```

</ResponseExample>
````

`api` 接一个 HTTP 方法，加上一条路径或一个完整 URL。路径参数写在大括号里 —— `{workspaceId}` —— 并由对应的 `path` 字段填入。完整 URL，例如 `GET https://api.acme.com/v1/users`，会按原样发出；而路径则拼接站点的 [`api.server`](#site-defaults)。

## 演练场与示例 [#playground-and-samples]

页面里的 `ParamField` 会变成 Try it 面板的输入项，就像规范中一个接口的参数那样：`path`、`query` 和 `header` 字段都是参数，`body` 字段拼成 JSON 请求体，而某个字段的嵌套字段（写在它自己的 [`Expandable`](/docs/content/components/) 里）则成为该对象的属性。`type` 为 `string[]` 表示数组；若 `type` 不是 JSON 类型，例如 `enum<string>`，就按字符串发送。字段的 `default` 用来预填请求体，它的 `placeholder` 则是示例里显示的示例值。

面板旁边，页面还会给出 cURL、JavaScript 和 Python 三种请求示例。页面若自带 `RequestExample`，就由它来展示。

还有两个 frontmatter 键用来调整页面：

- `authMethod` 设置该端点的认证方式：`bearer`、`basic`、`key`（放在请求头里的 API key）或 `none`。它会覆盖站点的 [`api.auth`](#site-defaults)。
- `playground` 设置页面显示什么：`interactive`（默认）显示 Try it 面板和示例，`simple` 只显示示例，`none` 两者都不显示。方法、路径以及任何示例都保留。

## 站点默认值 [#site-defaults]

`blume.config.ts` 里的 `api` 设置每个端点页面共享的内容：

```ts blume.config.ts lineNumbers
export default defineConfig({
  api: {
    server: "https://api.acme.com/v1",
    auth: { method: "key", name: "x-api-key" },
    playground: { proxy: true },
  },
});
```

- `server` 是 `api` 路径拼接时用的基础 URL。
- `auth` 是页面未设置 `authMethod` 时请求的认证方式：`method` 为 `bearer`、`basic`、`key` 或 `none`，`name` 是 API key 所在的请求头（默认 `x-api-key`）。没有 `auth` 时，页面不发送任何凭据。
- `playground` 接受与 OpenAPI 参考的 [playground 选项](/docs/references/openapi/) 相同的取值：`false` 在每个页面上隐藏 Try it 面板，`proxy` 则把它的请求经由 CORS 代理发出 —— 可以是你自己的 URL，也可以是 `true` 表示使用 Blume 内置的那个。内置代理需要[服务端输出](/docs/deployment/)，并且只转发到 `server` 的 origin 以及 `api` frontmatter 中任何完整 URL 的 origin。

页面的布局、字段和示例与其它地方用的是同一套组件，因此页面的 [Markdown 副本](/docs/discoverability/llms-txt/) 会列出每个字段，搜索也像对其它页面一样为它建立索引。

frontmatter 的键和组件属性与 Mintlify 一致，因此为它写好的页面无需改动即可继续工作。

---

# AsyncAPI 参考
Source: https://blume.ndjp.net/docs/references/asyncapi/
English: https://useblume.dev/docs/references/asyncapi

事件驱动的 API 使用 `blume/reference` 中的 `asyncapi()` 适配器，它登记在 `reference` 下，与任何 [OpenAPI](/docs/references/openapi/) 或 [GraphQL](/docs/references/graphql/) 适配器并列。它接受与 `openapi()` 相同的选项，并用同一个原生渲染器渲染。每个 `send`/`receive` 操作都会变成一个真实页面，带消息 payload 与 header 的 schema 表、channel 参数、协议绑定、一个依据规范中 `securitySchemes`（服务器级与操作级，可选项渲染成“或”字样的分组）推导出的 Authorization 小节，以及一个 [Try it](#try-it-for-events) 消息编辑器。由于每个操作都是一个真正的 Blume 页面，它有自己的 URL，会出现在**站内搜索**和 `llms.txt` 中，还会得到一张 Open Graph 图片 —— 与手写文档别无二致。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { asyncapi } from "blume/reference";

export default defineConfig({
  reference: [asyncapi({ spec: "./asyncapi.yaml" })],
});
```

它把参考挂在 `/events`（一个概览页）上，每个操作各自占其下方的一个页面。`spec` 要么是一个 `http(s)` URL，要么是你项目中某个本地文件的路径，JSON 或 YAML 均可。与所有参考一样，它不会自己添加页眉标签页 —— 把一个[导航标签页](/docs/content/navigation/)指向它的路由，即可让它露出来，并限定操作侧边栏的范围：

```ts blume.config.ts
navigation: {
  tabs: [{ label: "Events", path: "/events" }],
}
```

## 规范版本 [#spec-versions]

AsyncAPI **2.x 规范会自动规范化到 3.x**，用的是官方 AsyncAPI 转换器，因此 `publish`/`subscribe` 的 channel 会映射到 `send`/`receive` 的操作页面上，URL 保持稳定 —— 之后若再通过该转换器升级规范文件本身，也不会挪动任何东西。这个转换器是一个可选的 peer 依赖，因此规范为 1.x 或 2.x 的站点需要安装它（`npm install @asyncapi/converter`）；不安装的话构建会失败并给出这条安装命令。3.x 规范则无需任何额外东西。操作按 tag 分组；没有 tag 的操作归在其 channel 地址之下。

## 代码示例 [#code-samples]

代码示例是**感知协议**的，依据操作的绑定（或其服务器的协议）来选：WebSocket 用 `wscat` 和一段浏览器 `WebSocket` 代码，Kafka 用 `kcat`，MQTT 用 `mosquitto_pub`/`mosquitto_sub`。`codeSamples` 按与 `openapi()` 上挑选语言相同的方式过滤这个集合，而 `codeSamples: false` 则一个都不显示。若某个协议没有受支持的工具，就只渲染消息 payload 示例，而不会编造一个客户端出来。

## 共用选项 [#shared-options]

[OpenAPI](/docs/references/openapi/) 上记录的一切都照搬过来，[`playground`](#try-it-for-events) 也不例外：[`route`](/docs/references/openapi/)、带 `label`/`route` 的 [`sources`](/docs/references/openapi/)、`expandSchemas`、那些[按来源的索引](/docs/references/openapi/)开关（`seoDescriptionSuffix` 同样可用 —— 自动生成的那句话改为点明 channel 与动作，而不是端点），以及按操作的 summary、description、tag 和 endpoint（`SEND user/signup`）建立的搜索索引。

## 改为嵌入 Scalar [#embedding-scalar-instead]

`asyncapi()` 始终渲染 Blume 自己的页面。若想改为嵌入 [Scalar](https://scalar.com) 的界面，就列出一个指向 AsyncAPI 文档的 [`scalar()`](/docs/references/scalar/) 适配器 —— 它的嵌入页会自动识别文档类型，并渲染 channel、操作、消息和一个 Models 小节。Scalar 自己没有 AsyncAPI 演练场，因此这样一换就把消息编辑器换掉了，而且按来源的控制项里也只有 `noindex` 对它适用。

## 事件的 Try it [#try-it-for-events]

原生渲染的操作页面在这里也带一个 **Try it** 面板，条件与 [OpenAPI 面板](/docs/references/openapi/)完全一致：以折叠状态在服务端渲染，其 JavaScript 只在读者首次打开时才加载。

无论协议为何，面板打开时都是一个 payload 编辑器，内容按消息的 `examples` 预填 —— 若消息没有声明任何 `examples`，则从 payload schema 中采样一个值 —— 并在你输入时按消息 payload schema 校验。它下方是每个 channel 参数一个输入项，以及一个由 channel 的 `servers` 填充的服务器选择器（host 和 path 变量取默认值），另有自由文本字段供填写其它 URL。感知协议的代码示例与表单严格同步，正如 HTTP 操作上的 curl、js 和 python 那样：channel 地址模板会填入你输入的参数值，因此复制出的 `wscat`、`WebSocket`、`kcat` 或 `mosquitto_pub` 代码与表单显示的内容一致。

实时连接只支持 WebSocket。在 `ws` 或 `wss` 绑定上，面板会连到解析出的 channel URL，显示连接状态，并逐帧记录日志、附上时间戳。AsyncAPI 3 从 API 一侧来陈述动作，面板也照此行事：`receive` 操作表示 API 从你这里接收消息，因此它有一个 **Send** 按钮用来发布编排好的 payload；`send` 操作只是向你推送消息，因此它只负责连接和记录。这里没有重连逻辑 —— socket 一旦关闭，就一直关闭，直到你再次连接。Kafka、MQTT、AMQP 以及其它所有协议则得到消息编辑器和可复制的 CLI 示例，面板也会在页面上明说这一点：Blume 不会在浏览器标签页里伪造 broker 连通性。

`asyncapi()` 的 `playground` 与 `openapi()` 的对应 —— 使用原生渲染器时默认开启，而 `false` 就是全部的关闭开关：

```ts blume.config.ts lineNumbers
reference: [asyncapi({ spec: "./asyncapi.yaml", playground: false })],
```

:::note
`playground.proxy` 对事件操作不适用。它转发的是 HTTP 请求，而 WebSocket 连接是从浏览器直连 URL 中指定的那台服务器，中间没有代理可插的位置。
:::

事件编辑器不收集任何 broker 凭据。每个操作页面的 **Authorization** 小节会说明 broker 期望什么，而 WebSocket 连接只携带 URL 里已有的内容。事件操作不会持久化任何东西。

---

# GraphQL 参考
Source: https://blume.ndjp.net/docs/references/graphql/
English: https://useblume.dev/docs/references/graphql

把一个 GraphQL schema 指给 Blume，它就会生成一份原生 API 参考：**每个根字段一个真实页面** —— query、mutation 和 subscription —— 外加**每个具名类型一个页面**（object、input object、enum、interface、union 以及自定义标量）。每个页面都会展示参数、默认值、弃用信息和使用反向链接，并配有一段生成的示例操作、代码示例以及一个交互式 [Try it](#try-it-playground) 面板。由于每个页面都是一个真正的 Blume 页面，它有自己的 URL，会出现在**站内搜索**和 `llms.txt` 中，还会得到一张 Open Graph 图片 —— 与手写文档别无二致。

这份参考是 `blume/reference` 中的 `graphql()` 适配器，登记在 `reference` 下，与任何 [OpenAPI](/docs/references/openapi/) 或 [AsyncAPI](/docs/references/asyncapi/) 适配器并列：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { graphql } from "blume/reference";

export default defineConfig({
  reference: [
    graphql({
      spec: "./schema.graphql",
      endpoint: "https://api.example.com/graphql",
    }),
  ],
});
```

它把参考挂在 `/graphql`（一个概览页）上，根字段位于 `/graphql/queries/<field>`、`/graphql/mutations/<field>` 和 `/graphql/subscriptions/<field>`，类型则按种类分组放在 `/graphql/objects/<type>`、`/graphql/enums/<type>` 等位置。

`spec` 要么是你项目中某个本地文件的路径，要么是一个 `http(s)` URL，并接受两种格式：

- **SDL 文本** —— 一个带类型定义的 `.graphql` 文件。文件用到却未声明的指令，例如 Apollo Federation 的 `@key` 或 AppSync 的 `@aws_*`，会被忽略。
- **内省结果** —— 运行标准内省查询得到的 JSON，可以是原始的 `{ "__schema": … }` 结构，也可以是完整的 `{ "data": { "__schema": … } }` 响应信封。

`endpoint` 是 GraphQL API 的实际访问地址。schema 与 OpenAPI 文档不同，它不指明任何服务器 —— 因此 Try it 面板和生成的代码示例都以这个地址为目标。不写它的话，示例会用一个占位 URL 渲染出来，由读者自行替换。

参考不会自己添加页眉标签页。要让它露出来，把一个[导航标签页](/docs/content/navigation/)指向它的路由 —— 这同时也限定了参考侧边栏的范围：

```ts blume.config.ts
navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}
```

## 生成的示例 [#generated-examples]

每个操作页面都带有一段完整且合法的示例操作 —— 每个参数对应一个变量，类型取自 schema，返回类型上带一层有界深度的选择集 —— 外加与之匹配的示例变量，以及一份镜像同一选择集的示例响应。代码示例会以每种配置的语言展示确切的 HTTP 请求（一个发送 `{ query, variables }` 的 JSON `POST`）。可选的[语言](/docs/references/openapi/)与 `openapi()` 相同，而 `codeSamples: false` 则一个都不显示：

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    spec: "./schema.graphql",
    codeSamples: ["curl", "js"],   // openapi() 提供的任意语言
  }),
],
```

## 类型页面 [#type-pages]

具名类型各自拥有可深链的页面，并在侧边栏中按种类分组：字段与输入字段（类型带链接）、枚举值、union 成员、interface 的实现，以及一个 **Used by** 小节，列出返回或接受该类型的操作，以及引用它的其它类型。规范内置的标量（`String`、`Int`……）不生成页面；自定义标量则会生成，包括它们的 `specifiedBy` URL。

## 多份 schema [#multiple-schemas]

`sources` 中的每个条目都在自己的路由上渲染一份 schema。按来源设置的 `endpoint` 会覆盖适配器的：

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    endpoint: "https://api.example.com/graphql",
    sources: [
      { label: "Public API", spec: "./schema.graphql" },
      {
        label: "Admin API",
        route: "/graphql-admin",
        spec: "./admin.graphql",
        endpoint: "https://admin.example.com/graphql",
      },
    ],
  }),
],
```

`spec` 是单条目 `sources` 的简写。需要不同显示选项的 schema 应放进各自独立的 `graphql()` 适配器，每个配一个 `route`。每个来源接受与 `openapi()` 相同的[按来源控制项](/docs/references/openapi/)：`includeInSearch`、`includeInLlms`、`noindex` 和 `seoDescriptionSuffix`（这里自动生成的那句话会点明具体的 query、mutation 或类型 —— “GraphQL API 中 `pets` query 的参考文档。”）。

## Try it 演练场 [#try-it-playground]

query 和 mutation 页面会渲染一个交互式面板：编辑请求体（query 与变量），把它指向你的 endpoint 或一个自定义 URL，然后发送 —— 代码示例会实时更新，因此你复制到的内容与实际发出的请求逐字节一致。用 `playground: false` 关闭它。subscription 页面则改为展示生成的操作和一个示例事件：subscription 跑在有状态的传输之上（WebSocket 或 SSE），而演练场那唯一一次 HTTP `POST` 说不了这种话。

如果你的 GraphQL API 不允许来自文档站点的跨域请求，发送就会走一个 CORS 代理 —— 可以是你自己的 URL，也可以是 `true` 表示使用内置的 `/_api-proxy` 端点（如果你设了 `basePath`，它就在其之下；它需要[服务端输出](/docs/deployment/)：一个主机适配器，例如来自 `blume/deploy` 的 `deployment: vercel()`）。内置代理只会转发到已文档化规范所声明的 origin —— 每个配置过的 GraphQL `endpoint`，加上已记录的 [OpenAPI 规范](/docs/references/openapi/)里任何绝对的 `servers[].url` —— 因此一个公开的文档部署无法被指向其它主机。这也意味着 `endpoint` 是让代理正常工作的必需项：没有它，代理就没有可为这份参考放行的 origin，会拒绝每一次发送（构建时会就此发出警告）。请求体上限、请求头转发和响应头与 [OpenAPI 代理](/docs/references/openapi/)完全相同。

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
    playground: { proxy: true },
  }),
],
```

GraphQL 没有对应的 Scalar 版本：[`scalar()`](/docs/references/scalar/) 嵌入页只读取 OpenAPI 和 AsyncAPI 文档，因此 GraphQL 参考始终以原生方式渲染。

---

# OpenAPI 参考
Source: https://blume.ndjp.net/docs/references/openapi/
English: https://useblume.dev/docs/references/openapi

把一个 OpenAPI 规范指给 Blume，它就会生成一份原生 API 参考：**每个接口一个真实页面**，按 tag 分组放进受标签页约束的侧边栏，带 schema 表、请求/响应示例、生成的代码示例，以及一个交互式 [Try it](#try-it-playground) 面板。由于每个接口都是一个真正的 Blume 页面，它有自己的 URL，会出现在**站内搜索**和 `llms.txt` 中，还会得到一张 Open Graph 图片 —— 与手写文档别无二致。

每份参考都是从 `blume/reference` 导入并登记在 `reference` 下的一个**适配器**：`openapi()` 对应 OpenAPI 文档，[`asyncapi()`](/docs/references/asyncapi/) 对应 AsyncAPI 文档，[`graphql()`](/docs/references/graphql/) 对应 GraphQL schema。每个适配器掌管自己的规范来源、挂载路由和显示选项，因此这个列表里每种类型想放多少都行。下面的配置以公开的 Petstore 规范为例，把 Blume 指向它。

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { openapi } from "blume/reference";

export default defineConfig({
  reference: [
    openapi({ spec: "https://petstore3.swagger.io/api/v3/openapi.json" }),
  ],
});
```

它把参考挂在 `/reference`（一个概览页）上，每个接口位于 `/reference/<tag>/<operation>`。`spec` 要么是一个 `http(s)` URL，要么是你项目中某个本地文件的路径。Blume 用 [Scalar 的 OpenAPI 解析器](https://github.com/scalar/scalar)解析它 —— Swagger 2.0 和 OpenAPI 3.0 规范会自动升级到 3.1。适配器只是对参考的一份纯描述 —— 不是解析后的规范 —— 因此 Blume 可以预先校验它，并把它内联进生成的站点；完全不写 `reference`（或留空）则不会渲染出任何参考。要记录的是事件驱动 API 或 GraphQL API 吗？请看 [AsyncAPI](/docs/references/asyncapi/) 和 [GraphQL](/docs/references/graphql/)。

参考不会自己添加页眉标签页。要让它露出来，把一个[导航标签页](/docs/content/navigation/)指向它的路由 —— 这同时也限定了原生渲染器下接口侧边栏的范围：

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
接口进入搜索索引的依据是它们的 **summary、description、tag 和 endpoint**（`GET /pets/{id}`）。渲染出的 schema 表和代码示例不参与全文索引；搜索匹配接口的标题、正文、小节和路径，然后链到它自己的页面。
:::

## 本地规范 [#a-local-spec]

相对路径从你的项目根目录解析，并在构建时读取。JSON 和 YAML 都可以：

```ts blume.config.ts lineNumbers
reference: [openapi({ spec: "./openapi.yaml" })],
```

## 路由 [#route]

`route` 控制参考挂载的位置 —— 概览页的位置，以及每条接口路由的前缀（也是你让导航标签页指向的那个路由）：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    route: "/api",   // 概览页在 /api，接口在 /api/<tag>/<operation>
    spec: "./openapi.yaml",
  }),
],
```

## 代码示例与 schema [#code-samples-and-schemas]

`codeSamples` 决定每个接口渲染哪些语言，顺序就按你列出的顺序。它默认为 `["curl", "js", "python"]`。`expandSchemas` 让嵌套的 schema 行默认展开而非折叠：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    spec: "./openapi.yaml",
    codeSamples: ["curl", "python", "go", "java", "csharp"],
    expandSchemas: true,
  }),
],
```

每一段示例都是针对该请求的纯文本、可直接复制粘贴的代码，使用该语言标准或最常见的 HTTP 客户端：

| Id | 语言 | 客户端 | 也接受 |
| - | - | - | - |
| `curl` | cURL | `curl` | `bash`, `sh`, `shell` |
| `python` | Python | `requests` | `py` |
| `js` | JavaScript | `fetch` | `javascript` |
| `node` | Node.js | `axios` | `nodejs`, `node.js` |
| `typescript` | TypeScript | `fetch` | `ts` |
| `php` | PHP | curl 扩展 | |
| `go` | Go | `net/http` | `golang` |
| `java` | Java | `java.net.http` | |
| `ruby` | Ruby | `net/http` | `rb` |
| `powershell` | PowerShell | `Invoke-RestMethod` | `ps1` |
| `swift` | Swift | `URLSession` | |
| `csharp` | C# | `HttpClient` | `c#`, `cs` |
| `dotnet` | .NET | RestSharp | `.net`, `dot-net` |
| `c` | C | libcurl | |
| `cpp` | C++ | cpr | `c++` |
| `kotlin` | Kotlin | OkHttp | `kt` |
| `rust` | Rust | reqwest | `rs` |
| `dart` | Dart | `package:http` | `flutter` |

每个值都由它自己语言的引号规则包裹，因此像 `If-Match: "33a64df5"` 这样的请求头，或含 `$` 的请求体，都会按原样送达 API。

### 你自己的示例 [#your-own-samples]

想展示你的 SDK 而不是原始 HTTP 调用，就在规范里给某个接口加上 `x-codeSamples`。这是 Redocly 定义的扩展，Speakeasy 和 Stainless 都能替你写。每个条目需要一个 `lang`、一份 `source`，以及可选的 `label`：

```yaml openapi.yaml lineNumbers
paths:
  /plants:
    get:
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: |
            const plants = await planter.plants.list();
        - lang: bash
          label: CLI
          source: |
            planter list
```

这些示例会渲染成独立的标签页，排在生成的示例之前；读者改动 [Try it](#try-it-playground) 表单时，它们保持原样不。旧的 `x-code-samples` 写法同样有效。若只想展示自己的示例，设置 `codeSamples: false`。

## Try it 演练场 [#try-it-playground]

原生渲染的接口页面默认带一个交互式 **Try it** 面板。Blume 直接从接口本身生成表单：每个 path、query 和 header 参数一个输入项，一个依据请求体 schema 构建的请求体编辑器，全部内容都按规范里的示例预填。取值上线路径的方式与规范的描述一致：数组和对象参数遵循各自的 `style` 和 `explode`（query 中为 `tags=dog&tags=cat`，path 中为 `1,2`，`deepObject` 为 `filter[color]=red`），而 `application/x-www-form-urlencoded` 或 `multipart/form-data` 的请求体会以表单字段而非 JSON 发送。服务器选择器列出该接口的服务器（优先它自己的 `servers`，其次是它所在 path 的，最后是规范的，每处 `{variable}` 取其 `default`），并留一个自由文本字段供填写其它基础 URL；认证输入项则对应接口[解析出的安全要求](#authorization) —— bearer token、API key 和基本凭据，OAuth2 则是一个粘贴 token 的字段（自带 access token 即可；Blume 不跑那个流程）。

面板与代码示例始终保持同步：填进表单的值会实时更新生成的示例，因此复制出来的 curl 命令总与点下 **Send** 时所发的请求完全一致。它也不会碍事 —— 面板以折叠状态在服务端渲染，其 JavaScript 只在读者首次打开时才加载。从不碰它的读者不会下载其中任何东西。

浏览器唯一发不出的方法是 `TRACE`：`fetch` 会拒绝它，因此 `trace` 接口上的 **Send** 只作提示而不发送，而基于 `fetch` 的 JavaScript 示例也只是一句说明而非代码。cURL 和 Python 的示例都能正常发出。

`playground: false` 就是全部的关闭开关：

```ts blume.config.ts lineNumbers
reference: [openapi({ spec: "./openapi.yaml", playground: false })],
```

### 凭据 [#credentials]

输入到认证框里的凭据只留在内存中，刷新即消失。勾选 **Remember on this device** 会把它们持久化到 `localStorage`，作用域限定在文档站点的 origin —— 它们绝不会被发往被调用 API 之外的任何地方。无论输入了什么，代码示例里始终显示占位符（`YOUR_TOKEN` 之类），除非读者打开 **Include my values in samples**。

### CORS 与代理 [#cors-and-the-proxy]

与 [Scalar 嵌入页](/docs/references/scalar/)一样，请求**直接从浏览器**发往目标 API，因此 API 必须允许来自文档站点的跨域请求（`Access-Control-Allow-Origin`）。做不到这一点时，设置 `playground.proxy`：一个 URL 会让请求经由你自己托管的代理转发，`true` 则启用内置的 `/_api-proxy` 路由（若你设置了 [`basePath`](/docs/deployment/)，则位于 `{basePath}/_api-proxy`）—— 它需要[服务端输出](/docs/deployment/)：一个主机适配器，例如来自 `blume/deploy` 的 `deployment: vercel()`：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    spec: "./openapi.yaml",
    playground: {
      proxy: true,   // 或换成你自己的 URL
    },
  }),
],
```

内置代理只会把请求转发到你的规范在 `servers` 中声明的 origin（可以出现在文档级、path 级或接口级，变量取默认值）—— 跨重定向也一样 —— 因此一个公开的文档部署无法被指向其网络内的其它主机。输入到面板里的 **Custom base URL** 不算已声明的服务器：启用代理后，发往它的请求会被 403 拒绝。它只转发面板自己设置的请求头 —— 填好的凭据与 header 参数，以及请求体的 `Content-Type` —— 因此 cookie、浏览器替文档站点附带的凭据（比如受密码保护的预览上的 HTTP Basic 认证），以及你的主机添加的请求头（`X-Forwarded-For`、`CF-*`、`X-Vercel-*`）都不会到达 API。它读取请求体的上限只有 4 MB（更大的会得到 `413`），并且它转发的每个响应都带上 `Content-Security-Policy: sandbox`、`X-Content-Type-Options: nosniff` 和 `Cross-Origin-Resource-Policy: same-origin` —— 对 HTML 或 SVG 还会额外带 `Content-Disposition: attachment` —— 这样回显输入的 API 错误页就无法在文档 origin 上执行脚本。这个代理和每个读者可调用的服务端路由一样，按读者[限流](/docs/configuration/rate-limiting/)。

## 多份规范 [#multiple-specs]

用 `sources` 让一个适配器发布多份规范。每个来源都有自己的概览路由和接口页面，并共享适配器的显示选项。给每个来源一个 `label`（用于侧边栏并据此推导路由），或者显式设置 `route`：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    sources: [
      { label: "Public API", spec: "./public.json" },   // → /reference/public-api
      { label: "Admin API", route: "/admin", spec: "./admin.json" },
    ],
  }),
],
```

`spec` 是单条目 `sources` 的简写，因此只有在不止一份规范时才需要动 `sources`。当两份规范需要不同的显示选项 —— 比如不同的代码示例集合 —— 改为列出两个 `openapi()` 适配器，各自带自己的 `route`。原生页面旁边若要嵌入 [Scalar](/docs/references/scalar/) 参考，则在列表里另加一个 `scalar()` 适配器。来源按列表顺序解析，两个来源解析到同一路由时，先出现的那个胜出（构建会对被丢弃的那个发出警告）。

### 按来源的索引 [#per-source-indexing]

生成的页面默认参与搜索、`llms.txt` 和爬虫索引。次要或内容重叠的规范可以选择退出其中任意一项，而不必隐藏它的页面或把它从导航里移除：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    sources: [
      { label: "Public API", route: "/api", spec: "./public.json" },
      {
        label: "Platform API",
        route: "/platform",
        spec: "./platform.json",
        includeInSearch: false,
        includeInLlms: false,
        noindex: true,
      },
    ],
  }),
],
```

- `includeInSearch: false` 让该来源的概览页和接口不出现在站内搜索中。
- `includeInLlms: false` 让它们不出现在两个 `llms.txt` 文件中。
- `noindex: true` 添加爬虫 noindex 元数据，并把这些页面从 sitemap 中移除。

每个接口页面的 meta description 是该接口自己的 `description`（或 `summary`），后面跟一句自动生成、指明端点的话 —— “Petstore API 中 `GET /pets` 端点的参考文档。” —— 因此即便规范里的摘要都是简短的单行文字，每个页面仍会带上一段各不相同、正好适合搜索摘要长度的描述。这句话是英文的。如果你的规范正文用的是另一种语言，在该来源上设置 `seoDescriptionSuffix: false` 去掉它，只用手写的正文描述每个页面；既没有 `description` 也没有 `summary` 的接口会回退到它的标题（`GET /pets`），所以不会有页面带着空描述上线：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
  }),
],
```

[`scalar()`](/docs/references/scalar/) 嵌入页只接受其中的 `noindex` —— 它本就在 Blume 的搜索和 `llms.txt` 之外，因此那两个 `include*` 设置在那里无事可做。

## Overlays [#overlays]

当规范由别的工具生成、或归另一个团队所有时，用 [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html) 把你的文档改动留在它之外：一个单独的文件，列出要对规范做的改动，比如更清晰的描述、公开的服务器 URL，或删除内部接口。把 overlays 写在 `spec` 旁边。每一个都是本地路径或 `http(s)` URL，并按顺序生效：

```ts blume.config.ts lineNumbers
reference: [
  openapi({
    spec: "./openapi.json",
    overlays: ["./overlays/public.yaml"],
  }),
],
```

```yaml overlays/public.yaml lineNumbers
overlay: 1.1.0
info:
  title: Public docs
  version: 1.0.0
actions:
  - target: $.paths.*[?@['x-internal'] == true]
    remove: true
  - target: $.info
    update:
      description: The public Acme API.
```

每个 action 的 `target` 都是一个 [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) 表达式。`update` 会合并进它选中的每一个节点：对象按键逐一合并，数组追加新元素，其它值直接替换。`copy` 会从规范中别处合并进一个节点（Overlay 1.1），而 `remove: true` 则删除被选中的目标。Overlay Specification 1.0 和 1.1 都受支持。

Overlays 作用在原样的规范上，也就是 Blume 把它升级到 OpenAPI 3.1 之前，因此 overlay 针对的是你撰写规范时所用的那个版本。一切由规范构建出来的东西都会看到结果：接口页面、侧边栏、搜索、`llms.txt` 和 MCP 服务器。使用 `sources` 时，给每个来源配自己的 `overlays`。一个无法生效的 overlay 会像无法读取的规范一样让这份参考构建失败，因此坏掉的 overlay 无法把它本该隐藏的内容发布出去。

## 认证 [#authorization]

声明了[安全要求](https://spec.openapis.org/oas/v3.1.0#security-requirement-object)的接口会在参数之上渲染一个 **Authorization** 小节，生成的代码示例也会带上占位凭据（`Authorization: Bearer YOUR_TOKEN`、一个 API key 请求头，或一个 query key —— 取决于所用方案）。这里没有可配置项：Blume 从规范中读取 `security`，因此这份参考始终与 API 实际强制的要求一致。

OpenAPI 的语义原样沿用：

- 接口自身的 `security` 覆盖文档根部的默认值；`security: []` 表示它**公开**，不渲染 Authorization 小节。
- 多条要求条目是并列可选的 —— 渲染成“或”字样的分组；同一条目内的每个方案都必须同时满足。第一个可选项用于代码示例。
- 空的 `{}` 条目表示该接口的认证是**可选**的，小节里也会这样写明。
- OAuth2 的 scope 按方案逐项列出；来自 `components.securitySchemes` 的方案 `description` 会就地渲染。

## Webhooks 与 callbacks [#webhooks-and-callbacks]

你 API 发出的请求也会被记录下来。规范顶层 `webhooks` 中的每个 [webhook](https://spec.openapis.org/oas/v3.1.0#oas-webhooks) 都像接口一样拥有自己的页面：归入它的第一个 tag，若没有 tag 则归入一个 **Webhooks** 分组。页面展示 payload 的 schema，以及你的端点应当回传的响应。取代 Try it 面板和代码示例的，是侧栏中的一个示例 payload —— 因为这个请求是你的 API 发出的，而不是它提供的服务。webhook 页面只列出该 webhook 自己声明的 `security`：规范根部的 `security` 保护的是对你 API 的调用，因此不适用于 API 发出的请求。

```yaml openapi.yaml lineNumbers
webhooks:
  newPet:
    post:
      summary: New pet added
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 to acknowledge the event.
```

接口的 [`callbacks`](https://spec.openapis.org/oas/v3.1.0#callback-object) —— 你的 API 向调用方提供的 URL 发回的请求 —— 会渲染在该操作页面的 **Callbacks** 小节里。每一条都展示 URL 表达式（`{$request.body#/callbackUrl}`）、它的方法、它的请求体以及预期的响应。在 `components.callbacks` 下声明并用 `$ref` 引用的 callbacks 行为一致。

Webhook 页面是真正的页面：它们在搜索、`llms.txt` 和 MCP 服务器中都在列，而且它们的 Markdown 会告诉智能体这是一个由 API 发出的请求，智能体因此不会去调用它。

## 改为嵌入 Scalar [#embedding-scalar-instead]

`openapi()` 始终渲染 Blume 自己的页面。若想改为在单一路由上嵌入 [Scalar](https://scalar.com) 那套自带的 API 参考界面 —— 它自己的侧边栏、搜索、主题和请求客户端 —— 就用一个来自 `blume/reference` 的 `scalar()` 适配器替代（或并列于）当前这个。[Scalar](/docs/references/scalar/)页面介绍了这个嵌入页能做什么、不能做什么，以及如何把 Scalar 自己的选项透传进去。

---

# Scalar
Source: https://blume.ndjp.net/docs/references/scalar/
English: https://useblume.dev/docs/references/scalar

[`openapi()`](/docs/references/openapi/)、[`asyncapi()`](/docs/references/asyncapi/) 和 [`graphql()`](/docs/references/graphql/) 给你的是 Blume 自己的渲染器：每个接口一个真实页面，出现在你的侧边栏、搜索和 `llms.txt` 中，并带一个 [Try it 演练场](/docs/references/openapi/)。若你更想嵌入 [Scalar](https://scalar.com) 那套自带的 API 参考界面 —— 它自己的侧边栏、搜索、主题和请求客户端，全都集中在单个路由上 —— 就改为列出一个来自 `blume/reference` 的 `scalar()` 适配器。它接受一份 OpenAPI 或 AsyncAPI 文档，Scalar 会自行识别是哪一种：

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { scalar } from "blume/reference";

export default defineConfig({
  reference: [
    scalar({
      spec: "./openapi.yaml",
      theme: "purple", // 一个 Scalar 主题名
    }),
  ],
});
```

它把嵌入页挂在 `/reference`。`spec` 要么是一个 `http(s)` URL —— 页面会在浏览器中直接加载 —— 要么是一个本地文件路径 —— 在构建时读取并内联，使页面保持自包含。`route` 可以把它挪到别处，`sources` 则发布多份文档，每份各占一个路由 —— 与原生适配器遵循的是同一套 [`label`/`route` 规则](/docs/references/openapi/)：

```ts blume.config.ts lineNumbers
reference: [
  scalar({
    route: "/api",
    sources: [
      { label: "Public API", spec: "./public.json" },   // → /api/public-api
      { label: "Legacy API", route: "/legacy", spec: "./legacy.json", noindex: true },
    ],
  }),
],
```

[Overlays](/docs/references/openapi/) 在这里同样可用：把 `overlays` 写在 `spec` 旁边，或写在每个来源上。嵌入页随后会内联应用了 overlays 的规范，因此带 overlays 的远程规范会在构建时被抓取，而不是由浏览器去取。若某个 overlay 无法生效，构建会发出警告并跳过该页面，而不是在没有它的情况下照样把规范嵌进去。

Scalar 嵌入页与原生页面可以在同一个列表里并存 —— 比如为当前 API 用一个 `openapi()` 适配器，为某个遗留 API 用一个 `scalar()` 适配器 —— 只要它们的路由互不相同。和所有参考一样，这个嵌入页不会自己添加页眉标签页；把一个[导航标签页](/docs/content/navigation/)指向它的路由即可让它露出来。

## 嵌入页不做什么 [#what-the-embed-doesnt-do]

由 Scalar 渲染的参考是一个自包含的页面，占自己的路由。它不会织入 Blume 的侧边栏、搜索或 `llms.txt`，因此原生适配器那些按来源的控制项里，只有 `noindex` 在这里适用（它会添加爬虫 noindex 元数据，并把页面挡在 sitemap 之外）；没有 `codeSamples`、`expandSchemas` 或 `playground` 可设。Scalar 自带请求客户端，它会**直接从浏览器**调用你的**目标 API**（Blume 的 [`playground.proxy`](/docs/references/openapi/) 路由在这里不可用），因此 API 必须允许来自文档站点的跨域请求（`Access-Control-Allow-Origin`）。

嵌入页确实会跟随 Blume 的明暗切换：它挂载时绑定到页面的主题，并随之切换，因此 Scalar 自带的主题开关被隐藏了（传入 `forceDarkModeState` 或 `darkMode` 可把配色模式的控制权交还给 Scalar）。不设 `theme` 时，Blume 会把自己的强调色和圆角叠加到 Scalar 的默认主题上；指定了 `theme` 名称则会整体替换掉它。该适配器把 `@scalar/astro` 声明为运行时依赖，因此只有配置了 `scalar()` 适配器时，生成的项目里才会列出它。

## 透传 Scalar 选项 [#passing-scalar-options]

`theme` 是大多数人第一时间想到的选项，但 Scalar 支持的远不止这些。你传给 `scalar()` 的每个键 —— 超出 `spec`、`overlays`、`sources`、`route` 和 `theme` 的那些 —— 都会原样作为 [Scalar 配置](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)透传给嵌入的参考 —— Blume 不做键名把关，因此 Scalar 接受的任何内容都会流过去（只支持 JSON 值，因为配置会被内联进生成的页面）：

```ts blume.config.ts lineNumbers
reference: [
  scalar({
    spec: "./openapi.yaml",
    localization: { locale: "es" },   // 翻译 Scalar 自己的界面
    agent: { disabled: true },         // 禁用 Scalar Agent
    hideTestRequestButton: true,
    orderSchemaPropertiesBy: "preserve",
  }),
],
```

Blume 自己的 [`i18n`](/docs/content/i18n/) 翻译的是文档界面，而 Scalar 有一套独立的本地化系统 —— 设置 `localization.locale` 就能把嵌入的参考一并翻译。透传的选项优先于 Blume 推导出的配置，因此在这里设置的任何内容（包括 `customCss` 或规范的 `content`/`url`）都会覆盖 Blume 的默认值。唯一无法透传的键是 Scalar 自己的多文档 `sources`：这个名字属于 Blume，而 Blume 的每个来源都会成为独立的页面。

## AsyncAPI 文档 [#asyncapi-documents]

把 `spec` 指向一份 AsyncAPI 文档，嵌入页就会渲染 channel、操作、消息和一个 Models 小节。Scalar 自己没有 AsyncAPI 演练场，因此在 [`asyncapi()`](/docs/references/asyncapi/) 之外选择嵌入页，等于拿 Blume 的[事件编辑器](/docs/references/asyncapi/)去换。GraphQL schema 则根本没有 Scalar 嵌入版 —— [`graphql()`](/docs/references/graphql/) 参考始终以原生方式渲染。

---

# 升级到 Blume 2
Source: https://blume.ndjp.net/docs/upgrading/
English: https://useblume.dev/docs/upgrading

Blume 2 改的是配置，不是内容：你的 Markdown 和 MDX 页面无需任何改动（有一个字段现在才真正生效，见 [Frontmatter](#frontmatter)）。过去是具名字符串或带键值块的那些设置 —— 搜索服务、部署目标、内容源、API 参考、分析，以及 assistant 的模型后端 —— 现在都变成了**适配器**，你从 `blume/*` 子路径导入并调用。Ask AI 更名为 assistant，所以 `ai.ask` 变成 `ai.assistant`。面向机器的设置从 `ai` 移到新的 `agents` 键，而 `components.ts` 的覆盖会在构建前就被校验。一个零配置的站点，或者一个没有设置以上任何一项的站点，只需要升一下版本号。

## 一条命令完成升级

在你的项目里，也就是放着 `blume.config.ts` 的那个文件夹中运行升级命令：

```package-install
npx blume@latest upgrade
```

它会把 `package.json` 里的 `blume` 升到 2，用项目所用的包管理器安装，然后拿你的配置和 `components.ts` 对照 Blume 2 做检查。每一处仍需改动的内容都会连同所在文件、行号和替换方案一起列出 —— 包括 `package.json` 里仍在传递已被移除的 `blume build` 参数的脚本 —— 并且在还剩下改动时，命令会以非零状态退出。如果在既没有配置也没有 `blume` 依赖的文件夹里运行，它会直接报错停止。请通过 `npx blume@latest` 而不是 `blume` 来运行：这个命令随 Blume 2 一起提供，所以仍停在 1 的项目里还没有它。在 pnpm 12 上，要在 `pnpm dlx` 后面加 `--allow-build=esbuild`，因为 pnpm 12 未经批准不会运行 esbuild 的安装脚本。

如果想把这些改动交给编码 agent 处理，加上 `--codex` 或 `--claude`：

```package-install
npx blume@latest upgrade --codex
```

agent 会带着检查结果和本指南交互式打开，逐项应用改动，并反复运行 `blume doctor` 和 `blume build` 直到两者都通过，因此每一次修改都要经过它自己的权限流程来审阅。传 `--no-install` 可以只升级 `package.json` 而不安装。

下面各节会覆盖每一处改动，无论你是想手动升级，还是想核对 agent 做了什么。

## 搜索

`search` 现在接受来自 `blume/search` 的适配器，而不是一个带凭证块的 `provider` 字符串。默认的本地搜索无需改动。

```ts title="Blume 1"
export default defineConfig({
  search: {
    provider: "algolia",
    algolia: { appId: "APP_ID", indexName: "docs", searchApiKey: "SEARCH_KEY" },
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { algolia } from "blume/search";

export default defineConfig({
  search: algolia({ appId: "APP_ID", indexName: "docs", apiKey: "SEARCH_KEY" }),
});
```

- Orama Cloud、Typesense 和 Mixedbread 以同样方式映射为 `oramaCloud()`、`typesense()` 和 `mixedbread()`。在每一个接受搜索密钥的适配器里，它都叫 `apiKey`；`mixedbread()` 接受的是 `storeId` 而不是密钥，因为它的查询运行在文档服务器上；给它的其它任何选项都会透传给 store 的搜索调用，其中 `top_k` 默认为 8。管理密钥仍放在各自的环境变量里（`ALGOLIA_ADMIN_API_KEY`、`ORAMA_PRIVATE_API_KEY`、`TYPESENSE_ADMIN_API_KEY`、`MIXEDBREAD_API_KEY`）。
- `provider: "pagefind"` 变成 `pagefind()`，`provider: "none"` 变成 `search: false`。
- 想保留 `popular` 链接或 `indexing` 选项，就用对象包一层适配器：`search: { provider: algolia({ … }), popular: […] }`。

## 部署

`deployment` 现在接受来自 `blume/deploy` 的托管适配器，而不是 `adapter` 和 `output` 字段。`site` 和 `base` 移进适配器的选项里。

```ts title="Blume 1"
export default defineConfig({
  deployment: {
    adapter: "vercel",
    output: "server",
    site: "https://docs.example.com",
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { vercel } from "blume/deploy";

export default defineConfig({
  deployment: vercel({ site: "https://docs.example.com" }),
});
```

- `netlify()`、`cloudflare()` 和 `node()` 的用法完全一样。指定一个托管适配器会切换到服务端输出；传 `output: "static"` 则可以在该托管平台上保持静态构建并保留它的平台文件。
- 只设置了 `site` 或 `base` 的配置保持原样：`deployment: { site, base }` 依然是静态形式。
- `redirects` 中的 `:name` 路径段和结尾的 `*` 现在会按模式读取，并且在每个托管平台上匹配方式一致（见[模式重定向](/docs/deployment/)）。Blume 1 从不支持模式，只是把它们按书写的样子交给各个托管平台，所以请检查所有含有模式的 `from` 和 `to`。
- `blume build` 上的 `--adapter`、`--output` 和 `--base` 参数已被移除，传入其中任何一个都会让构建报错停止，并指明取而代之的 `deployment` 设置。请在 `blume.config.ts` 里设置适配器，并且要显式写明：服务端输出不再从平台环境中推断。

每个适配器的选项见[部署](/docs/deployment/)。

## 内容源

`content.sources` 的每一项现在都是来自 `blume/sources` 的适配器，而不是 `{ type }` 对象。

```ts title="Blume 1"
export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        owner: "acme",
        repo: "sdk",
        prefix: "changelog",
      },
    ],
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { filesystem, githubReleases } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "content" }),
      githubReleases({ owner: "acme", repo: "sdk", prefix: "changelog" }),
    ],
  },
});
```

- `mdx-remote`、`sanity`、`notion` 和 `obsidian` 变成 `mdxRemote()`、`sanity()`、`notion()` 和 `obsidian()`，其余字段原封不动地移进调用里。`{ type: "custom", source }` 变成 `custom(source)`。
- `content.root`、`content.include` 和 `content.exclude` 仍是单个文件夹的简写，但它们不能再与 `sources` 并列。请把它们移进 `filesystem()` 那一项里。
- 来自 `githubReleases()` 的发布页现在只发布一种语言，因此多语言站点不再把它们复制到其它每个 locale 的 URL（`/de/changelog/…`）上。如果其它站点链接到那些副本，请为默认 locale 的页面添加[重定向](/docs/deployment/)。

## API 参考

顶层的 `openapi`、`asyncapi` 和 `graphql` 块变成一个 `reference` 列表，里面是来自 `blume/reference` 的适配器。`enabled` 取消。

```ts title="Blume 1"
export default defineConfig({
  openapi: { enabled: true, spec: "./openapi.yaml" },
  graphql: {
    enabled: true,
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { graphql, openapi } from "blume/reference";

export default defineConfig({
  reference: [
    openapi({ spec: "./openapi.yaml" }),
    graphql({
      spec: "./schema.graphql",
      endpoint: "https://api.example.com/graphql",
    }),
  ],
});
```

- `asyncapi: { … }` 变成选项相同的 `asyncapi({ … })`。
- AsyncAPI 1.x 或 2.x 规范仍然会为你转换成 3.0，但转换器现在是一个可选的 peer 依赖：在项目里安装 `@asyncapi/converter`，否则构建会带着安装命令失败。3.x 规范什么都不需要。
- `renderer: "scalar"` 变成列表中独立的一项 `scalar({ spec, theme, … })`，并保留该块原有的 `route` 和 `sources`。
- 带 `enabled: false` 的块直接从列表里去掉。

## 分析

`analytics` 对象变成来自 `blume/analytics` 的适配器列表。

```ts title="Blume 1"
export default defineConfig({
  analytics: {
    posthog: { key: "phc_…" },
    vercel: true,
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { posthog, vercel } from "blume/analytics";

export default defineConfig({
  analytics: [posthog({ key: "phc_…" }), vercel()],
});
```

`cloudflare: { token }` 变成 `cloudflare({ token })`，每个 `scripts[]` 条目变成 `script({ … })`。

## Assistant

Ask AI 现在叫 assistant，它的配置也跟着改名：`ai.ask` 变成 `ai.assistant`。它的 `provider` 接受来自 `blume/ai` 的适配器，由它掌管模型以及此前与模型同属一处的那些字段。

```ts title="Blume 1"
export default defineConfig({
  ai: {
    ask: {
      enabled: true,
      provider: "openrouter",
      model: "anthropic/claude-sonnet-4-5",
      reasoning: "none",
    },
  },
});
```

```ts title="Blume 2"
import { defineConfig } from "blume";
import { openrouter } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: openrouter({
        model: "anthropic/claude-sonnet-4-5",
        reasoning: "none",
      }),
    },
  },
});
```

1.x 的 `provider` 名称会映射到 `gateway()`、`openrouter()`、`llmgateway()` 或 `inkeep()`，`openai-compatible` 则映射到 `openai({ baseUrl, name, model, apiKeyEnv })`；其余的在[适配器列表](/docs/configuration/assistant/)里。`model`、`apiKeyEnv`、`baseUrl`、`headers` 和 `reasoning` 移进适配器；`enabled`、`instructions`、`retrieval`、`suggestions`、`cors` 和 `endpoint` 原封不动地移到 `ai.assistant`。不设置 `provider` 仍然会使用 AI Gateway。

这次改名会波及每一个曾叫 Ask AI 的名称：

- `i18n.ui` 覆盖：`ask` 分组变成 `assistant`，`search.askAi` 和 `search.askAiHint` 变成 `search.assistant` 和 `search.assistantHint`。
- `blume/hooks` 中的 `useAskAI` 变成 `useAssistant`，相应的 `UseAssistant` 和 `UseAssistantOptions` 类型也一样。
- `PageLayout`、`RootLayout`、`Header` 以及 `Search` 覆盖上的 `askEnabled` prop 变成 `assistantEnabled`。
- 在 [`blume:data`](/docs/advanced/custom-pages/) 模块中，`config.ask` 变成 `config.assistant`，`ui.ask` 变成 `ui.assistant`，来自 `blume` 的 `UIStrings` 类型也随之更名。
- 来自 `blume/ai` 的适配器类型把 `Ask` 前缀换成 `Assistant`（`AskAdapter` 变成 `AssistantAdapter`，`AskGatewayOptions` 变成 `AssistantGatewayOptions`），来自 `blume/schema` 的 `askReasoningLevels` 和 `AskReasoning` 变成 `assistantReasoningLevels` 和 `AssistantReasoning`。
- `blume:open-ask-ai` 窗口事件变成 `blume:open-assistant`，`<body>` 上的 `data-blume-ask` 属性变成 `data-blume-assistant`。

生成的 `/api/ask` 路由以及 `ask`、`ask_answer`、`ask_error` 这些[分析事件](/docs/configuration/assistant/)都保持原名，所以调用方和仪表盘无需改动。`blume upgrade` 和 `blume doctor` 会指出它们发现的每一个旧配置键 —— 包括 `ai.ask` 和那些 `i18n.ui` 键 —— 以及各自的替代方案。

已经升到 Blume 2.0.0 了？它当时仍然读 `ai.ask`，所以照常更新 `blume` 并做同样的改名即可。

## agents 与其它配置迁移

面向机器的设置从 `ai` 移到新的 `agents` 键，另有三个小字段改变了形态。

```ts title="Blume 1"
export default defineConfig({
  ai: { mcp: { enabled: true }, skills: "./skills" },
  lastModified: true,
  markdown: {
    codeBlocks: { theme: { light: "github-light", dark: "github-dark" } },
  },
  theme: { layout: "sidebar" },
});
```

```ts title="Blume 2"
export default defineConfig({
  agents: { mcp: { enabled: true }, skills: "./skills" },
  lastModified: "git",
  markdown: {
    code: { theme: { light: "github-light", dark: "github-dark" } },
  },
});
```

- `ai.api`、`ai.catalog`、`ai.llmsTxt`、`ai.markdownComponents`、`ai.mcp`、`ai.skills`、`ai.webBotAuth` 和 `ai.webmcp` 变成 `agents.*`，`seo.agentReadability` 和 `seo.contentSignals` 也一样。`ai` 只保留 `assistant`（原 `ask`）和 `openInChat`。
- `lastModified` 现在是一个扁平值：`true` 变成 `"git"`，而 `{ type: "git" }` 或 `{ type: "frontmatter" }` 变成裸字符串。
- `markdown.codeBlocks` 合并进 `markdown.code`。
- `theme.layout` 已被移除。没有任何东西读它，所以直接删掉。

## Frontmatter [#frontmatter]

页面保留它们的 frontmatter。有一个字段改变了它的作用：`search.boost`。Blume 1 接受这个字段，但搜索从未读取过它，所以有没有它页面的排序都一样。现在它会成倍放大该页面的搜索相关性（见[排序](/docs/configuration/search/)）。请检查所有设置了它的页面：你当初加上之后忘了的某个 boost，现在会把该页面排上去。

## 组件覆盖

Blume 2 会在构建前校验每一项 `components.ts` 条目，而不再在运行时回退。每个 `mdx` 和 `layout` 条目必须是一个导入的组件、一个路径字符串，或一个 `{ component, client, media }` 对象；`islands` 分组已被移除：带 `client` 模式的 `mdx` 条目就是交互岛。

```ts title="Blume 1"
import { defineComponents } from "blume";
import Counter from "./islands/Counter.tsx";

export default defineComponents({
  islands: { Counter },
});
```

```ts title="Blume 2"
import { defineComponents } from "blume";
import Counter from "./islands/Counter.tsx";

export default defineComponents({
  mdx: { Counter: { component: Counter, client: "visible" } },
});
```

内联函数、在 `components.ts` 自身里声明的组件、展开运算符或计算得出的键，现在都会以 `BLUME_COMPONENTS_INVALID` 失败，并指明是哪一个条目。请把该组件移进独立文件再导入。`islands/` 文件夹约定照旧可用。可接受的形式见[定制](/docs/configuration/customization/)。

## 已 eject 的应用

在 Blume 1 上[已 eject](/docs/configuration/customization/) 出来的应用不再通过 Blume CLI 运行，但它依然依赖 `blume` 包。它的页面导入 Blume 的组件，`src/generated/` 保存着由 Blume 1 生成器写入的站点快照，而 `astro build` 会再次加载 `blume.config.ts` 来写搜索索引、`llms.txt` 和 sitemap。在它下面把 `blume` 升到 2，会把那份 Blume 1 快照与期待新形态的 Blume 2 组件配到一起，所以请重新 eject 一次：

1. **把项目复制出来**

    把除 `astro.config.mjs`、`src/`、`.blume/`、`dist/` 和
    `node_modules/` 之外的一切复制到一个空文件夹：你的内容、
    `blume.config.ts`、`components.ts`、`islands/`、`public/`、你的
    reference 会读取的任何规范文件，以及 `package.json`。
    把已 eject 的应用原样留在那里。

2. **升级这份副本**

    在副本里运行 `npx blume@latest upgrade` 并应用它列出的改动，让
    `blume.config.ts` 和 `components.ts` 成为合法的 Blume 2。然后运行
    `npx blume build`，在 eject 之前确认站点能够构建。

3. **eject 一份全新的副本**

    在副本里运行 `npx blume eject --yes`，安装它新增的包，然后用
    `npm run build` 构建。

4. **把你的修改搬过去**

    把全新的 `astro.config.mjs` 和 `src/` 与你已 eject 的应用做 diff，
    再把你自己的改动移到新文件上。

在新副本准备好之前，请让已 eject 的应用继续留在 Blume 1 上（`"blume": "^1"`），并且不要在里面运行 `blume upgrade`：不升级版本号就什么都不会变。

## 命令行参数

现在每一条 `blume` 命令都会拒绝它不接受的参数，而在 Blume 1 里这些参数会被忽略。传了一个多余或拼错的参数的脚本或 CI 步骤会失败，并报出它不认识的参数以及该命令接受的那几个。`blume upgrade` 只会报告被移除的那三个 `blume build` 参数（`--adapter`、`--output`、`--base`），所以你其它那些 `blume` 脚本也要一并检查。

## 检查你的成果

一旦 `blume upgrade` 报告没有剩余改动，就运行站点自己的检查：

```bash
npx blume doctor
npx blume build
```

每一处改动的完整列表，以及它们背后的理由，都写在[更新日志](/docs/advanced/changelog/)里。