《DDIA 逐章精读》小册

引子

每次 DDIA 读书会[1]之后，会把文字稿发在知乎[2]、博客[3]或者微信上。但是文字稿实在是又臭又长，这些平台似乎都不太是一个好的载体。而 GitHub Pages 使用 Jekyll[4] 渲染，但只支持寥寥几个免配置的主题，怎么说呢，就都挺丑的。

某天偶然发现 Vonng 的 DDIA 翻译[5]是用的 docsify 工具将 markdown 文件生成的网页，于是看了看其官方文档[6]，研究了下用法。十分意外，真是开箱即用、简洁大方。

这里简单记录下过程，希望能够帮到想写“小册”、“文档”并做成网页的同学，顺便推广下 DDIA 分享文字稿集结而成的——《DDIA 逐章精读》小册：https://ddia.qtmuniao.com/[7]，原文托管在 github[8] 上，欢迎大家拍砖，不吝赐教，多提 issue、pr。

Docsify

Docsify 一个文档向的静态网页生成工具，配合 GitHub Pages 使用，体验绝佳。

初始化

初始化一个 GitHub repo，然后使用 docsify 初始化：docsify init . ，会生成：

1. README.md：文档的首页。也是我们 GitHub repo 通常的首页，可以看出 docsify 应该就是定位和 GitHub 生态深度绑定。
2. index.html ：docsify 配置页。

对于我来说，我是已经有一个仓库，里面有一些 markdown 文件，此时初始化，会提示 ✔ Are you sure you want to rewrite it? (y/N)放心同意就好，并不会真的覆盖你的文档数据。

此外，如果你的 repo 本来有 _config.yml(JekyII 默认配置文件)通常还生成一个空的文件 .nojekyll来禁止 GitHub Pages 启用 JekyII 来渲染。

基本配置

下面是我的 docsify 配置，仅配置了文档名字、仓库、侧边栏、侧边栏展开深度、文档主题颜色、自动回到顶部：

window.$docsify = {
  name: '《DDIA 逐章精读》',
  repo: 'https://github.com/DistSysCorp/ddia',
  loadSidebar: true,
  subMaxLevel: 2,
  themeColor: '#77AAC2', 
  auto2top: true
}

值得一提的是侧边栏，默认会使用 _sidebar.md 作为侧边栏，但你只需要在文档中写各文档标题以及链接即可：

- [序](preface.md)
- 第一部分：数据系统基础
    * [第一章：可靠、可扩展、可维护](ch01.md)
    * [第二章：数据模型和查询语言](ch02.md)
    * [第三章：存储与查询](ch03.md)
    * [第四章：编码和演进](ch04.md)
- 第二部分：分布式数据
    * [第五章：冗余](ch05.md)
    * [第六章：分区](ch06.md)

而定位到某一篇文章后，一级标题、二级标题自动展开的效果，只需配置：

subMaxLevel: 2,

十分方便。

文档组织

仓库文档组织如下：

.
├── CNAME
├── README.md
├── _sidebar.md
├── ch01.md
├── ch02.md
├── ch03.md
├── ...
├── img
│   ├── ch01-book-software-design.jpeg
│   ├── ch01-data-society.png
│   ├── ch01-fig01.png
│   ├── ch01-fig02.png
│   ├── ch01-fig03.png
│   ├── ch02-06.png
│   ├── ...
├── index.html
├── js
│   ├── docsify.min.js
│   ├── search.min.js
│   └── vue.css
└── preface.md

其中值得一提的是：

1. 封面：README.md ，就是最终网站首页，通常用来放一些说明性文字和导航。
2. 章节：chxx.md，每一章具体内容，我使用了前面填 0 的方式命名，如 ch01.md，这样如果超过 10 章，且不大于 99 章的情况下，单词序即章节序。
3. 配图：放到了 img 文件夹中，严格来说，如果图片非常大和多，不建议放到 repo 中浪费 GitHub 流量，可以额外找图床。
4. js：这个本来不需要有，下一节说。
5. 其他：_sidebar.md 是侧边栏，上一节讲了，preface.md 就是序言啦，随便写点，看起来更像一本书:)。

docsify js 资源

使用 docsify init . 命令默认生成的 index.html 使用的 js 是在 cdn.jsdelivr.net中 host 的，似乎被墙了，访问很慢。因此最好将所需资源下载下来放到 repo 中：

docsify.min.js  // 主文件
search.min.js   // 搜索用到
vue.css         // 主题样式用到

我偷了个懒，直接 copy 了 Vonng repo 的，因此也将 js 和 css 混到一个 js 目录中了。

自定义域名

首先，你要有个域名。然后需要两个步骤：

1. 在 GitHub 仓库中 Settings > Pages > Custom domain，配置一个你喜欢的二级域名，当然顶级的也行。例如：ddia.qtmuniao.com
2. 在你的域名服务提供商的 DNS 解析页面里，添加一个 CNAME 记录，指向你的 github 个人或者组织名字即可，不需要指向具体仓库， GitHub Pages 内部应该会路由。例如：

CNAME ddia distsyscorp.github.io. 1 小时

最后可以在 Settings > Pages 中勾选下 Enforce HTTPS，使用 https 加密访问更佳。

小结

简单记录了下使用 docsify 工具将 markdown 文件变成静态网页的方法，真的很方便，希望能够帮到想要快速制作简单相关网页的同学。最后，我们的 DDIA 逐章分享[9]仍在进行，小册也会持续更新，欢迎 Star，提 issue 和 PR。

看到这，你说 DDIA 是什么？可以看下我之前写的读书小记[10]，也是本小册的序。

参考资料

[1]

DDIA 读书会: https://docs.qq.com/sheet/DWHFzdk5lUWx4UWJq

[2]

分布式点滴: https://www.zhihu.com/column/learn-distributed-system

[3]

我的博客: https://www.qtmuniao.com/

[4]

Jekyll 一个静态网页生成引擎: https://jekyllrb.com/

[5]

DDIA 翻译: https://github.com/Vonng/ddia

[6]

docsify 官方文档: https://docsify.js.org/

[7]

DDIA 逐章精读小册: https://ddia.qtmuniao.com/

[8]

DDIA 逐章精读 repo: https://github.com/DistSysCorp/ddia

[9]

DDIA 逐章分享: https://ddia.qtmuniao.com/

[10]

DDIA 读书小记: https://ddia.qtmuniao.com/#/preface