haydenbleasel/blume

# Blume [](https://www.npmjs.com/package/blume) [](https://www.npmjs.com/package/blume) [](./LICENSE) [](https://nodejs.org) **为你构建的一切提供文档。** 快速、适配 AI 且零配置。永久免费且开源。 将 Markdown 或 MDX 放入文件夹，运行 `blume dev`，即可获得一个生产级文档站点 —— 包含导航、搜索、主题、Open Graph 图像以及丰富的组件库 —— 无需编写或维护任何应用样板代码。Blume 会为你生成并驱动一个隐藏的 Astro 项目；当你想要完全控制时，随时运行 `blume eject` 即可获取独立的 Astro 应用。 **[文档](https://useblume.dev)** · [快速开始](https://useblume.dev/docs/quickstart) · [组件](https://useblume.dev/docs/content/components) · [CLI](https://useblume.dev/docs/reference/cli) ## 快速开始 Blume 需要 **Node.js 22.12 或更高版本**，以及一个包含至少一个 `.md`/`.mdx` 文件的内容文件夹 —— 无需其他设置。 ``` npx blume init ``` 运行带有热重载的开发服务器： ``` blume dev ``` 将带有本地搜索索引的静态 HTML 构建到 `dist/`： ``` blume build ``` Blume 兼容任何包管理器，且绝不要求你自行配置 Astro 或 Tailwind。 ## 功能 - **零配置，包括模板** —— 一个装满文档的文件夹就是一个完整的项目。无需克隆启动模板，无需学习新框架。配置是按需开启的，一次一个文件。 - **默认即快** —— 基于 Astro 和 Vite 的静态 HTML；核心主题不附带任何客户端框架 JS，因此页面在 Core Web Vitals 上的得分开箱即高。 - **类型安全的配置** —— `blume.config.ts` 和每个 `meta.ts` 都是真正的 TypeScript，通过 schema 验证，并使用 `defineConfig` / `defineMeta` 编写，因此你的编辑器能在构建前发现错误。 - **组件，无需导入** —— 卡片、分栏、步骤、选项卡、手风琴、徽章、代码组、边框、文件树、类型表格、实时代码预览、diff 等，可在任何 MDX 页面中使用。 - **本地搜索** —— Orama 在开发和生产环境中运行，无需托管服务；FlexSearch、Pagefind、Algolia、Typesense、Orama Cloud 和 Mixedbread 只需一个设置即可切换。 - **适配 AI** —— `llms.txt` / `llms-full.txt`、任何 `.md` URL 下的原始 Markdown、复制为 Markdown、在聊天中打开、可选的 Ask AI 助手，以及托管的 MCP 服务器，让编码代理能直接搜索和阅读你的文档。 - **代理技能** —— Blume 内置了 [代理技能](https://useblume.dev/docs/advanced/skills)，可教导编码代理如何搭建、编写和维护你的文档站点。 - **内容源** —— 将本地文件与远程 MDX、GitHub Releases、Notion、Sanity 或任何自定义后端混合到同一个站点中。 - **国际化** —— 将翻译文件放入指定位置，即可实现感知区域设置的路由、按语言划分的导航、翻译后的 UI 和 SEO。 - **SEO** —— 内置元数据、Open Graph 图像（在构建时使用 Takumi 渲染）、sitemap、`robots.txt`、RSS feeds 和 JSON-LD。 - **API 参考** —— 通过 Scalar 将 OpenAPI 或 AsyncAPI 规范渲染为交互式参考（schema、身份验证、请求运行环境）。 - **导出** —— 允许读者将任何页面下载为 PDF 或 EPUB，完全在客户端完成，确保静态构建保持静态。 - **自定义** —— 组件覆盖、React islands、自定义页面、Tailwind v4 主题 token 和 `theme.css`，以及源组件注册表 (`blume add`)。 - **弹出** —— `blume eject` 会生成一个仍使用 `blume` 包的独立 Astro 项目。 ## CLI | 命令 | 描述 | | ------------------ | ----------------------------------------------------- | | `blume init [dir]` | 搭建项目（默认为交互式）。 | | `blume dev` | 启动带有热重载的开发服务器。 | | `blume build` | 构建静态（或服务端）站点。 | | `blume preview` | 预览上一次构建。 | | `blume add ` | 从注册表安装源组件。 | | `blume sync` | 重新获取远程内容源并重新生成。 | | `blume eject` | 将运行时提升为独立的 Astro 应用。 | | `blume check` | 使用 `astro check` 对文档站点进行类型检查。 | | `blume validate` | 验证内部、锚点、资源和外部链接。 | | `blume doctor` | 诊断配置和内容问题。 | 查看 [CLI 参考](https://useblume.dev/docs/reference/cli) 了解所有标志。 ## 工作原理 Blume CLI 会加载 `blume.config.ts`，将你的内容扫描成图，并在 `.blume/` 下生成一个由其驱动进行开发和构建的隐藏 Astro 项目。Astro 通过一个全匹配路由页面进行渲染，该页面会导入 Blume 内置的组件、生成的数据以及你的覆盖内容。`.blume/` 在每次运行时都会重新生成 —— 只会写入更改过的文件，因此热重载能保持快速 —— 直到你运行 `blume eject` 将其据为己有。 ## 部署 `blume build` 将静态 HTML 输出到 `dist/` —— 可部署到任何静态托管平台（Vercel、Netlify、Cloudflare Pages、GitHub Pages、S3 + CloudFront 或任何 CDN）。对于像 Ask AI 或 MCP 服务器这样的请求时功能，请切换到服务端输出并选择一个适配器： | 适配器 | 用于 | | ------------ | ------------------------------------ | | `vercel` | Vercel | | `netlify` | Netlify Functions | | `node` | 自托管 Node 服务器、容器 | | `cloudflare` | Cloudflare Workers 和 Pages | 在 Vercel、Netlify 和 Cloudflare Pages 上，会自动检测匹配的适配器和站点 URL。 ## 兼容性 | 要求 | 支持 | | ---------------- | --------------------------------- | | Node | 22.12+ | | 包管理器 | Bun, pnpm, npm, yarn | | 适配器 | Vercel, Netlify, Node, Cloudflare | ## 开发 此代码库是一个 monorepo：已发布的包位于 `packages/blume`，而 `apps/docs` 是 Blume 自己的文档，使用 Blume 构建。 ``` bun install bun run check # lint + format (Ultracite) bun run typecheck bun run test ``` 查看 [CONTRIBUTING.md](https://github.com/haydenbleasel/blume/blob/main/.github/CONTRIBUTING.md) 了解架构和约定。 ## 许可证 [MIT](./LICENSE) © Hayden Bleasel

标签：Astro, Markdown, MDX, MITM代理, SOC Prime, TypeScript, 安全插件, 开发工具, 文档生成器, 自动化攻击, 静态站点生成