工具安利 | docsify 入坑指南与我放弃 Gitbook 的那些理由
工具安利 | docsify 入坑指南与我放弃 Gitbook 的那些理由
- docsify 是什么？
- 快速开始
- 安装
- 初始化
- 预览
- 路由说明
- 导航与侧边栏配置
- 导航栏
- 侧边栏
- 插件
- 代码高亮
- 部署到 Github Pages
- 与 Gitbook 体验对比
leetcode-notebook[1] 的题解越来越多，原先选择 Gitbook[2] 构建解题本的弊端逐渐显现出来，每次补充一道题解重新 build 项目时居然要花上 30 秒左右……
由于无法忍受 gitbook build 的速度和大量垃圾静态文件，我打算重新构建项目，因此有了与 docsify[3] 的邂逅。
docsify 是什么？
官方的介绍是：
A magical documentation site generator.
与 Gitbook 和 VuePress[4] 相同，docsify 是一个文档站点生成器。至于它究竟 magic 在何处，我将在后面说到。
快速开始
安装
首先全局安装 docsify-cli：
npm i docsify-cli -g
初始化
假设我们要在 ./docs 子目录中编写文档，将该目录初始化：
docsify init ./docs
初始化后系统帮我们生成了一个 ./docs 目录，目录中包含以下文件：
index.html：入口文件README.md：将作为主页渲染.nojekyll：阻止 Github Pages 忽略以下划线开头的文件
预览
使用以下命令启动本地服务器：
docsify serve docs
路由说明
页面路由和文件夹的对应关系如下：
docs/README.md => http://domain.com
docs/guide.md => http://domain.com/guide
docs/zh-cn/README.md => http://domain.com/zh-cn/
docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
导航与侧边栏配置
导航栏
简单导航栏
简单的导航栏可以在 index.html 文件中直接定义：
<body>
<nav>
<a href="#/">LeetCode 题解</a>
<a href="http://jalan.space" target="_blank">我的博客</a>
</nav>
<div id="app"></div>
</body>
复杂导航
复杂导航可以通过 Markdown 文件配置。
首先配置 loadNavbar 为 true：
<script>
window.$docsify = {
loadNavbar: true
}
</script>
<script src="//unpkg.com/docsify"></script>
在 ./docs 下创建一个 _navbar.md 文件，在该文件中使用 Markdown 格式书写导航：
- 导航 1
- [子导航](nav1/child/ "子导航")
- [导航 2](nav2/ "导航2")
侧边栏
默认情况下，侧边栏会根据当前文章的标题生成目录。但也可以通过 Markdown 文档生成。
首先配置 loadSidebar 选项为 true：
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//unpkg.com/docsify"></script>
然后在 ./docs 下创建 _sidebar.md 文件：
- [简介](/ "简介")
- 数据结构
- [数组](data-structure/array/ "数组")
- [字符串](data-structure/string/ "字符串")
- [链表](data-structure/linked_list/ "链表")
- 树
- [递归](data-structure/tree/recursion/ "递归")
- [层次遍历（BFS）](data-structure/tree/bfs/ "层次遍历（BFS）")
- [前中后序遍历（DFS）](data-structure/tree/dfs/ "前中后序遍历（DFS）")
- [其他](data-structure/tree/other/ "其他")
- [堆](data-structure/heap/ "堆")
- [栈](data-structure/stack/ "栈")
- [哈希表](data-structure/hash/ "哈希表")
- 算法思想
- 排序
- [堆排序](algorithm/sort/heap/ "堆排序")
- [快速排序](algorithm/sort/quick/ "快速排序")
- [冒泡排序](algorithm/sort/bubble/ "冒泡排序")
- [其他](algorithm/sort/other/ "其他")
- 搜索
- [深度优先](algorithm/research/dfs/ "深度优先")
- [广度优先](algorithm/research/bfs/ "广度优先")
- [二分查找](algorithm/research/binary-search/ "二分查找")
- [动态规划](algorithm/dynamic/ "动态规划")
- [贪心](algorithm/greedy/ "贪心")
- [位运算](algorithm/bit/ "位运算")
- [数学题](algorithm/math/ "数学题")
- [其他](algorithm/other/ "其他")
- 周赛
- [第 121 场周赛](weekly/121/ "第 121 场周赛")
- [第 122 场周赛](weekly/122/ "第 122 场周赛")
插件
代码高亮
使用 Prism 作为代码高亮插件，可以在 index.html 中这样配置：
<script src="//unpkg.com/docsify"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.js"></script>
注意这里引入的文件，如果你要高亮 Python 代码，那么就要引入：
<script src="//unpkg.com/prismjs/components/prism-python.js"></script>
对不同语言的高亮支持可见 Prism 仓库[5]。
更多插件见 插件列表[6]。
部署到 Github Pages
我的 Github Pages 读取的是 gh-pages 分支下的代码，因此我要把 ./docs 下的文件上传到 gh-pages 分支上，完整的代码则上传的到 master 分支。
为了方便更新，我在项目根目录下放置了一个用于推送代码的脚本 push.sh：
message=$1
# 复制 README.md
cp README.md docs/README.md
# 更新 master
git add .
git commit -m "$message"
git push -f git@github.com:JalanJiang/leetcode-notebook.git master
# 更新 gh-pages
cd docs/
git init
git add -A
git commit -m "$message"
git push -f git@github.com:JalanJiang/leetcode-notebook.git master:gh-pages
与 Gitbook 体验对比
初次搭建这一类文档站点使用的是 Gitbook， 之前写过一篇 搭建 GitBook 并托管到 git pages[7]，目前我仓库里可见的文档站点几乎都是 Gitbook 搭建的。然而很早开始 Gitbook 团队就专注于 Gitbook 的商业化项目，命令行工具已经被抛弃了……
对比项 | docsify | Gitbook |
|---|---|---|
是否需要编译 | 否 | 是 |
插件 | 较少 | 多 |
阅读体验 | 好 | 极好 |
灵活性 | 较好 | 较差 |
其中最大的不同点还是 docsify 是轻量级、无需编译的，而 Gitbook 每次 build 都需要生成一堆 HTML 静态文件，不仅 build 时间长，还污染了我的提交记录……?♂️
而在插件方面，虽然 docsify 插件不如 Gitbook 的丰富，但麻雀虽小五脏俱全，该有的基本也都有，足够使用。
如果再建文档站点，我估计再也不会回去使用 Gitbook 了。
参考资料
[1]
leetcode-notebook: https://github.com/JalanJiang/leetcode-notebook
[2]
Gitbook: https://www.gitbook.com/
[3]
docsify: https://docsify.js.org/#/
[4]
VuePress: https://github.com/vuejs/vuepress
[5]
Prism 仓库: https://github.com/PrismJS/prism
[6]
插件列表: https://docsify.js.org/#/plugins
[7]
搭建 GitBook 并托管到 git pages: http://jalan.space/2018/04/22/2018/2018-04-22-gitbook-and-git-pages/