Docs-as-Code

2025年1月，我在准备下一个文档项目 「云图 -- 云计算图志: 构建」 Cloud Atlas: Arch ，调查选型撰写工具:

  • 想要选择一个比现在所使用的 Sphinx文档 更为现代化美观，并且能够整体融合到一个网站中的静态网站生成器

  • 主流技术，有非常活跃和前途的社区支持

  • 能够促使自己更好学习前端构建技术的平台

虽然我已经撰写 「云图 -- 云计算图纸: 探索」 好些年了，但是很少关注和调研整个文档工具生态。搜集和整理一些资料以后，对于最近几年涌现出大量文档工具以及 Docs-as-Code 理念，有了一些了解和想法，也为后续自己选择工具规划网站做了一些准备。

概念

../../_images/docs-as-code.jpg

所谓 docs-as-code 就是采用代码开发的方式:

  • 使用 git 版本控制来维护每一次文档修改

  • 代码review控制文档质量以及多人写作完成文档

  • 使用 GitLab 这样的的CI/CD工具管理整个撰写、编译、发布流程: 在GitLab平台实现docs as code

  • 使用Issue跟踪项目bug

    • 分支策略: 不同章节的工作可以多人协作完成

    • Pull Requests: 引入代码review过程

    • 持续集成: 可以自动完成文档测试和部署

并且现在Netlify和GitHub提供了托管平台，可以为文档最后发布提供稳定的支持。

格式和工具

围绕以下格式流派:

  • Markdown: 很多大型组织用来构建文档库

备注

从GitHub的星来看， Docusaurus (5.76w star) 和 Astro (4.8w star)是最流行的内容网站框架，特别是 Astro 号称集成不同的主流前端框架，可能比较适合某类熟悉React或Vue框架的开发。

Nextra (1.21w start)则由 Next.js 开发

  • Asciidoc: 很多开源项目使用的文档系统，适合电子书输出，例如 FreeBSD doc

    • docToolchain

    • Asciidoctor GitHub开发的Asciidoc生成器

    • Antora

  • reStructuredText: Python社区主要使用的文档系统，也是偏重技术文档内容但不care外观的选择，例如 kernel.org

对比和思考

从电子书角度来看， Asciidoc 和 reStructuredText 是主要的文档格式，被很多严肃、核心的开源项目，例如FreeBSD和Kernel选为文档基础。我感觉主要原因是这些开源团队更侧重于后台技术，需要严谨的文档格式，同时不希望太过花哨的展示形式冲淡了作为核心技术的稳健风格。

从市场工具来看， Markdown 显然是更为流行的网站工具，并不局限于电子书，而是通过WEB对外展示公司和组织的技术。围绕 Markdown 的工具更是层出不穷，构建了大量美轮美奂的文档网站。

从核心技术角度来看， Markdown 工具技术都是 JavaScript 流派的，最流行的文档工具其实核心技术都是基于 DMX + Node.js + TypeScript + React (或者还有支持 vue 等前端框架)。所以我感觉区别不是很大，主要是掌握核心技术，也就是底层的 JavaScript 系列前端技术，切换工具也应该不难。

Asciidoc 和 reStructuredText 更适合后端技术领域。

目前我想学习一些前端技术，所以我在选型时会选择 Markdown 流派，同时我会结合自己近期的学习路线来最终选择一个平台。可能选择基于 Next.js 的 Nextra 。

参考