Cloudflare 做了一个文档工具,它真正想解决的是 AI 时代的文档归属问题

做一个文档网站，今天已经不算难事。

选一个框架，写几篇 Markdown，加上侧边栏、搜索和深色模式，一个看起来不错的文档站很快就能上线。

但文档的使用者已经变了。

过去，文档主要写给人看。现在，搜索引擎要索引它，AI 助手要读取它，Coding Agent 要根据它修改代码，甚至文档本身也可能由 Agent 起草和维护。

这让一些过去不明显的问题同时冒了出来：

• 网页对人很好看，Agent 抓下来却只得到一堆导航和组件标签；
• 文档主题封装得很完整，但真正想改布局时，只能和主题 API 周旋；
• AI 可以生成页面，却没有清晰的来源、审核和质量控制机制；
• 内容、路由和侧边栏分别维护，时间一长就会彼此漂移；
• 文档可以被 Agent 读取，却很难让 Agent 安全地修改和持续维护。

Cloudflare 开源的 Nimbus，就是针对这组新问题设计的文档工具。

它的官网把自己定义为：

Docs for the agentic web.

如果只看页面，Nimbus 很像一个现代文档站模板。但它真正值得关注的，不是外观，而是：

1. 文档网站的可见部分应该完全属于你；
2. 人类和 Agent 都应该成为一等读者；
3. Agent 不仅要能读文档，还应该能参与创建、检查和维护文档。

Nimbus 到底是什么？

Nimbus 是一套基于 Astro 的文档站构建工具。

它当前建立在 Astro 7、Tailwind CSS v4 和 Rust Markdown 处理器 Sätteri 之上，并可选使用 React 19 创建交互内容。默认产物是静态网站，因此既可以部署到 Cloudflare，也能放到 Vercel、Netlify 或其他能够托管静态文件的平台。

创建项目只需要一条命令：

npx @cloudflare/create-nimbus-docs@latest

脚手架会询问项目目录、模板类型、包管理器和部署目标。安装完成后，运行：

cd my-docspnpm dev

你会得到一个具备侧边栏、全文搜索、面包屑、上下页导航、深浅色主题、移动端导航、SEO 元数据和 Agent 读取接口的文档站。

不过，把 Nimbus 理解成“Cloudflare 版 Docusaurus”并不准确。

传统文档框架通常把主题、布局和组件封装在依赖里，项目通过配置项和扩展 API 去改变它们。Nimbus 则刻意把系统分成两层。

第一层是不可见的基础能力。

它们放在 @cloudflare/nimbus-docs 包中，包括 Astro 集成、内容 Schema、侧边栏和目录数据助手，以及生成 Agent 读取接口的路由能力。

第二层是用户能看到的部分。

脚手架会把它们直接写进项目：

my-docs/├── src/│   ├── components/      # 页面组件│   ├── content/docs/    # Markdown 和 MDX 内容│   ├── layouts/         # 页面布局│   ├── pages/           # 路由│   ├── styles/          # 主题与排版│   └── components.ts    # MDX 全局组件注册表├── astro.config.ts├── nimbus.json└── package.json

这些文件不是只能覆盖的主题副本，而是从创建项目第一天起就属于你的源码。你可以改一个 Tailwind Class，重写整个布局，删掉不需要的组件，也可以重新组织目录。

Nimbus 把这条原则概括为：You own all your code。

“源码属于你”为什么是核心，而不只是宣传语？

文档框架通常面临一个取舍。

封装越完整，上手越快；但定制越深入，就越容易撞到框架边界。你可能需要等待主题开放一个配置项，也可能为了改一个细节，创建一层又一层覆盖样式。

Nimbus 选择的是另一条路线：脚手架负责把一个能工作的完整网站交给你，然后退到幕后。

这有两个直接结果。

首先，视觉和交互没有被某个上游主题锁住。

Nimbus 的颜色、间距、字体和布局宽度集中在 src/styles/globals.css 中，使用 --nb-* CSS 变量表达。浅色和深色模式都可以直接修改；正文排版也在项目自己的 prose.css 中。需要更大改动时，组件和布局源码同样在本地。

其次，Coding Agent 更容易理解整个项目。

如果页面结构隐藏在依赖内部，Agent 只能根据类型定义、文档和少量扩展点猜测系统行为。现在布局、组件、内容、样式和路由都在仓库里，Agent 可以像阅读普通 Astro 项目一样追踪修改会影响什么。

这也是 Nimbus 的“Agent 原生”能够成立的前提：

Agent 不只看得见最终网页，也看得见生成网页的完整代码。

当然，所有权也意味着责任。文件属于你以后，Nimbus 不会在升级时悄悄覆盖它们。你获得了自由，也需要自己审查和合并上游变化。后文会讲如何管理这个成本。

它不是给网页附加一份 `llms.txt` 那么简单

很多网站所谓的“AI 友好”，就是在根目录增加一份 llms.txt。

Nimbus 做得更系统。每个站点默认同时提供多种面向 Agent 的内容表面。

每个页面都有两份 Markdown 对应物

假设一个页面的地址是：

/get-started/

Nimbus 还会提供：

/get-started/index.md/get-started/index.mdx

index.md 是经过降级处理、适合直接阅读的干净 Markdown。页面中的组件会被转换，Agent 不必解析完整网页。

index.mdx 则保留作者写下的原始内容，包括 Import、JSX 和指令，适合需要理解或修改源内容的工具。

这一区分很重要：消费内容和编辑内容需要的格式并不相同。

站点同时提供索引和完整语料

Nimbus 会生成：

• /llms.txt：列出所有已发布页面及其 Markdown 地址；
• /llms-full.txt：把全站已发布内容合并成一份确定性的 Markdown 文档；
• /<section>/llms.txt：为每个顶层分区或内容集合生成独立索引。

轻量 Agent 可以先读索引，再按需获取页面；检索系统也可以一次获取完整语料。分版本文档还会在 Markdown Frontmatter 中携带版本信息，让 Agent 明确自己读到的是哪个版本。

页面仍然照顾搜索引擎和社交分享

每个页面的 <head> 中会加入 JSON-LD。配置站点 URL 后，Nimbus 还会生成 Sitemap 和 robots.txt。标题、摘要、Open Graph 图片、Canonical 和版本之间的 Alternate Link 都有相应支持。

因此，Nimbus 不是为了 Agent 牺牲人类网页，而是让同一份内容同时服务三类消费者：

内容源码├── HTML：给人类浏览├── 元数据、Sitemap、JSON-LD：给搜索系统└── Markdown、llms.txt、llms-full.txt：给 Agent 和检索系统

文件树就是网站本身

Nimbus 的另一个重要观点叫 The tree is the truth，即“文件树就是真相”。

在默认模式下，src/content/docs/ 下的目录同时决定 URL 和侧边栏：

src/content/docs/├── introduction.mdx           → /introduction├── guides/│   ├── index.mdx              → /guides│   ├── styling.mdx            → /guides/styling│   └── deploying.mdx          → /guides/deploying└── reference/    └── api.mdx                → /reference/api

移动文件，URL 和导航一起移动；删除文件，导航项也随之消失。这样就不需要再维护一份经常忘记更新的导航配置。

页面级细节由 Frontmatter 控制。Nimbus 只强制要求 title，同时支持：

• description：搜索摘要和页面描述；
• draft：开发环境可见，生产构建和 Agent 索引不可见；
• noindex：不被搜索引擎和 Agent 索引；
• searchable：单独控制站内搜索；
• sidebar.order、label、badge：控制导航顺序和展示；
• tableOfContents：调整或关闭页面目录；
• socialImage：设置页面分享图；
• prev、next：覆盖上下页链接；
• mode: custom：移除标准文档外壳，创建自定义落地页。

如果网站很大，不希望完全由文件树决定侧边栏，也可以在 astro.config.ts 中显式配置分组、外链和自动生成目录，或者只展示当前顶层分区。

写作层：Markdown 为主，MDX 负责表达能力

Nimbus 同时支持 .md 和 .mdx。

普通说明、概念和参考资料可以直接使用 Markdown；需要卡片、步骤、标签页、提示框或交互演示时，再使用 MDX 组件。

常用组件可以注册在 src/components.ts 中，之后所有 MDX 页面都能直接使用，不必反复 Import：

import { Aside } from "./components/ui/aside";import { Card } from "./components/ui/card";export const components = {  Aside,  Card,};

Nimbus 会在构建前检查 MDX 中的 PascalCase 标签。组件没有注册、忘记 Import，或者错误地写成小写时，构建会直接失败，而不是上线后把它当成奇怪的纯文本标签。

代码块则由 Shiki 在构建期完成高亮，支持：

• 文件名标题；
• 指定行高亮；
• 新增、删除、警告和错误标记；
• 聚焦某些代码行；
• 浅色和深色主题自动切换；
• npm、pnpm、yarn、bun 多包管理器命令标签页。

这些能力都不会把客户端高亮器一起发给浏览器。

文档也应该像代码一样接受检查

Nimbus 把文档检查分成两层。

第一层是 构建验证器，负责阻止真正会破坏网站的问题，例如：

• 配置结构错误；
• Frontmatter 不符合 Zod Schema；
• MDX 组件不存在或未注册；
• 路由重复；
• Registry 记录与使用方式不一致。

第二层是 按需运行的写作 Linter，检查内容质量问题。规则使用稳定 ID，例如：

nimbus(config, {  rules: {    "nimbus/single-h1": "error",    "nimbus/bare-url": "warn",  },});

然后可以运行：

npx @cloudflare/nimbus-docs lintnpx @cloudflare/nimbus-docs lint --fixnpx @cloudflare/nimbus-docs lint --format=json

这里有一个容易忽略的细节：写作规则默认全部关闭，需要项目主动启用。

而且 Lint 结果不会阻止开发环境渲染页面。Nimbus 有意把“网站会坏”和“内容写得不够好”分开处理：前者阻止构建，后者保持醒目但不妨碍草稿预览。

--format=json 则是专门为 Agent 工作流准备的。Agent 可以读取带位置和规则编号的诊断，应用自动修复，再重新运行检查。这比在 Prompt 里笼统地写一句“提高文档质量”可靠得多。

Registry：复制代码，或者把任务交给 Agent

Nimbus 提供一个 Registry，但它和传统组件库的安装方式不同。

Registry 中有三类内容：

• registry:ui：UI 组件；
• registry:lib：工具函数；
• registry:feature：交给 Coding Agent 执行的功能配方。

添加一个普通组件时：

npx @cloudflare/nimbus-docs add accordion

CLI 会解析组件依赖，将源码复制到 src/components/ 或 src/lib/，并补充所需 npm 依赖。复制完成后，这些文件归项目所有，可以自由修改。

添加一个功能时，逻辑不同：

npx @cloudflare/nimbus-docs add 404-page

“404 页面”不是一个到处都应该完全相同的组件。它需要读取现有布局、品牌样式和路由结构。因此 Registry 不会粗暴复制固定文件，而是提供一份 Markdown Runbook，让 Coding Agent 先理解项目，再规划、实施和验证。

如果 CLI 没有自动检测到 Agent，也可以手动把配方交给它：

npx @cloudflare/nimbus-docs add 404-page --print | claude

目前官方 Registry 还提供搜索、Mermaid、Changelog、新内容集合、新文档版本等 Feature，以及 Overview、Quickstart、Tutorial、How-to、Concept、Reference、Example、Troubleshooting 等内容类型配方。

这个设计体现了一条很实用的边界：

确定、重复的改动适合复制文件；需要理解项目语境的改动，适合让 Agent 参与。

交互式文档：框架管理生命周期，你负责表达

很多技术概念只靠静态文字很难讲清楚，例如请求如何流转、状态如何变化、节点怎样连接。

Nimbus 为此提供了可选的 nimbus-docs/react。它包含一个无头的 <Diagram> 容器，以及 usePhase、useMeasure、useTabIndicator、useDiagram 等 Hook。

框架负责的是繁琐但通用的部分：

• 组件离开视口后暂停；
• 尊重系统的“减少动态效果”设置；
• 键盘操作；
• 错误边界；
• 多个 Astro Island 之间的协调。

实际画出来什么、采用什么颜色、怎样讲解概念，仍由项目自己决定。按钮、标签页和播放控制也会通过 Registry 复制到本地。

React 及 React DOM 是可选 Peer Dependency。完全不需要交互图的站点，不必承担这部分客户端成本；需要时再按需安装，并使用 client:visible 在进入视口时 Hydrate。

搜索、版本和部署也没有被忽略

Nimbus 默认使用 Pagefind 提供全文搜索。Pagefind 在构建完成后扫描 dist/ 并生成静态索引，不需要后端服务，因此部署到任何静态托管平台都能工作。

如果已有 Algolia 或自建搜索，也可以关闭默认搜索，或者实现自定义 SearchProvider，保留 Nimbus 的搜索界面。

版本管理采用了一个很朴素的设计：每个版本就是一个内容集合。

src/content/├── docs/├── docs-v2/└── docs-v3/

同一套机制也能表示语言和产品，例如 docs-fr/、docs-api/、docs-cli/。只有真正需要版本时才增加集合，不必从项目第一天就承担一套复杂的版本系统。

部署方面，Nimbus 输出普通的 Astro 静态站点：

pnpm build

构建结果位于 dist/，可以托管到任意静态平台。选择 Cloudflare 作为脚手架目标时，项目会附带已经连接好的 wrangler.jsonc，可以继续使用 Wrangler 部署。

怎样把 Nimbus 用得更好？

Nimbus 的默认能力很多，但“功能都打开”不等于“文档就会变好”。更合理的使用方式，是把它当成一套文档工程基础设施，而不是漂亮模板。

1. 先设计读者的问题，再设计目录

因为 Nimbus 的文件树同时决定 URL 和导航，目录一旦混乱，网站的信息架构也会混乱。

开始写内容前，可以先把页面分成不同职责：

• Overview 回答“这是什么，我该从哪里开始”；
• Quickstart 提供从零到第一次成功的最短路径；
• Tutorial 负责教学；
• How-to 解决具体任务；
• Concept 解释原理和边界；
• Reference 提供完整、稳定、适合查询的事实；
• Troubleshooting 直接使用用户会搜索的错误信息作为标题。

不要把教程、概念解释、API 参数和错误处理全部塞进一篇“超级文档”。Nimbus 的内容配方不是强制模板，但它们很适合帮助团队建立共同语言。

2. 大多数页面坚持使用 Markdown

MDX 很强，但每个页面都塞满组件会增加维护成本，也会让原始内容更难复用。

一个简单原则是：

• 能用 Markdown 表达，就使用 Markdown；
• 需要结构化展示时，使用已经注册的轻量组件；
• 只有“交互本身就是解释的一部分”时，才引入 React Diagram。

这样生成的 Markdown Twin 也会更干净，更适合 Agent 和检索系统消费。

3. 不要忘记主动开启 Lint 规则

Nimbus 的构建验证默认工作，但写作规则默认关闭。如果不配置 rules，nimbus-docs lint 不会凭空替团队定义内容标准。

更稳妥的做法是先选择少量高价值规则，将确定性问题设为 error，表达性问题设为 warn，再逐步增加。不要第一天就打开所有规则，把历史文档变成一片红色。

CI 可以组合运行：

pnpm typecheckpnpm lint:docspnpm build

Agent 修改内容时，则优先使用 JSON 诊断和 --fix，修复后再构建验证。

4. 把 `AGENT.md` 当作维护契约，而不是装饰文件

脚手架会在项目根目录写入 AGENT.md，供 Coding Agent 了解项目规则。

应该把真正稳定、跨任务适用的信息写进去，例如：

• 内容目录的职责；
• 术语和产品命名；
• 哪些命令必须在修改后运行；
• 哪类页面使用哪种内容结构；
• 哪些生成文件不能直接修改。

不要把某一次任务的临时要求长期留在这里。AGENT.md 越准确，Agent 越能安全地维护文档。

5. 给 AI 生成内容留下来源和审核状态

Nimbus 的内容集合 Schema 可以扩展。官网展示了一种做法：增加 aiGenerated 字段，标记由 Agent 起草、尚未经过人工审核的页面，并在页面操作区域显示“awaiting review”。

docsCollection({  schemaFields: {    aiGenerated: z.boolean().optional(),  },});

这比仅在团队口头约定“AI 写完要检查”更可靠。来源和审核状态应该与内容一起进入版本控制，而不是留在聊天记录里。

还可以继续扩展 reviewedBy、reviewedAt 或适合团队流程的字段，但不必一开始就设计复杂审批系统。先解决最重要的问题：读者能不能知道这份内容是否经过人类确认。

6. 把 Agent 接口当成产品能力进行验收

网站上线前，不要只点开 HTML 页面看样式。还应该检查：

/llms.txt/llms-full.txt/某个关键页面/index.md/某个关键页面/index.mdx

确认草稿和 noindex 页面没有意外进入索引，Markdown 降级后仍然可读，版本标签正确，描述足以帮助 Agent 判断页面用途。

如果某些内容永远不应该被 Agent 读取，官方建议不要只依赖展示层隐藏，而应把它放在内容集合之外。

7. 认真管理“源码所有权”带来的升级责任

Nimbus 会使用 nimbus.json 记录脚手架版本、模板 Tag、组件来源、Registry Release 和内容 Hash。这个文件应该提交到 Git。

日常可以先运行只读检查：

npx @cloudflare/nimbus-docs outdatednpx @cloudflare/nimbus-docs diff

outdated 用于了解 Registry 组件和 Starter 文件是否落后；diff 用于区分：

• 上游改了、你没改，可以安全更新；
• 你和上游都改了，需要手动合并；
• 只有你改了，继续保留自己的版本。

更新组件时，Nimbus 默认不会覆盖本地文件。只有显式使用 --overwrite 才会替换，因此更新后一定要查看 git diff。

8. 尽早决定 Markdown 处理器路线

Nimbus 默认使用 Sätteri，优点是 Rust 实现、速度快。但它也有一个明确约束：通过 Astro MDX 配置附加的 Remark/Rehype 插件不会生效。

如果项目依赖 Mermaid、数学公式或自定义 Remark 插件，应尽早切换到 Unified 处理器。这样会放弃 Sätteri 的性能优势，但能使用成熟的 Unified 插件生态。

不要等大量文档写完后才发现核心插件链与默认处理器不兼容。

9. 生产构建需要完整 Git 历史时，要调整 CI

Nimbus 可以通过 Git 提交记录生成页面最后更新时间。但 Vercel、Cloudflare Pages 和 GitHub Actions 等 CI 环境经常默认使用浅克隆。

如果希望线上显示准确的 Git 作者时间，需要在 Checkout 阶段获取完整历史，例如：

- uses: actions/checkout@v4  with:    fetch-depth: 0

否则 Nimbus 会尝试使用 Frontmatter 中的 lastUpdated，没有可用值时则不显示更新时间。

Nimbus 适合谁，又不适合谁？

Nimbus 很适合以下项目：

• 已经使用或愿意采用 Astro、TypeScript 和现代前端工具链；
• 文档外观和交互需要较深定制；
• 希望源码、组件和内容都留在自己的仓库；
• 希望文档能够直接服务 AI Agent 或 RAG 系统；
• 团队准备让 Coding Agent 参与文档创建和维护；
• 偏好静态部署，不想维护搜索后端。

它不一定适合以下情况：

• 团队只想选择一个托管 SaaS，不愿维护前端项目；
• 希望主题升级能够自动覆盖，而不是自己审查差异；
• 项目严重依赖现有 Remark/Rehype 插件，却又不愿切换处理器；
• 需要一个已经长期稳定、承诺严格兼容的成熟平台。

最后一点尤其重要。

Nimbus 官方仓库明确标注它仍然是 Work in progress，当前处于 0.x、尚未到 1.0。它已经可以用于真实网站，但 Minor Version 之间仍可能调整公共接口，也还存在粗糙之处。

如果现在用于生产环境，官方建议锁定版本，并在升级前查看各个 Package 的 Changelog。Nimbus 的框架包和脚手架包独立发布，版本号也不一定同步。

Nimbus 真正有价值的地方

Nimbus 并不是因为多了搜索、深色模式或漂亮代码块而特别。这些能力在今天已经是优秀文档工具的基础配置。

它真正提出了一个更值得讨论的问题：

当文档同时由人和 Agent 创建、阅读、修改时，文档系统应该怎样重新设计？

Nimbus 的答案是：

• 不把重要代码藏在主题依赖后面；
• 不让 HTML 成为内容唯一的出口；
• 不把 AI 生成内容默认当作已经可信；
• 不用另一份配置重复描述内容树；
• 不要求所有扩展都通过固定 API 完成；
• 让机器可读、质量检查、来源记录和 Agent 工作流成为默认基础设施。

以前，我们常把文档网站理解成产品的“说明书页面”。

在 Agent 时代，文档开始变成一种公共接口：人通过它理解产品，搜索引擎通过它组织信息，Agent 通过它回答问题、生成代码和执行任务。

Nimbus 最有意思的地方，不是它已经解决了所有问题，而是它把这次变化直接写进了架构。

如果你的文档未来不仅要“给人看”，还要真正进入 Agent 的工作流，那么 Nimbus 值得认真试一次。

参考资料

1. Nimbus 官网：https://nimbus-docs.com/
2. Get started：https://nimbus-docs.com/get-started/
3. Philosophy：https://nimbus-docs.com/philosophy/
4. Installation：https://nimbus-docs.com/installation/
5. Project structure：https://nimbus-docs.com/project-structure/
6. Agent surfaces：https://nimbus-docs.com/ai/agent-surfaces/
7. CLI：https://nimbus-docs.com/cli/
8. Writing 文档：https://nimbus-docs.com/writing/llms.txt
9. Nimbus GitHub 仓库：https://github.com/cloudflare/nimbus