nimbus：Cloudflare 开源的人机双读文档框架，MDX 出 HTML 和 Markdown

给 AI 写文档的尴尬在于格式：人要 HTML，Agent 要 Markdown，维护两份迟早跑偏。vikingmute 2026-11-04 推荐的 nimbus 是 Cloudflare 开源的文档框架（MIT，TypeScript，截至 2026-11-04 有 1,723 星），建立在 Astro 上把这件事定成一条流水线：你照常写 MDX，构建时同时产出给人看的 HTML 和给 Agent 看的 Markdown 版本，外加 llms.txt 与 llms-full.txt——这正是本站为搜索引擎与 AI 引用手工维护的那套产物的框架化版本。

核心功能

• 双格式发布：文档与 API 参考页自动生成 Markdown 版，加 llms.txt 与 llms-full.txt；隐藏版本不会泄进 Agent 产物。
• 写作组件：MDX 组件覆盖代码块、标签页、步骤、卡片、文件树、可复用片段与交互图，部分用 nimbus-docs add 按需装；API 参考从 OpenAPI 3.x 生成，支持多版本。
• 内容检查：构建时校验配置、frontmatter 与 MDX 组件；lint 报告写作错误（不阻断构建）；check 不构建就能查环境、结构、内容与类型，--fix 应用安全修复，--json 把结果直接喂给 Agent。
• Agent 输出可选件：Agent Skills、WebMCP 搜索与远程 MCP server，把文档做成 Agent 可直接调用的服务。
• 内容来源扩展：除本仓库外还能从其他 Git 仓库或 Notion 拉页面，支持文档版本与搜索。

典型使用场景

• 开源项目文档：一份源同时服务人类读者和来查文档的编码 Agent，README 里那句「为人和 Agent 写文档」就是这个意思。
• API 文档站：OpenAPI 生成加多版本，Agent 拿 Markdown 版本比爬 HTML 准确得多。
• 团队知识库：Notion 里的内容拉进站点统一发布，check --json 让 Agent 自己维护文档质量。

快速上手

需要 Node.js 22.12+：

npx @cloudflare/create-nimbus-docs@latest my-docs --yes --package-manager npm
cd my-docs && npm run dev

页面放在 src/content/docs/ 写 MDX；静态构建 npm run build 后任意托管，远程 MCP server 等需要服务端的功能可选 Cloudflare/Netlify/Vercel/Node 适配器。

小结

nimbus 适合要同时服务人类与 Agent 读者的项目文档和 API 文档团队；纯内部 wiki 或要所写即所见（Notion 式编辑器）的团队不对口——它默认你愿意在仓库里写 MDX。要点与边界：MIT、TypeScript、脚手架把站点代码完整拷进你的仓库（可改任何部分）；Pre-1.0，官方明说公共 API 会在 minor 版本间变化，升级前看 changelog。它赌的方向和本站一致：文档的下一条大读者不是人，是带着任务的 Agent——与其等人来读，不如把 Markdown、llms.txt 和 MCP 接口一起备好。同样面向 Agent 读者设计内容的还有 agent-browser-control 那篇对浏览器自动化方案的拆解，两篇合起来正好覆盖 Agent 获取信息的两个入口。