当用GitBook写文档成为趋势, 是Mkdocs不好用了吗?

在开发过程中总需要写技术文档, 平时学学东西也经常会看笔记或指南一类的电子文档. 因此, 我经常会跟 GitBook 和 Mkdocs 这样的文档工具相遇.

之前在照猫画虎, 模仿 zju-icicles 制作 lib-hfut 的时候, 也有跟 Mkdocs 打过交道. 这一过程在 Mkdocs制作项目说明书 有记录下来, 感兴趣可以去看看.

有一个叫做 readthedocs 的项目/平台会教你怎么样建立自己的文档, 其中有讲到两个工具, Mkdocs 和 Sphinx. 这两个工具其实都挺不错的, Sphinx 应该是亲儿子项目, 不仅位置摆在 Mkdocs 前面, 文档内容也详细许多. 我看他这么希望我用 Sphinx 写文档, 就打算试一试. 结果使用的时候出了点问题, 就跑去用 Mkdocs 了. 最终导致 lib-hfut 除了多做了个自动化上传的脚本之外, 其他跟 zju-icicles 几乎是一模一样.

Mkdocs 夯的不行, 在 GitHub 上有超过 8K 个 Star, GitBook 更是爆炸, 有超过 22K 的 Star(说实话我完全没想到 GitBook 有那么高的人气). 加之很多热门软件的文档也是用 GitBook 生成的, 因此我也想尝试一下. 借着最近都在线上上课, 课本也都在学校里, 干脆边上课边用 markdown 语法记笔记, 然后再用 GitBook 整理成册.

Mkdocs 默认的主题是 readthedocs, 对于我的项目还是比较应景的. 看文档的时候不会被主题影响到, 而且主题自带年代感, 看着有种时光沉淀的味道. 相比之下, GitBook 的默认主题就显得比较有设计感. 纯白色的主题, 简约风的页面, 很迎合当今扁平化的审美趋势.

这是我目前的成果 W3Notepad. W3Notepad 的名字受到了 W3School 的启发. 网站名称里虽有着 “W3”, 但与制定网页WWW标准的万维网联盟 “W3C” 无任何关连。

已经使用了几天也算小有心得, 我并没有兴趣去研究他们的更多的功能, 目前还处在能用就行的阶段 - 托管我的文档, 这就够了. Mkdocs 给的的感觉就是一个工具, 需要一定的技术背景才能够知道他怎么用. 虽然很好用, 但是入门的门槛有点高. 而且他只会帮你由 markdown 文件生成 HTML 代码, 还是需要你自己去 GitHub 或是其他一些地方托管你的代码. 在完成了以上步骤后, 你的文档才能实现托管.

这样的话, 你就得至少掌握

1. markdown 语法
2. 安装 Python
3. pip 命令
4. GitHub 基本操作
5. Git 基本操作

当然了, 用 Mkdocs 跟 GitBook 比并不对等. 拿 readthedocs 跟 GitBook 来比应该比较公平, 只不过 readthedocs 里面的描述实在有够复杂, 我看完 Sphinx 和 Mkdocs 部分的文档就失去了兴趣. 虽然注册了一个 readthedocs 的账号, 但是直到我用 Mkdocs 弄好了托管的文档, 也不知道注册了的账号到底要干嘛. 不过, 我猜可能 readthedocs 应该也有一个类似 GitBook 的网页版本的编辑器, 可以直接对着里面输入.

再来说说 GitBook. 虽然 GitBook 也有 类似 Mkdocs 这样的 gitbook-cli 工具, 但是应该用的人不多, Google 一搜索出来的就是网页版本的编辑器. 随便点了点就大概知道怎么用了, 不出 10min 就把我的笔记全都上传到了 GitBook 上面托管, 使用体验很好.

GitBook 的使用并不需要有高深的技术背景, 只有往格子里面填内容, 最多再配合一些 markdown 语法, 应该也不至于写的太差了. 易用性上, GitBook 是绝对甩 Mkdocs 一条街的.

从托管的角度看, 我觉得两者差不多. Mkdocs 是用 GitHub Page 托管, 而 GitBook 是在自己的网站上托管. 如果硬要比出个高下, 那么 GitBook 还是更简单些. 如果你是在自己的用户仓库下使用 GitBook 而不是在 org 中, 相应的 转换 PDF 或者更多的主题都不能使用. 默认的主题也还行, 几乎全白的极简风, 但是看久了有点审美疲劳.

修改和维护性上, 我觉得 Mkdocs 会好许多. 背靠 GitHub 这样的代码托管平台, 有足够强大的托管技术支持, 维护起来不成问题. GitBook 需要 GitHub 账号注册, 修改文档后也有 Git 的操作, 甚至可以设置仓库作为后端, 这样的话就能在本地进行一些 push 之类的操作, 然后 GitBook 就会自动更新. 不过, 你需要对 GitBookIO 进行权限的授予.

安全角度看来, Mkdocs 肯定是比 GitBook 好的. Mkdocs 只是用了 GitHub 的登录凭证, 而 GitBook 则是拥有了 GitHub 的操作权限, 甚至可以设置在 GitHub 修改自动同步到 GitBook 或是反过来(commit 记录会显示你和 GitBook 共同完成这个变动). 虽然我是不太相信他会做什么坏事, 但是把权限给出去了心里不太踏实.

用图表形式做个小结, 分数总是越高越好.

• GitBook

  Mkdocs

• 轻松入门	5	1
  托管文档	4	4
  修改维护	5	5
  安全	3	5

注: 分数完全主观评判, 除参考外无其他价值.

不过, 我想可能对多数人来说, 一个容易入门的文档工具, 就足够为之倾倒了. 经过这几天的使用, 我认为 GitBook 是一个有良好交互的文档系统, 他很巧妙的把用户不需要关注的东西隐藏了起来, 让人只要关注文档就行了. 虽然我个人会有安全的疑虑, 但是他确识非常好上手, 几乎没有学习成本. 虽然 gitbook-cli 的工具更新不勤, 但是如果设置了仓库为后端, 那么这也不会有任何影响.

这就是我对于为什么更多人在用 GitBook 写文档的观察和揣测. 因为实在没有找到什么的参考内容, 就写写自己的一点想法.