使用gitbook和mkdocs写文档

我的博客是使用hexo生成的, 这是一款基于Node.js的静态博客框架, 他可以帮助像我一样对前端一无所知的人快速搭建一个看上去有模有样的博客, 而我只需要会用markdown写博文就行. 同样, 在开发过程中总会有写技术文档的需要, 因此也就有了gitbook和mkdocs这样的工具.

gitbook和mkdocs的定位其实应该不太一样, gitbook的初衷是让人使用markdown快速写书(也就包括文档), 而mkdocs则是帮助技术人员快速撰写及形成一个可修改性好的文档. 不过到了我这种菜鸡手里…基本的够能都比较类似, 也就没有太大的区别了…

gitbook

gitbook-cli是基于Node.js的工具, 可通过npm安装: npm install gitbook-cli. 需要注意的是, 由于gitbook项目组方向的调整, 这个命令行工具已经不再更新了. 不过基本的功能也差不多了, 继续用似乎也没啥问题…

安装完成之后就可以使用gitbook命令创建和编写文档, 创建命令是gitbook init, 目录下会产生README.md和SUMMARY.md两个文件, 其中SUMMARY.md是整个文档的目录文件兼结构文件, gitbook-cli会根据这个文件的内容生成最后的文档. SUMMARY.md本身也是个markdown文件:

# 第一章
* [文档说明](README.md)
* [第一部分](Part1/README.md)
    * [内容1](Part1/content1.md)
        * [内容小标题](Part1/content1.md)
# 第二章
* [XXXX](NNNN.md)

首先书的章节由一级标题的语法(#)控制, 不同章节的内容在目录树里会用分隔线分开, 如果开启自动序号的话, 不同章节的小序号也会不一样.

章节里面以无序列表的形式保存目录结构, 每一级列表项目都使用链接的语法([]())链接到具体的markdown文件. 具体的markdown文件内可以以一级标题作为锚点. 目前实测只有一级标题有锚点的作用, 如果想要锚定二级标题或其他内容则要手动添加html tag作为锚点.

gitbook支持所有的基本markdown语法, 同时也支持html, 因此如果需要在文档中加入比较复杂的表格, 可以写成html的格式的然后直接贴入.

基本上知道这些就能够写书了. 如果对文档的表现或者使用的插件有要求, 可以自行建立book.json配置文件, 在其中按格式填写配置信息, 即可在生成书籍的时候作调整.

书籍在写作完成后可以使用gitbook serve开启本地的书籍预览, 默认端口8000. 预览服务可以一直保持开启, 对markdown源文件进行的修改会实时反映在预览网页内(可能需要刷新). 当然如果确定写的书没有问题, 可以直接使用gitbook build, 创建好的html书籍会保存在_book/内.

mkdocs

mkdocs是基于python的工具, 使用pip或者conda都可以方便的安装. 安装完后mkdocs命令即可使用, 创建文档的命令是mkdocs new proj_name, 运行后会在名为proj_name/的文件夹内建立mkdocs.yml文件和docs/文件夹. 其中mkdocs.yml是配置文件兼目录结构文件, 采用yaml格式进行记录. 文件大概是这样:

site_name: "我的文档"

pages:
- 目录: index.md
- 第一章: chapter1.md
- 第二章: chapter2.md

theme: readthedocs

mkdocs形成的目录基本等同于常见的markdown TOC, 不需要像gitbook一样去做额外的锚点设置. 然后由于我这次使用mkdocs写的文件比较简单, 对于其更多的功能没有涉及.

编写完成的文档可以通过mkdocs serve预览, 同样会根据markdown源文件实时更新. 也可以通过mkdocs build直接构建, 构建结果会在site/目录中.

两款工具的比较

我这次整理离职文档的过程中两个工具都使用过一次, 也有一些对比使用的体会.

首先从基本功能上, 两个工具对我来说几乎没有区别, 都是用markdown写文档, 然后基本命令都很简单易用, 都可以本地浏览. 不过gitbook-cli毕竟是不更新了, 之后会不会出什么问题我也不知道.

然后从扩展性上来说呢…其实两者也差不多, 都有很多作者在给两个工具写插件. 不过有一点值得注意的是, gitbook似乎没什么第三方主题? 我搜了很多次也没有能够拿来直接用的主题, 而mkdocs内置的就有好几个了.

另外由于本次的是工作交接用的文档, 我的同事其实不太习惯看html的, 因此两个工具的第三方pdf导出插件我都用了…怎么说呢…能用…但是确实不是那么好用吧…跟html的效果比起来两个的pdf都显得比较砢碜了…不过硬要说的话mkdocs的稍微好一些.