《DDIA 逐章精读》小册

520 阅读4分钟

引子

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

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

这里简单记录下过程,希望能够帮到想写“小册”、“文档”并做成网页的同学,顺便推广下 DDIA 分享文字稿集结而成的——《DDIA 逐章精读》小册: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.io1 小时

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

小结

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

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

题图故事

北海公园的鸳鸯

参考资料

[1] DDIA 读书会: docs.qq.com/sheet/DWHFz…

[2] 分布式点滴: www.zhihu.com/column/lear…

[3] 我的博客: www.qtmuniao.com/

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

[5] DDIA 翻译: github.com/Vonng/ddia

[6] docsify 官方文档: docsify.js.org/

[7] DDIA 逐章精读小册: ddia.qtmuniao.com/

[8] DDIA 逐章精读 repo: github.com/DistSysCorp…

[9] DDIA 逐章分享: ddia.qtmuniao.com/

[10] DDIA 读书小记: ddia.qtmuniao.com/#/preface