文档代码化：重塑软件开发的文档系统

最近一个月里，我在开发一个基于 Git + Markdown 的全新文档系统。我定制了一个基于 markdown 的标记语言，以支持起雷达图、条形统计图、思维导图等图表的文档系统。这个系统将在未来几个月内发布。当然了，视进度而看，也可能是月底。

过去的几年里，我们一直在讨论各种各样的代码化，基础设施代码化、设计代码化、需求代码化……。在我的那一篇《云研发：研发即代码》中，设计了一个完全代码化的软件开发流程。而今天我们将讨论另外一个有趣的存在：文档。

在《架构金字塔》中，我将文档定义为支撑五层架构模型的一种存在。因为文档在一个系统中是非常重要的存在，我们用它来指导开发工作，用它来记录问题，用它来写下规范……。总而言之，它很重要，所以我们重新讨论一下这个话题。

引子 1：架构决策记录：格式化文档

静态站点生成是一种混合式的 Web 开发方法，它通过部署预先构建的静态文件进行部署，来让开发者在本地构建基于服务器的 站。

当 GitHub Pages 成为了程序员首选的 博客/内容/文档 服务器时，他/她也采用了静态站点生成这一项技术。静态站点生成有各种各样的优点：

• 可靠性、安全性、稳定性、可用性等更好

• 可版本控制

• 易于测试

• 易于实践持续部署。提交即可上线

• 灵活，易于定制

而事实上，静态站点生成所做的最主要的一件事是：将数据库中的数据进行代码化。采用诸如 WordPress 这样的 CMS 时，我们是将数据存储在数据库中，以实现对于数据的 CRUD。一篇文章变为数据库二进制文件中的一个片段。

随后，静态站点生成工具做了第二件事情便是将文本内容可视化出来，便于人们阅读。这样一来，我们便实现了发布-开发分离。

引子 3：定制的标记语言：扩充

即，我们将过程拆为了三步：

• 开发人员，编写内容的展示

• 发布的时候，集成这两部分代码

我们依旧可以选择用源码管理的方式来管理内容。只需要将数据库接口，转变为 Git 服务器接口即可 —— 当然它们是稍有不同的。不过呢，把本地的 Git 转换为 Git remote 那就基本一致了。

文档代码化

3.1 重写 markdown 渲染器

我们在这个过程中，遇到的最大的挑战是，随着我们对 markdown 语法的不断扩充，相关的代码已经变成了一坨大泥球。所以，我们不得不重写了这部分代码：

借助于 marked.js 的 lexer 解析出 token

根据 token 修改生成新的 token

遍历新生成的 token，渲染出元素

结合虚拟滚动，解决性能问题

已经开源在 GitHub，并发布对应的 npm 包： 。

4. 发布这个项目

我们已经在 GitHub 上发布了这个文档化系统，你可以参与到其中的使用和开发。

GitHub：https://github.com/phodal/ledge

项目首页：https://devops.phodal.com/

5.  开放与协作

让每个人都可以访问，并提出修改意见。

总结

然后，你就成为了一个 Markdown 工程师，D3.js 设计师，Echart 配置管理员。