在Ubuntu上使用GitBook（20200419更新）

在Ubuntu上使用GitBook

GitBook简介

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书，GitBook 并非关于 Git 的教程。
GitBook支持输出多种文档格式：
·静态站点：GitBook默认输出该种格式，生成的静态站点可直接托管搭载Github Pages服务上；
·PDF：需要安装gitbook-pdf依赖；
·eBook：需要安装ebook-convert；
· 单HTML网页：支持将内容输出为单页的HTML，不过一般用在将电子书格式转换为PDF或eBook的中间过程；
·JSON：一般用于电子书的调试或元数据提取。

Gitbook优于latex之处：

• 要把一个写了很多个md的项目编辑成一本书，而且要输出pdf
• 书的内容包含很多代码
• 这本书要放到线上，比如readthedoc

Gitbook支持公式：

• 只能通过html的katex引擎支持公式。

安装

在此，我们实现的效果是：在本地配置GitBook工具，并能够以HTML和PDF等格式生成书籍。
以下的每一步都可能相当耗时。要有耐心。

依赖工具nodejs的安装¹

0.安装软件之前先把软件包升级到最新

sudo apt-get update
sudo apt-get upgrade

1.安装nodejs和npm

sudo apt-get install nodejs
sudo apt-get install npm

2.升级nodejs和npm

sudo npm install npm -g
sudo npm install –g n stable

如果不行的话去掉参数-g，如果还不行的话改成sudo npm install n
3.npm镜像替换为淘宝镜像

sudo npm get registry # 得到原本的镜像地址，输出https://registry.npmjs.org/
sudo npm config set registry http://registry.npm.taobao.org/ # 设成淘宝镜像

4.（选）安装cnpm
因为npm安装插件是从国外服务器下载，受网络影响大，可能出现异常，所以可以用基于中国镜像的cnpm代替npm.

sudo npm install cnpm -g --registry=https://registry.npm.taobao.org

注意：安装完后最好查看其版本号cnpm -v或关闭命令提示符重新打开，安装完直接使用有可能会出现错误

依赖工具Calibre的安装

sudo apt-get install calibre

GitBook的安装²

sudo npm install -g gitbook-cli
gitbook -V #查看gitbook版本，确定安装成功

使用GitBook

进入空目录后运行

gitbook init

生成README.md和SUMMARY.md，另外建议手动新建其它文件，如下（注意这些文件都要放在主目录下）：

简介：README.md

此文件是简单的电子书介绍，可以把您所制作的电子书做一下简单的描述。语法就是md.

目录：SUMMARY.md

此为电子书的目录文件，语法就是md. 此处建议放全书的目录结构（使用markdown中的“列举+超链接”），这样目录可以起到导航作用。如下所示：

* [简介](README.md)
* [第一章](section1/README.md)
* [第二章](section2/README.md)

词汇表：Glossary.md

对于电子书内容中需要解释的词汇可在此文件中定义。词汇表会被放在电子书末尾。其语法就是md.

书的配置文件：book.json

book.json 是电子书的配置文件，规定了title、description、isbn、language、direction、styles 等。
这里给出一个比较好用的book.json³，稍微改一下里面的参数就可以用，亲测支持汉语、公式，总体来说还是能用的。

{
    "title": "Effective Python 阅读笔记",
    "description": "阅读Effective Python这本书的阅读笔记，汉语",
    "author": "Chong",
    "language": "zh-hans",
    "styles": {
        "website": "style.css"
    },
    "plugins": [
        "-lunr",
        "-livereload",
        "-sharing",
        "katex", 
        "advanced-emoji",
        "include-codeblock", 
        "mermaid",
        "yahei",
        "anchor-navigation-ex",
        "theme-api",
        "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "theme-api": { "theme": "light" },
        "tbfed-pagefooter": {
            "copyright": "© Chong",
            "modify_label": " Modified At: ",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "fontSettings": {
            "theme": "white",
            "family": "msyh",
            "size": 2
          }
    },
    "pdf": {
        "toc": true,
        "pageNumbers": true,
        "fontSize": 18,
        "paperSize": "a4",
        "margin": {
          "right": 30,
          "left": 30,
          "top": 30,
          "bottom": 50
        }
      }
}

普通章节.md 文件

其他文件必须放在主目录下，而普通章节.md 文件放哪都行，但不要忘了在“SUMMARY.md”文件中引用，否则不包括在书籍内。

电子书封面图片: cover.jpg

GitBook 帮助文档建议封面图片的尺寸为 1800*2360 像素并且遵循建议：没有边框、清晰可见的书本标题、任何重要的文字在小版本中应该可见。
图片的格式为 jpg 格式。把图片重命名为“cover.jpg”放到电子书项目文件夹即可。

生成书籍

上述文件准备齐备之后，首先需要安装书中使用的插件。
安装这些插件，最快的方法是cnpm install gitbook-plugin-*这种方式一个一个安装插件，比如cnpm install gitbook-plugin-include-codeblock。
使用gitbook install ./可以一键安装所有的插件，但是不建议使用，因为很慢。⁴

安装好插件之后，gitbook build生成书籍，然后在主目录/_book/index.html预览效果，或者gitbook serve之后访问http://localhost:4000来预览效果。

之后，通过以下命令生成电子书文件：

gitbook mobi # 生成mobi文件
gitbook pdf # 生成pdf文件

在主目录下会生成相应文件。

扩展阅读

【Gitbook】实用配置及插件介绍

参考

---

1. ubuntu 上安装node.js 的简单方法 ↩︎

2. ubuntu下安装gitbook并生成电子书 ↩︎

3. ubuntu上使用 gitbook 生成 pdf 电子书:解决中文乱码问题 ↩︎

4. GitBook无法显示矩阵/数学公式 ↩︎