场景：文档总在功能上线后掉队？用 docs.dev 把文档发布重新放回 Git 与 Cloudflare
“代码合并了，文档下周再补”几乎是每个团队都会积累的技术债。问题往往不在于没人会写 Markdown，而在于文档系统和开发流程是两套系统：代码在 Git、审查在 Pull Request、部署在 CI；文档却在另一个 SaaS 编辑器里，权限、版本、发布路径都需要单独维护。
docs.dev 提供了一个很有意思的反向方案：它不是把仓库内容导入某个托管平台，而是把文档站作为部署到自己 Cloudflare 账号中的模板。页面保存在 Git 仓库的 MDX 文件中；编辑器发布一次改动，本质上是一次 Git commit，之后由 push-to-deploy 自动更新站点。对已经有 GitHub 和 Cloudflare 流程的开发团队来说，这比再引入一套“文档数据库”更容易纳入现有治理。
先辨清它解决的边界
docs.dev 的开源仓库是 TypeScript 项目，采用 MIT 许可证。它基于 Fumadocs、Next.js 与 MDX，阅读层则使用 pretext 的文本测量布局：服务端先输出正常的段落文本，客户端在增强后再把同一份文本按行排布到图片、代码块或图形周围。这样无 JavaScript 的访问者、搜索引擎和读屏软件仍能取得正常阅读顺序，而不是只得到一张 Canvas 截图。
它的重点不是替代所有内容管理系统，而是适合下面这个场景：
- 产品与 API 文档已经或计划放进 Git；
- 希望文档修改跟随分支、提交、回滚和代码审查；
- 想让 Claude Code 等编码 Agent 能按仓库约定起草文档，但仍保留人类审核；
- 希望最终站点与账号、域名和部署权都留在自己的 Cloudflare 组织内。
这里要避免一个常见误解：仓库虽然可公开获取，部署到 Cloudflare Workers 仍有平台条件。项目 README 明确说明，当前服务端 Worker 的压缩后体积约为 5.3 MiB，超过 Workers 免费计划的 1 MiB 脚本限制；按其说明，部署此模板需要 Workers Paid 计划。不要把“没有 docs.dev 平台订阅费”误解成“所有底层云资源都免费”。
从本地运行开始，而不是直接接入生产文档
先在一个临时仓库验证渲染、导航和团队流程。项目 README 给出的本地命令很简单：
pnpm install pnpm dev
/docs 是常规的文档站入口，/showcase 用来观察 pretext 的排版效果。建议先把一小段真实的快速开始文档迁入 content/docs/，而不是一口气搬迁全部知识库。单个页面使用 MDX，基本 frontmatter 只需标题和描述：
--- title: API 快速开始 description: 用五分钟完成首次请求。 --- ## 创建访问令牌
注意正文从 H2 开始：该模板会从 title 生成页面 H1；侧边栏顺序由 content/docs/meta.json 管理。这些约定很适合写进团队的 CLAUDE.md，让人和 Agent 都遵循同一份规则。
发布链路：让“发布文档”成为一次可追溯提交
推荐路径是使用仓库提供的 Deploy to Cloudflare 流程：它会将模板克隆到你的 GitHub 或 GitLab 账号，在你的 Cloudflare 账号中构建并部署，并配置后续 push 自动重新部署。手动预览和部署时，README 列出的命令是：
pnpm cf:preview pnpm cf:deploy
在线编辑并没有绕过仓库。编辑器的草稿会放在同一个仓库的专用 docsdev-drafts 分支；发布时，页面和上传资源通过 GitHub API 写入仓库，随后由既有 CI 部署。这样一个文档修订可以像代码一样回答三个问题：谁改的、为什么改、如何撤回。
如果选择独立的 /admin 登录方式，项目要求显式配置 GITHUB_PAT、ADMIN_PIN 与 ADMIN_SECRET；它没有提供内置默认凭据。这一点很关键：不要为了方便把具有 contents:write 权限的令牌写进仓库或前端配置。令牌应通过 Cloudflare/Wrangler 的 secret 管理，并限定到最小可用仓库权限。
让 AI 起草，但不要让 AI 直接越过审查
docs.dev 仓库附带 CLAUDE.md 和技能文件，Agent 可以据此新增页面、更新导航并运行检查。一个稳妥的使用方式是把 Agent 的产物限制在分支或草稿阶段：让它根据代码变更起草页面，再由维护者在渲染后的页面中检查术语、示例、版本和安全说明，最后再发布。
例如，团队可以把请求描述得足够具体：
为新 webhook API 起草文档；接口定义位于 src/routes/webhooks.ts。 更新导航，并在提交前运行 pnpm types:check。
重点不是命令本身，而是把验收条件写清楚：事实来自哪个源文件、哪些示例必须可运行、谁负责最终发布。对于 API 文档，docs.dev 还支持将 OpenAPI JSON 放入 openapi/ 并在构建时生成参考页面；生成内容应从规范重新构建，而不是手工修改生成页面。
迁移时的三个实践建议
- 先保留 Git 为唯一真相来源。 不要同时在旧平台和新编辑器长期双写。选择一个仓库分支作为发布源，历史与回滚才不会分叉。
- 把草稿当成协作区，不当成发布环境。 共享草稿适合多人润色，但对外可见内容仍应只来自默认分支的成功部署。
- 把阅读体验与可访问性一起验收。 pretext 的视觉排版是增强层；仍应检查无脚本阅读、移动端、代码复制、链接和搜索是否保持可用。
文档掉队不是写作能力问题，而是发布链路没有嵌入工程链路。docs.dev 的价值在于把“页面编辑—Git 提交—CI 部署”收敛为同一个工作流：仓库仍是事实来源，Cloudflare 仍是运行边界，人类审核仍是最后一道质量门。对于希望保有基础设施与内容控制权的开发团队，这是一条比“再买一个文档 SaaS”更值得先试验的路线。