此篇文章同时发布在知乎专栏 前端后端客户端,专栏专注于前端、后端、客户端开发的技术分享与探讨,欢迎关注。

Rum 的题解越来越多,原先选择 Gitbook 构建解题本的弊端逐渐显现出来,每次补充一道题解重新 build 项目时居然要花上 30 秒左右……

由于无法忍受 gitbook build 的速度和大量垃圾静态文件,我打算重新构建 Rum,因此有了与 docsify 的邂逅。

docsify 是什么?

官方的介绍是:

A magical documentation site generator.

GitbookVuePress 相同,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 文件配置。

首先配置 loadNavbartrue

<script>
window.$docsify = {
loadNavbar: true
}
</script>
<script src="//unpkg.com/docsify"></script>

./docs 下创建一个 _navbar.md 文件,在该文件中使用 Markdown 格式书写导航:

* 导航1
* [子导航](nav1/child/)
* [导航2](nav2/)

侧边栏

默认情况下,侧边栏会根据当前文章的标题生成目录。但也可以通过 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/)
* [前中后序遍历(DFS)](data-structure/tree/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/)
* [第 122 场周赛](weekly/122/)
* [第 124 场周赛](weekly/124/)
* [第 129 场周赛](weekly/129/)
* [第 130 场周赛](weekly/130/)
* [第 131 场周赛](weekly/131/)
* [第 133 场周赛](weekly/133/)
* [第 134 场周赛](weekly/134/)
* [第 136 场周赛](weekly/136/)
* [第 137 场周赛](weekly/137/)
* [第 138 场周赛](weekly/138/)

插件

代码高亮

使用 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 仓库)。


更多插件见 插件列表

部署到 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,目前我仓库里可见的文档站点几乎都是 Gitbook 搭建的。然而很早开始 Gitbook 团队就专注于 Gitbook 的商业化项目,命令行工具已经被抛弃了……

对比项 docsify Gitbook
是否需要编译
插件 较少
阅读体验 极好(可以调整字体、背景等)
灵活性 较好 较差

其中最大的不同点还是 docsify 是轻量级、无需编译的,而 Gitbook 每次 build 都需要生成一堆 HTML 静态文件,不仅 build 时间长,还污染了我的提交记录……‍🤦‍♂️

而在插件方面,虽然 docsify 插件不如 Gitbook 的丰富,但麻雀虽小五脏俱全,该有的基本也都有,足够使用。

如果再建文档站点,我估计再也不会回去使用 Gitbook 了。

参考资料与扩展阅读