之前花了将近六个月的时间写了一本书,是一本关于人工智能、深度学习、TensorFlow方面的数,这里先打个广告吧,此处是链接。
这本书我使用了gitbook作为发布平台,同时渲染了很多数学公式(使用了mathjax作为渲染工具)。你可以发现,最后gitbook编译出来的书整体效果是令人满意的。如果使用word来编辑这本书,它本身的工作量就会变得非常大。因此你可以将gitbook理解为一个快速排版、快速发布的写作平台,这样你就可以不用花很多时间和编辑沟通,自己就可以决定出版一本书的节奏。
显然这是出版的一种趋势。
当我第一次接触gitbook时感到非常困难,这是因为gitbook衍生于github,而github主要服务于程序员的圈子。要熟练使用gitbook,你需要掌握下面几个方面预备知识:
现在先来配置开发环境:
gitbook似乎基于javascript,这点我并不是非常清楚,总之需要先安装Node.js。
具体的安装方法可以参考这篇文章
我推荐其中的第一个方法“通过编译后的文件安装”,实质上就是做软链接到可执行文件的环境变量目录下。
跟着那篇文章走就可以顺利安装gitbook了。在Linux和Mac下的安装方法基本一样。请注意装完以后并不会出现gitbook的“图形化界面”,而是在命令行下可以使用
$ gitbook
这里的gitbook命令就是一个编译工具。
也可以参考这个文档,二者配合着看,就能了解整个过程了,后面的命令行建书我遇到一些问题,因此我使用从gitbook上建立项目然后git clone下来的方法编辑。
git就是github的一个工具,由于上传下载文本都需要用到它,因此你也要安装一下git。
具体方法可以google,这里不再赘述。
装完以后就是可以在命令行下使用:
$ git
相关git的操作我这里简单说明一下:
$ git clone
就是将一个开源项目完整地下载到你当前的命令行目录下。
假如这是你自己的项目,并且对项目内的文档做了修改,然后你想把它在回传到你的网上项目:
$ git add . # 添加当前目录下的所有更改
$ git commit -m "这段文字只是作一个记录方便日后查看" # 提交所有更改,并显示和上一个版本有哪些改动
$ git push # 上传改动的部分
然后你的github(或是gitbook)上就存在了一个可回溯的版本
这里推荐这个教程
基本流程就是:
由于这个环节比较慢,有时候你的语法有问题,会导致网上的版本渲染失败,因此可以在本地用gitbook渲染一下看看是否正确:
$ gitbook serve $你的项目名称
上面那个教程里使用的在线编辑,但是在线编辑速度很慢,也不适合编辑有大量文字、图片、公式的markdown文档,因此我推荐直接用markdown文本编辑器处理。
这里推荐两个markdown文本编辑器:
然后就是编辑你想要的文档了。注意使用SUMMARY.md确定你的目录结构,否则gitbook没办法对你的篇章结构进行渲染。
gitbook的强大之处在于你只需要准备好:
然后$ gitbook serve $你的项目
,或是直接push到gitbook项目中去,系统就会自动帮你渲染成一个可读的文档,或是转成pdf文件下载。
我开头提到的那本书大约11W字,300多页,渲染起来也非常地快。
如果你的书中需要渲染数学公式,那么可以使用外部数学公式插件库。有两种公式插件可供使用,但是它们的语法不一样,所以需要做一个选择:
使用方法可以参考这篇文档
其原理是写一个配置文件来配置gitbook,而这个配置文件基于JSON的格式。
如果你想直接上传,那么就只需要建立一个book.json
文件并按照文档里的要求写。如果你想在本地渲染确定一下,那么需要:
$ gitbook install ./
这个命令就是告诉gitbook要安装mathjax
这个插件,会直接安装在项目根目录下。
有时候安装会报错,那可能是因为你的node.js装在了系统目录下,因此需要使用sudo
命令。
然后你就可以开心地使用数学公式表达你的思想啦!
其实也没什么好讲的,幸福的编译总是相同的,不幸的编译却各有各的不幸。我就简单说说我遇到的问题吧。
类似于这样:
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的数学公式的处理量是有限的。
这似乎是一个很玄的问题,以前在别人的页面上也遇到过,可能是因为浏览器性能不足或是网络有问题吧。
我的解决方法是再刷新一次,或是直接,就没有问题了。