5分钟搭建生产级文档网站：Blume从init到build的新手快速入门教程-育师

【免费下载链接】blume

The open-source docs framework for humans and agents.

项目地址：https://gitcode.com/gh_mirrors/blum/blume

Blume是一个开源文档框架（docs framework），专为人类和 AI Agent 设计：把 Markdown/MDX 文件丢进文件夹，一条blume init命令即可从零搭建文档网站，blume build生成带本地搜索的静态站点，无需任何模板或样板代码。本教程带你完成 Blume 新手入门：安装、初始化、写第一页、本地预览到生产构建，全程约 5 分钟。

为什么选择 Blume 文档框架？

特性	说明
🚀 零配置	一个 docs 文件夹就是一个完整项目，无需克隆 starter
⚡ 性能优秀	基于 Astro + Vite 输出静态 HTML，默认不加载客户端框架 JS
🔍 本地搜索	Orama 开箱即用，Pagefind、Algolia 等一个适配器切换
🤖 AI 就绪	内置`llms.txt`、JSON 文档 API、页内 AI 助手、MCP 服务器
🎨 组件库	卡片、步骤、选项卡、手风琴等组件无需 import，MDX 直接用
🌍 国际化/SEO	多语言路由、OG 图片、sitemap、robots.txt 全部内置

核心原理很简单：Blume CLI 扫描你的内容，在隐藏的.blume/目录下生成并驱动一个 Astro 项目——你只需要写文档，剩下的交给框架（架构细节见 How it works）。

⚠️ 环境要求：Node.js 22.19 或更高版本，以及一个包含至少一个.md/.mdx文件的内容文件夹。这是全部前置条件。

一键安装：用 blume init 初始化项目

打开终端，运行下面这条命令即可（npx会自动拉取最新版，npm / pnpm / yarn / Bun 均支持）：

npx blume init

blume init会交互式询问 4 个问题：

项目创建位置—— 目标目录
文档站名称—— 显示在页头和搜索结果中
模板选择
内容目录位置—— 通常是docs/

回答完，它会自动生成最小项目骨架并安装依赖：

docs/ index.mdx # 你的第一个文档页面 .gitignore # 忽略 node_modules/、.blume/、dist/ blume.config.ts # 类型安全的配置文件 package.json # 含 dev / build / doctor 脚本

💡 提示：加--yes可跳过所有提问直接取默认值，加--no-install则只写文件不装依赖。完整说明见 Quickstart 官方文档。

编写第一页：Markdown 即页面

每个页面就是带 frontmatter 的 Markdown 文件，title和description会自动渲染为页面标题和简介。把下面内容写入docs/index.mdx：

--- title: Introduction description: Welcome to my docs. --- Welcome! 使用 **Markdown** 和内置组件 —— 无需任何 import： :::note Blume 内置 callout、卡片、选项卡、步骤等组件。 :::

保存后开发服务器会即时热更新——导航、搜索、页面元数据都会随你新增文件自动推断，你只管写，网站自动跟上。

想调整站点标题、主题色、搜索等选项，只需编辑 blume.config.ts 配置文件——它是真正的 TypeScript，用defineConfig包裹即可获得编辑器自动补全和类型检查，所有字段都有合理默认值（全部选项参考配置文档）。

本地预览：启动 dev 开发服务器

进入项目目录，启动带热重载的开发服务器：

npm run dev

浏览器打开终端提示的地址，一个带导航、搜索、暗色模式的文档站已经跑起来了。改任何.mdx文件，页面毫秒级刷新。

生产构建：一条命令生成静态站点

npm run build

构建完成后，纯静态 HTML、CSS 输出到dist/目录，内容物包括：

✅ 所有文档页的静态 HTML
✅ 本地搜索索引（默认 Orama）
✅sitemap.xml与robots.txt
✅llms.txt/llms-full.txt（供 AI 工具消费）
✅ 预渲染的 Open Graph 社交卡片

部署到任意静态托管：构建命令blume build、输出目录dist、Node 22.19+——这三个参数直接填入 Vercel、Netlify、Cloudflare Pages 或 GitHub Pages 的设置即可上线，无需运行任何服务器（部署指南见 02-deployment.mdx）。

进阶解锁：让 AI Agent 读懂你的文档

Blume 的名字含义正在于此——为人类和 Agent 服务的文档框架。构建产物天生对 AI 友好：

📄 任意.mdURL 可返回原始 Markdown
🔌 托管MCP 服务器，编码 Agent 可直接搜索、阅读你的文档
💬 可选的页内 AI 助手，基于文档内容回答用户提问

Blume 还内置 Agent Skills，教编码 Agent 帮你搭建、编写和维护文档站——甚至提供blume audit（SEO 体检）、blume eval（Agent 只凭文档答题测试文档质量）等命令，见 CLI 命令列表。

常见问题 FAQ

Q1：一定要 Node 22.19 吗？是的，最低要求 Node.js 22.19+；Bun、pnpm、npm、yarn 任意包管理器均可。

Q2：已有项目的 package.json 会被覆盖吗？不会。blume init对已有文件只增不改，你只需npm install blume后把"dev": "blume dev"和"build": "blume build"加进 scripts，或直接运行npx blume dev。

Q3：以后想要完全控制权怎么办？运行npx blume eject，Blume 会把隐藏运行时"弹出"成一个独立的 Astro 项目（仍使用 blume 包），源码位于 packages/blume/src。

总结

回到最初的时间账：blume init（约 1 分钟安装）→ 写一页 MDX（1 分钟）→npm run dev预览 →npm run build产出dist/→ 推送到任意静态托管。一个带搜索、SEO、AI 能力的生产级文档网站就此上线。接下来推荐的学习路径：配置参考、组件库、发现性指南（llms.txt 与 MCP）。