blume

Blume

Blume 是一个基于 Astro 和 Vite 构建的开源、Markdown 优先文档框架。将 Markdown 或 MDX 文件放入文件夹，运行 blume dev，即可获得一个可用于生产环境的文档站点，内置导航、搜索、主题、Open Graph 图片和丰富的组件库，无需编写或维护任何应用样板代码。

核心理念：**框架_本身就是_模板。**无需克隆起始项目，也无需在写下第一个字之前就先拥有一个项目。你只需处理内容。等默认配置无法满足需求时，再逐个文件添加配置；当你想要完全掌控时，可以运行 blume eject，将项目迁移为普通 Astro 项目。

与众不同之处

• 默认快速 — 基于 Astro/Vite 生成静态 HTML。核心主题不附带客户端框架 JS，因此页面开箱即能获得良好的 Core Web Vitals 分数。只在需要时才启用服务器功能。
• 开箱即支持 AI — 生成 llms.txt/llms-full.txt；在页面 URL 后追加 .md 即可获取任意页面的原始 Markdown；提供由 /openapi.json 中的 OpenAPI 文档描述的 JSON 文档 API（/api/docs/…）；每个页面都提供复制为 Markdown和在聊天中打开功能；还可托管可选的页面内助手或 MCP 服务，让编码 Agent 直接读取文档。
• 零配置——连模板也不例外 — 一个文档文件夹就是一个完整项目。导航根据文件自动推断；搜索在开发和生产环境中均可使用，无需托管服务；主题配置只需少量设计令牌。
• 核心全程类型安全 — blume.config.ts 和每个 meta.ts 都是真正的 TypeScript 文件，由 schema 验证，并通过 defineConfig 和 defineMeta 编写。编辑器会自动补全选项，并在构建前发现错误。

快速开始

Blume 需要 Node.js 22.19 或更高版本。在一个空文件夹中运行：

npx blume init   # scaffold docs/index.mdx, blume.config.ts, and package.json scripts, then install
npm run dev      # dev server with hot reload
npm run build    # static HTML to dist/, with a local search index

在已有 package.json 的项目中，blume init 不会修改该文件：在其 scripts 中添加 "dev": "blume dev" 和 "build": "blume build"，或运行 npx blume dev。Blume 兼容任何包管理器，无需自行配置 Astro 或 Tailwind。

编写页面

每个页面都是带少量 frontmatter 的 Markdown 或 MDX。title 和 description 会自动显示为页面标题和简介；内置组件（提示框、卡片、标签页、步骤等）无需导入。

---
title: Introduction
description: Welcome to my docs.
---

Welcome! Use **Markdown** and built-in components — no imports required:

:::note
Blume ships callouts, cards, tabs, steps, and more.
:::

添加文件后，导航、搜索和页面元数据都会根据文件自动推断。

从 Blume 1 升级

Blume 2 改变的是配置，而非内容：搜索、部署、内容源、API 参考、分析功能和助手的模型后端都变为从 blume/* 子路径导入的适配器（例如，从 blume/search 导入 search: algolia({ … })）；Ask AI 更名为助手（ai.ask 变为 ai.assistant）；机器可读设置从 ai 移至 agents；components.ts 中的条目必须是静态的。在包含 blume.config.ts 的文件夹中运行：

npx blume@latest upgrade

该命令会更新 package.json 中的 blume 版本、安装依赖，并列出仍需进行的所有配置变更及对应的文件、行号和替换内容（还会列出传入已移除 blume build 标志的 package.json 脚本，以及 frontmatter 设置了已移除字段的页面），并在仍有待处理项时以非零状态码退出——每完成一轮修复后都要重新运行。（在终端中使用 --codex 或 --claude 可将该列表交给 Agent CLI。）如果你是负责升级的 Agent，请根据该列表和升级指南进行操作。升级指南位于已安装软件包中的 docs/03-upgrading.mdx，为每项变更都提供了变更前后的示例。保持站点行为不变，并使用 blume doctor 和 blume build 验证。

从其他框架迁移

要将 Mintlify、Docusaurus、GitBook、MkDocs、ReadMe 或其他文档站点迁移到 Blume，用户需要在该项目中运行 npx blume migrate [source] --codex（或 --claude），这会在 blume-migrate 技能上启动一个 Agent。如果你就是该 Agent，或者用户要求你直接执行迁移，请按照已安装软件包中的 skills/blume-migrate/SKILL.md 操作，而不要参考本文档。

每次构建都会在 /skill.md 发布该站点生成的 Agent 技能（agents.skillMd）。要根据文档编写更完善的技能，用户需要运行 blume skill --codex（或 --claude），这会在 blume-write-skill 技能上启动一个 Agent。如果你就是该 Agent，或者用户要求你直接编写该站点的技能，请按照已安装软件包中的 skills/blume-write-skill/SKILL.md 操作。

包含的功能

• 组件 — 提示框、卡片、步骤、标签页、折叠面板、徽章、文件树和参数表，可在 MDX 中直接使用，无需导入。
• 本地搜索 — 在开发和生产环境中使用 Orama，无需托管索引；Pagefind、Algolia 和其他后端只需添加一个适配器即可接入（search: pagefind() 来自 blume/search）。
• AI — llms.txt、原始 Markdown URL、带有 OpenAPI 描述的 JSON 文档 API、“复制为 Markdown”、“在聊天中打开”、页面内助手，以及由文档站点自身提供服务的 MCP 服务端点。
• 旁白 — “朗读此页面”播放器（浏览器语音设为 narration: true，或使用来自 blume/ai 的 narration: { provider: gateway({ … }) }，采用构建时生成的语音；openai({ model, voice }) 则使用 OpenAI 的语音模型，也可通过 baseUrl 使用可自托管的 OpenAI 兼容语音服务端；此功能需要安装 @ai-sdk/openai）。
• 导航 — 根据文件推断，并通过 meta.ts 或配置进行调整。
• SEO — 元数据、Open Graph 图片、RSS 订阅源和 JSON-LD。
• 自定义 — 组件覆盖、React 岛、自定义页面、主题令牌，以及通过 blume add 使用的源组件注册表。
• 脱离框架 — blume eject 会生成一个独立的 Astro 项目，但仍会使用 blume 软件包。

工作原理

Blume CLI 会发现你的内容、构建内容图谱，并在 .blume/ 下生成一个隐藏的 Astro 项目，用于开发和构建。生成的运行时属于实现细节——你只需编写 Markdown，其余工作由 Blume 处理——直到你选择脱离框架并自行管理项目。

完整文档

本文仅作概述。如需完整、权威的文档——涵盖配置参考、所有 CLI 命令和标志、组件 API、内容编写、导航、搜索、SEO、AI 功能、主题和部署——请阅读已安装的 blume 软件包中附带的 docs/ 目录。

请先找到软件包的位置——它不一定在仓库根目录。 在工作区单仓库（尤其是 pnpm）中，blume 安装在依赖它的工作区的 node_modules 中（例如 apps/docs/node_modules/blume/docs），而不是根目录。从依赖 blume 的软件包目录运行以下命令，即可输出确切位置：

node -e "console.log(require.resolve('blume/package.json'))"

文档位于该 package.json 旁边的 docs/ 目录中。请从 docs/index.mdx（简介）和 docs/01-quickstart.mdx 开始，然后查看 docs/ 目录：每个章节都是一个文件夹，分别介绍配置、内容编写、API 参考、可发现性（SEO 和面向 Agent 的界面）、CLI 及高级主题。请打开与当前任务相关的章节。