使用gitbook发表文章和书的正确姿势

使用gitbook的正确姿势

之前花了将近六个月的时间写了一本书，是一本关于人工智能、深度学习、TensorFlow方面的数，这里先打个广告吧，此处是链接。



这本书我使用了gitbook作为发布平台，同时渲染了很多数学公式（使用了mathjax作为渲染工具）。你可以发现，最后gitbook编译出来的书整体效果是令人满意的。如果使用word来编辑这本书，它本身的工作量就会变得非常大。因此你可以将gitbook理解为一个快速排版、快速发布的写作平台，这样你就可以不用花很多时间和编辑沟通，自己就可以决定出版一本书的节奏。

显然这是出版的一种趋势。

1. 配置环境

当我第一次接触gitbook时感到非常困难，这是因为gitbook衍生于github，而github主要服务于程序员的圈子。要熟练使用gitbook，你需要掌握下面几个方面预备知识：

markdown语法。markdown是一种文本渲染语法，具体可以google补全这部分知识，在这里我就不详述了。顺便也在这里推荐这种语法，我觉得它比word编辑文档更有效率，适合经常需要写作或是要写书的朋友。

基本的编译原理。学会了markdown语法之后，你会用这种语法编辑你自己的书，产生一个或多个文本文档。然后gitbook会将这个文档编译成机器语言，因此你还需要简单知道一点计算机编译的原理（我可以向你保证，这并不难）。如果使用过LaTex的朋友就会了解其中的诀窍。

github的使用方法。由于gitbook源于github，而github是一个倡导开源的代码版本管理平台，简单的说就是将你的代码开源给别人，让包括自己和他人共同修改你上传的代码（gitbook将你的书视为代码）。因此你在写作的时候并不需要一次性地将整本书写好，然后一口气上传，而是写一点、上传更新一点，也可以通过gitbook回溯到之前的某个版本（将gitbook视为一个版本控制器），所以程序员接触gitbook会更快一些。

命令行的操作。到目前为止我对Windows的命令行依然生疏，所以我只介绍在一般Linux和Mac下的命令行操作方法。命令行可以让你高效的进行文件系统管理，如果用惯了Windows的图形化操作界面，可能一下子会有一点不太适应，但当你逐渐变得专业以后，就知道如果做出取舍了。

现在先来配置开发环境：

1.1 安装Node.js和gitbook

gitbook似乎基于javascript，这点我并不是非常清楚，总之需要先安装Node.js。

具体的安装方法可以参考这篇文章

我推荐其中的第一个方法“通过编译后的文件安装”，实质上就是做软链接到可执行文件的环境变量目录下。

跟着那篇文章走就可以顺利安装gitbook了。在Linux和Mac下的安装方法基本一样。请注意装完以后并不会出现gitbook的“图形化界面”，而是在命令行下可以使用

$ gitbook

这里的gitbook命令就是一个编译工具。

也可以参考这个文档，二者配合着看，就能了解整个过程了，后面的命令行建书我遇到一些问题，因此我使用从gitbook上建立项目然后git clone下来的方法编辑。

1.2 安装git

git就是github的一个工具，由于上传下载文本都需要用到它，因此你也要安装一下git。

具体方法可以google，这里不再赘述。

装完以后就是可以在命令行下使用：

$ git

相关git的操作我这里简单说明一下：

$ git clone

就是将一个开源项目完整地下载到你当前的命令行目录下。

假如这是你自己的项目，并且对项目内的文档做了修改，然后你想把它在回传到你的网上项目：

$ git add .  # 添加当前目录下的所有更改
$ git commit -m "这段文字只是作一个记录方便日后查看" # 提交所有更改，并显示和上一个版本有哪些改动
$ git push # 上传改动的部分

然后你的github（或是gitbook）上就存在了一个可回溯的版本

2. 写书

2.1 创建并编辑你的文档

这里推荐这个教程

基本流程就是：

在gitbook上注册一个账户

建立一个项目（也就是一本书）

git clone这个项目

用文本编辑器编辑你的项目文档

用git上传你编辑的内容

去gitbook上看一看，是不是正确渲染好了

由于这个环节比较慢，有时候你的语法有问题，会导致网上的版本渲染失败，因此可以在本地用gitbook渲染一下看看是否正确：

$ gitbook serve $你的项目名称

2.2 更新你的文档

上面那个教程里使用的在线编辑，但是在线编辑速度很慢，也不适合编辑有大量文字、图片、公式的markdown文档，因此我推荐直接用markdown文本编辑器处理。

这里推荐两个markdown文本编辑器：

Typora。这个编辑器很强大，Linux、Mac、Windows通用，而且免费

MWeb。也是一个很强大的编辑器，只能在mac和ios平台上使用，需要付费。这篇文章就是用MWeb写的。

然后就是编辑你想要的文档了。注意使用SUMMARY.md确定你的目录结构，否则gitbook没办法对你的篇章结构进行渲染。

gitbook的强大之处在于你只需要准备好：

README.md 作为开头介绍页

SUMMARY.md 作为篇章结构和链接到的具体篇章markdown文档

写好篇章里的结构

如果篇章结构里有图，就直接在项目里面建文件夹进行管理

然后

$ gitbook serve $你的项目

，或是直接push到gitbook项目中去，系统就会自动帮你渲染成一个可读的文档，或是转成pdf文件下载。

我开头提到的那本书大约11W字，300多页，渲染起来也非常地快。

2.3 使用MathJax渲染数学公式

如果你的书中需要渲染数学公式，那么可以使用外部数学公式插件库。有两种公式插件可供使用，但是它们的语法不一样，所以需要做一个选择：

Mathjax。我目前使用的插件，语法和LaTex相差无几

KaTeX。号称”最快“的公式渲染库，目前还没有研究过

使用方法可以参考这篇文档

其原理是写一个配置文件来配置gitbook，而这个配置文件基于JSON的格式。

如果你想直接上传，那么就只需要建立一个

book.json

文件并按照文档里的要求写。如果你想在本地渲染确定一下，那么需要：

$ gitbook install ./

这个命令就是告诉gitbook要安装

mathjax

这个插件，会直接安装在项目根目录下。

有时候安装会报错，那可能是因为你的node.js装在了系统目录下，因此需要使用

sudo

命令。

然后你就可以开心地使用数学公式表达你的思想啦！

3. 各种杂乱无章的Debug

其实也没什么好讲的，幸福的编译总是相同的，不幸的编译却各有各的不幸。我就简单说说我遇到的问题吧。

也许是我的书中使用的数学公式太多了，系统报错：RangeError: Maximum call stack size exceeded

类似于这样：

gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: loading book configuration....OK
info: load plugin gitbook-plugin-highlight ....OK
info: load plugin gitbook-plugin-search ....OK
info: load plugin gitbook-plugin-sharing ....OK
info: load plugin gitbook-plugin-fontsettings ....OK
info: load plugin gitbook-plugin-livereload ....OK
info: >> 5 plugins loaded
info: start generation with website generator
info: clean website generator
info: OK

RangeError: Maximum call stack size exceeded

最终问题仍然没有从本质上解决，我参考了这篇回答，里面的方法都试过了，还是不行。

最后就是用了非常SB的办法：将一章的内容分割成多个章，然后就可以了。可以确定的是，在每一章中，gitbook对mathjax的数学公式的处理量是有限的。

第一次打开页面的时候，公式或是没有正确渲染，或是不显示

这似乎是一个很玄的问题，以前在别人的页面上也遇到过，可能是因为浏览器性能不足或是网络有问题吧。

我的解决方法是再刷新一次，或是直接翻墙，就没有问题了。