使用Gitbook创建文档并导出PDF

导出PDF的方式有很多种，之前使用过马克飞象的导出功能，不过只是简单的导出并不能添加目录，因为源文件是markdown编写的，经过筛选后采用了gitbook的方式进行编写文档并且使用gitbook pdf .的方式导出为PDF文件。

注意：本机需要有NodeJs环境。

环境准备

想要使用gitbook，那么我们本机需要进行安装，通过npm命令可以很方便的安装。

安装GitBook

通过npm的方式进行安装gitbook环境，命令如下所示：

npm install gitbook -g

安装calibre & ebook-convert

使用gitbook的导出功能，需要第三方插件ebook的支持，下面针对两种不同的操作系统进行配置环境。

Linux系统

下载地址：https://calibre-ebook.com/download_linux

• 下载并安装

  sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

• 配置软链接

  sudo ln -s /usr/bin/nodejs /usr/bin/node

Mac系统

下载地址：https://calibre-ebook.com/download_osx

• 下载并安装

  下载的为dmg文件直接双击安装即可。

• 配置软链接

  sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin

测试安装

安装完成后通过如下命令进行测试是否已经生效。

ebook-convert --version

生成文档

一个新的gitbook文档有两个文件组成，分别是README.md、SUMMARY.md（可自行创建文件夹，在文件夹内创建这两个文件）。

• README.md：关于当前文档的详细描述
• SUMMARY.md：当前文档的目录层级关系配置，通过初始化命令可直接生成markdown文件以及文件夹。

编写Summary

下面是一个示例文档的层级关系：

# Summary

- 第一级目录
  - [第一级目录的子目录](one/first.md)
- 第二级目录
  - [第二级目录的子目录](two/first.md)

GitBook初始化

gitbook内部提供了一个初始化的命令，自动根据SUMMARY.md文件的层级内容生成对应的md文件以及文件夹，执行如下命令：

➜ gitbook-example gitbook init
info: create one/first.md 
info: create two/first.md 
info: create SUMMARY.md 
info: initialization is finished 

控制台的输出信息已经告诉我们成功创建了one/first.md、two/first.md这两个文件。

配置语言

gitbook默认使用的并不是中文汉子，我们需要通过配置book.json文件来修改默认语言方式（book.json文件创建在SUMMARY.md同级目录下）如下所示：

{
    "language": "zh-hans"
}

导出文档

gitbook导出文档的方式有多种，下面简单介绍几种导出的方式。

导出为PDF

在SUMMARY.md文件的同级目录执行gitbook pdf .命令进行导出PDF文件，执行日志如下所示：

➜ gitbook-example gitbook pdf .
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 3 pages 
info: found 0 asset files 
info: >> generation finished with success in 5.7s ! 
info: >> 1 file(s) generated 

如果想要自定义生成的pdf文件名称，可以使用gitbook pdf . ./xxxx.pdf命令。

导出为epub

在SUMMARY.md文件的同级目录执行gitbook epub .命令进行导出epub文件，执行日志如下所示：

➜ gitbook-example gitbook epub .
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 3 pages 
info: found 2 asset files 
info: >> generation finished with success in 2.4s ! 
info: >> 1 file(s) generated 

导出为mobi

在SUMMARY.md文件的同级目录执行gitbook mobi .命令进行导出mobi文件，执行日志如下所示：

➜ gitbook-example gitbook mobi .
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 3 pages 
info: found 3 asset files 
info: >> generation finished with success in 1.9s ! 
info: >> 1 file(s) generated

导出日志查看

如果你在导出过程中遇到了问题，你可以在执行导出命令时添加--log=debug命令参数，这样导出时就可以看到完整的日志信息在控制台输出，如下所示：

➜ gitbook-example gitbook pdf . ./example.pdf --log=debug
debug: readme found at README.md 
debug: summary file found at SUMMARY.md 
debug: cleanup folder "/var/folders/c1/5mrhntb13_zfrnjg4grnf8zr0000gn/T/tmp-2291a4Jd8P8oNX4l" 
......

总结

使用gitbook可以用来编写公司的接口使用文档、项目设计文档等等，功能远不止如此，它还可以通过gitbook build命令来生成静态html文件，可以部署到Nginx、阿里云OSS等静态页面托管的地方。