引子
每次 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 . ，会生成：
- README.md：文档的首页。也是我们 GitHub repo 通常的首页，可以看出 docsify 应该就是定位和 GitHub 生态深度绑定。
- index.html ：docsify 配置页。
对于我来说，我是已经有一个仓库，里面有一些 markdown 文件，此时初始化，会提示 ✔ Are you sure you want to rewrite it? (y/N)放心同意就好，并不会真的覆盖你的文档数据。
此外，如果你的 repo 本来有 _config.yml(JekyII 默认配置文件)通常还生成一个空的文件 .nojekyll来禁止 GitHub Pages 启用 JekyII 来渲染。
基本配置
下面是我的 docsify 配置，仅配置了文档名字、仓库、侧边栏、侧边栏展开深度、文档主题颜色、自动回到顶部：
代码语言：javascript复制window.$docsify = {
name: '《DDIA 逐章精读》',
repo: 'https://github.com/DistSysCorp/ddia',
loadSidebar: true,
subMaxLevel: 2,
themeColor: '#77AAC2',
auto2top: true
}
值得一提的是侧边栏，默认会使用 _sidebar.md 作为侧边栏，但你只需要在文档中写各文档标题以及链接即可：
代码语言：javascript复制- [序](preface.md)
- 第一部分：数据系统基础
* [第一章：可靠、可扩展、可维护](ch01.md)
* [第二章：数据模型和查询语言](ch02.md)
* [第三章：存储与查询](ch03.md)
* [第四章：编码和演进](ch04.md)
- 第二部分：分布式数据
* [第五章：冗余](ch05.md)
* [第六章：分区](ch06.md)
而定位到某一篇文章后，一级标题、二级标题自动展开的效果，只需配置：
代码语言：javascript复制subMaxLevel: 2,
十分方便。
文档组织
仓库文档组织如下：
代码语言：javascript复制.
├── 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
其中值得一提的是：
- 封面：README.md ，就是最终网站首页，通常用来放一些说明性文字和导航。
- 章节：chxx.md，每一章具体内容，我使用了前面填 0 的方式命名，如
ch01.md，这样如果超过 10 章，且不大于 99 章的情况下，单词序即章节序。 - 配图：放到了 img 文件夹中，严格来说，如果图片非常大和多，不建议放到 repo 中浪费 GitHub 流量，可以额外找图床。
- js：这个本来不需要有，下一节说。
- 其他：
_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 目录中了。
自定义域名
首先，你要有个域名。然后需要两个步骤：
- 在 GitHub 仓库中
Settings > Pages > Custom domain，配置一个你喜欢的二级域名，当然顶级的也行。例如：ddia.qtmuniao.com - 在你的域名服务提供商的 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
