GitBook 简明使用教程

GitBook 简明使用教程

GitBook 是用来创建一个现代化的文档工具。比如经常被用编写系统文档、API 文档、数据库文档等。要使用 GitBook 必须安装 nodejs，以便能够使用 npm 来安装 gitbook。其次还能导出 pdf、epub、mobi 等格式文件。

1 环境安装

1.1 nodejs 安装

由于我们会用到 npm 命令。所以，我们得先安装 nodejs。

大家可以根据自己的系统类型(Windows、Mac)进行对应的安装。这里仅介绍 Windows 版本的 nodejs 安装。

进入官网地址直接下载 Windows 版本的 nodejs 双击安装即可。地址： https://nodejs.org/zh-cn/

验证是否安装成功。

打开 windows 下的命令提示符工具执行如下命令：

C:\Users\Administrator>node -v
v10.16.3

如果正确安装就会得到 node 的版本号。否则会提示：

C:\Users\Administrator>node -v
'node' 不是内部或外部命令，也不是可运行的程序或批处理文件。

1.2 安装 gitbook 库

在 windows 命令提示符窗口执行如下命令：

C:\Users\Administrator>npm install gitbook-cli -g

安装成功之后，再执行如下命令确认是否安装成功。

C:\Users\Administrator>gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

-V 是大写的字母 V。

有些教程会在安装的时候命令是：npm install gitbook -g。注意少了 gitbook 后面少了 gitbook-cli。这样运行 gitbook -V 命令的时候失提示要安装 gitbook-cli。

1.3 安装 ebook-convert 以及 calibre

gitbook 可以将我们写的电子书或文档导出为 PDF、ePub、Mobi 等格式。而导出这三种格式又依赖 npm 的 ebook-convert 库。

而在 windows 下，ebook-convert 库又依赖 calibre 软件提供的库。所以，我们要安装这两个东西。

**1.3.1 安装 ebook-convert **

在 windows 命令提示符执行如下命令安装：npm install ebook-convert -g。

C:\Users\Administrator>npm install ebook-convert -g

验证安装成功与否。

在 windows 命令提示符执行如下命令：ebook-convert --version。

C:\Users\Administrator>ebook-convert --version
ebook-convert.exe (calibre 4.2.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>

1.3.2 安装 Calibre 软件

去官网找对应系统的下载。官网下载地址： https://calibre-ebook.com/download 。

注意：如果 windows 系统是 64 位，请下载 windows 64 版本的 Calibre。

Windows 下载安装没有特别之后，直接下一步下一步就完成了安装。

安装成功之后还不行。

必须把 Calibre 所在的安装目录添加到系统环境变量 PATH 中。

我的 Calibre 安装目录是： C:\Program Files (x86)\Calibre2 。所以，我把该路径添加到了系统环境变量 PATH 中。至于怎样添加请自行在网上搜索"windows 环境变量添加"。win7 与 win8 操作方式小不同。这里就不做多余说明。

很多人只安装了 ebook-convert 命令，而忘记安装 Calibre 软件，导致导出报错。另外还就有安装之后未添加到系统环境变量。

关于怎样导出 PDF、ePub、Mobi 格式文件。将会后面讲解。

2 创建电子书

在创建电子书文档时，我们先看一个创建好的示例运行效果。

1111.png

这种结构形式完全是像一本书呈现出来。我们可以用它存放我们的系统设计、API 文档、数据库文档等系列文档。

2.1 先睹为快

为了快速感受 GitBook 带来的魅力，我们来快速搭建体验一下。

在系统任何位置创建一个目录。如：gitbook-test。然后运行 gitbook init 初始化电子目录。然后执行 gitbook serve 启动一个 Web 服务运行该电子书。

E:\gitbook>mkdir gitbook-test

E:\gitbook>cd gitbook-test

E:\gitbook\gitbook-test>gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

E:\gitbook\gitbook-test>gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
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 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.3s !

Starting server ...
Serving book on http://localhost:4000

以上就是我快捷创建一本书电子书的全过程。此时，我们已经启动了一个 Web 服务，可以在浏览器直接访问这本电子书了。

浏览器输入：http://localhost:4000

2222.png

剩下的事情就是我们来编辑这本书里面的内容了：书目录、内容、友情链接等。

2.2 目录结构

通过上一小节我们快捷创建了一个电子书的项目。通过 gitbook init 命令我们产生两个非常关键的文件：

README.md
SUMMARY.md

README.md 它是我们通过浏览器访问电子书时默认显示的首页。是这本电子书的开篇介绍部分。这是相当重要的。请认真妥善对待它。

SUMMARY.md 这个文件它决定了我们左侧的目录结构。所以，这个文件也是相当的重要。

SUMMARY.md 文件的初始内容为如下：

# Summary

* [Introduction](README.md)

我在上面部分演示了自己的创建的电子书。看看我的 SUMMARY.md 是怎样编写的。

# Summary

* [介绍](README.md)
* [第 1 章：Session 分布式存储](chapter-1/README.md)
  * [1.1 Session 基础](chapter-1/basics.md)
* [第 2 章：队列](chapter-2/README.md)
  * [2.1 Redis](chapter-2/redis.md)
  * [2.2 Kafka](chapter-2/kafka.md)
  * [2.3 RabbitMQ](chapter-2/rabbitmq.md)
* [第 3 章：锁](chapter-3/README.md)
  * [3.1 文件锁](chapter-3/file.md)
  * [3.2 MySQL 锁](chapter-3/mysql.md)
  * [3.3 Redis 锁](chapter-3/redis.md)
* [第 4 章：PHP CLI](chapter-4/README.md)
* [第 5 章：守护进程](chapter-5/README.md)
* [第 6 章：Supervisor 管理守护进程](chapter-6/README.md)
* [第 7 章：PHP 多进程](chapter-7/README.md)
* [第 8 章：Composer 基础](chapter-8/README.md)
* [第 9 章：Composer 包开发](chapter-9/README.md)
* [第 10 章：PHP C 扩展安装](chapter-10/README.md)
* [第 11 章：Web Api 设计](chapter-11/README.md)
* [第 12 章：Postman 使用](chapter-12/README.md)
* [第 13 章：PHPunit 单元测试](chapter-13/README.md)
* [第 14 章：PHP 加密技术](chapter-14/README.md)
* [第 15 章：PHP 常量功能案例](chapter-15/README.md)

---

* [第 16 章：PHP-FPM](chapter-16/README.md)
* [第 17 章：Nginx](chapter-17/README.md)
* [第 18 章：Linux](chapter-18/README.md)
* [第 19 章：MySQL](chapter-19/README.md)
* [第 20 章：Web 安全](chapter-20/README.md)
* [第 21 章：HTTP 协议](chapter-21/README.md)
* [第 22 章：Git+GitHub+GitBook](chapter-22/README.md)

通过我给出的示例，其实已经说明了很多事情。

2.2.1 多级目录

书的目录并不只有一级。也会存在二级三级甚至多级的情况。那么怎样让电子书呈现多级呢？

我对 SUMMARY.md 文件进行了更改。如下：

# Summary

* [开篇介绍](README.md)
* [第一级](README.md)
  * [第二级-2.1](README.md)
  * [第二级-2.2](README.md)
    * [第三级-3.1](README.md)

此时我们再去浏览器刷新查看文档目录结果变成了如下图所示：

3333.png

我们可以得出结论：多级目录实际上是通过缩进方式来进行区分实现的。

2.2.1 文章内容

上面的目录结果还有一个问题我们忽略了。所有的目录都指向同一个 README.md。这是不合适的。所以，在编写文章的时候，请每个目录一个 markdown 文件。这里就不做细说。很容易看明白。

2.3 目录折叠

通过上面演示的示例，大家一定发现了一个问题：目录层级越来越多之后，目录的滚动查看就越来越不方便。那么应该怎样折叠呢？

目录折叠 gitbook 默认没提供这样的功能。但是，可以通过安装配套的 gitbook 插件来实现。也是相当简单的。

在根目录下创建一个 book.json 的文件。该文件主要是对电子书的各种属性进行配置。

book.json 主要功能：

• 配置电子书名称
• 配置电子书作者
• 配置电子书描述
• 配置电子书语言各类
• 配置电子书使用的 gitbook 版本
• 自定义电子书样式
• 配置电子书左侧导航友情链接
• 配置插件

本小节目录折叠功能就是靠在 book.json 文件中增加如下配置实现：

{
    "plugins": [ 
        "expandable-chapters"
    ]
}

现在我们在 book.json 当中配置成功之后还不能生效。我们必须执行 gitbook install 命令安装。

E:\gitbook\gitbook-lamphp>gitbook install
info: installing 1 plugins using npm@3.9.2
info:
info: installing plugin "expandable-chapters"
info: install plugin "expandable-chapters" (*) from NPM with version 0.2.0
info: >> plugin "expandable-chapters" installed with success

因为我已经安装了的缘故，所以会提示我该插件已经安装了。

此时我们再通过 gitbook serve 启动 Web 服务再去访问。发现之前展示的导航全部折叠了。

2.4 分隔符

当我们折叠的目录太多的时候。我们肯定会希望把一组功能相关的功能导航通过分隔符以示区分。实现这个简单。只需要在 SUMMARY.md 文件当中对导航如下设置即可。

示例:

......
* [第 13 章：PHPunit 单元测试](chapter-13/README.md)
* [第 14 章：PHP 加密技术](chapter-14/README.md)
* [第 15 章：PHP 常量功能案例](chapter-15/README.md)

---

* [第 16 章：PHP-FPM](chapter-16/README.md)
* [第 17 章：Nginx](chapter-17/README.md)
......

对！就这么简单。只需要 --- 三个减号符号即可搞定。

2.5 友情链接

友情链接也是一个非常重要的功能。不管是推广自己的网站还是合作伙伴的网站。这个功能都非常棒。

它也是通过 book.json 文件来实现的。

在 book.json 中增加如下配置：

{
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.6 设置书名

书名或文档名称。也是通过 book.json 实现。

示例如下：

{
    "title": "《PHP 向前冲》",
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.7 设置作者/描述/语言/版本

也是通过 book.json 来实现。以下示例配置一看就明白。勿须多做说明。

{
    "title": "《PHP 向前冲》",
    "author": "fingerQin",
    "description": "一本集作者十年开发经验的 PHP 电子书",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.8 自定义样式

每个人都有自己对美的定义。gitbook 默认的文档样式可能对很多有着更高追求的人来说可能还需要优化。我们的 gitbook 也考虑到这种情况，提供了一种自定义样式的机制让你可以随心所欲制定自己外观。

{
    "title": "《PHP 向前冲》",
    "author": "fingerQin",
    "description": "一本集作者十年开发经验的 PHP 电子书",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

在上面的配置当中，我们增加了如下配置：

......
"styles": {
        "website": "./styles/website.css"
    }
......

3 插件

除了样式可以定制，我们还可以通过插件的形式定制更多的功能。GitBook 默认提供 highlight、search、sharing、fontsettings、livereload 5 个插件。

• highlight 代码高亮插件。
• search 搜索插件。就是左侧菜单顶部的搜索功能。
• sharing 社会化分享工具。
• fontsettings 文章内容字符设置插件。如文字大小、字体、背景颜色设置。
• livereload 内容扫更新。如果不使用此插件则内容更新每次都要重启 Web 服务才能看到变化内容。

4444.png

3.1 插件使用

插件使用非常简单。只需要在 book.json 的 plugins 小节配置即可。如下所示：

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search"
    ]
    ......
}

注：GitBook 默认的插件即使不在此处配置也是生效的。

3.2 插件配置

所谓插件配置是指当我们要使用一个插件的时候，此插件可能提供了一些高级功能的配置。所以，此时我们需要配置这些参数，则需要通过 plugins-configs 来控制。

我们以配置 sharing 默认插件的分享平台开关为例：

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search",
        "sharing"
    ],
    "pluginsConfig": {
        "sharing": {
            "facebook" : true,
            "weibo" : false
        }
    }
    ......
}

如果对插件的配置不是特别清楚，可以查看文档： https://www.npmjs.com/package/gitbook-plugin-sharing-plus

在这里可以找到所有插件对应的文档。

3.3 插件禁用

我们安装了各种各校的插件。有时候我们不需要某个插件的时候，可以禁用插件生效。禁用插件也非常简单。

禁用分享插件示例：

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search",
        "-sharing"
    ]
    ......
}

没错。就是在插件名字前面加一个减号"-"即可对插件禁用。

3.4 常用插件

默认提供的 5 个插件固然很优秀。但是，我们还是希望拥有更多的功能。

3.4.1 捐赠

可以说这个插件是非常常见的功能了。

插件名称：donate

插件地址： https://www.npmjs.com/package/gitbook-plugin-donate

book.json 配置：

{
    ......
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "微信捐赠二维码图片地址",
          "alipay": "支付宝捐赠二维码图片地址",
          "title": "捐赠",
          "button": "默认值：Donate",
          "alipayText": "默认值：支付宝捐赠",
          "wechatText": "默认值：微信捐赠"
        }
    }
    ......
}

记住，配置好之后，要执行 gitbook install 安装这个插件。否则，这个插件不生效且可能会报错。

3.4.2 导航目录折叠

在本文档 2.3 小节我们已经介绍过了。这里不多做介绍。

插件名称：expandable-chapters

插件地址： https://www.npmjs.com/package/gitbook-plugin-expandable-chapters

3.4.3 回到顶部

当一个页面内容太多的时候。回到顶部这样一个小且实用的功能是非常棒的。

插件名称：back-to-top-button

插件地址： https://www.npmjs.com/package/gitbook-plugin-back-to-top-button

{
    "plugins" : [ "back-to-top-button" ]
}

使用比较简单，直接在 plugins 中增加 back-to-top-button 并通过 gitbook install 安装这个插件即可生效。

3.4.4 内页生成导航

当我们一个内页内容非常多的时候。此时如果能在内页起始就能查阅当前的内页目录提供检索，那是相当的棒。

插件名称：page-treeview

插件地址： https://www.npmjs.com/package/gitbook-plugin-page-treeview

{
    "plugins" : [ "page-treeview" ]
}

使用比较简单，直接在 plugins 中增加 page-treeview 并通过 gitbook install 安装这个插件即可生效。

由于常用且实用的插件很多。这里仅作抛砖引玉。更多更优秀的插件等着大家去发掘。

4 导出

导出功能可谓非常强大。gitbook 支持导出 pdf、epub、mobi、html静态网站等。

在环境安装一小节，我们已经安装了 ebook-convert 插件以及 calibre 软件。所以，这里不再对这两个东西的安装进行过多说明。

4.1 导出 PDF

导出 PDF 非常容易。打开 windows 命令行提示符，在电子书根目录执行命令：gitbook pdf

E:\gitbook>gitbook pdf

直接回车慢慢等待即可。执行成功会在当前目录下生成一个 pdf 文件。

不过我在 windows 下运行的时候会出现工具内部代码报错的异常。这可能与平台工具有很大关系。

4.2 导出 ePub

与 PDF 一样依然很简单。打开 windows 命令提示符，在电子书根目录执行命令：gitbook epub

E:\gitbook>gitbook epub
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 42 asset files
info: >> generation finished with success in 2.6s !
info: >> 1 file(s) generatedE:\gitbook>gitbook epub

命令运行成功会在根目录生成一个 book.epub 格式的文件。

4.3 导出 mobi

与 PDF 一样依然很简单。打开 windows 命令提示符，在电子书根目录执行命令：gitbook mobi

E:\gitbook>gitbook mobi
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 43 asset files
info: >> generation finished with success in 3.0s !
info: >> 1 file(s) generated

命令运行成功会在根目录生成一个 book.mobi 格式的文件。

mobi 格式是亚马逊 kindle 的电子书格式。可以直接发送到 kindle 设备阅读。

4.4 导出 HTML

非常简单。如下所示：

E:\gitbook>gitbook build
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 44 asset files
info: >> generation finished with success in 1.6s !

会在当前目录下的 _book 文件夹下生成一堆的 HTML。就可以打包成各种各样的格式分享出去。比如，打包成 CHM 格式的文件。