文摘  使用GitBook打造在线电子书详解

一、GitBook介绍

GitBook 是一个基于 Node.js 开发的命令行工具，使用它可以很方便的管理电子书，GitBook 是目前最流行的开源书籍写作方案。

除了通过 GitBook 命令行管理电子书外，还可以在线（gitbook.com）或者使用桌面编辑器 Gitbook Editor 来编写和管理电子书。

对于新手来说，我推荐使用 Gitbook Editor 来编写和管理电子书，因为它集成了 GitBook 命令、Markdown 编器和 Git 的功能，内容通过 Git 可与 gitbook.com / Gitlab / GitHub 同步，方便版本管理和团队协作。

可对于程序员或熟悉 Git 和 Markdown 的人，我更推荐使用 GitBook 命令行 + Typora + SourceTree 来编写和管理电子书。使用专业工具做专业的事，比 Gitbook Editor 高效很多。

官网：https://www.gitbook.com 

GitBook 的功能：

· 支持 Markdown 或 AsciiDoc 语法

· 可导出静态站点或电子书（PDF、epub、mobi）

· 支持多语言

· 可设置封面

· 支持变量、模板和模板继承

· 有丰富的插件

GitBook 的工具组合：

· Node.js：为了使用 npm 安装 GitBook，一定要先安装 Node.js。

· GitBook 命令：基于 Node.js 开发的命令行工具，用于创建和管理电子书。

· Markdown：GitBook 使用 Markdown 来写作，作者再也不用担心排版了。

· Git：GitBook 使用 Git 管理写作内容，方便多人协作和版本管理。

· Github/Gitlab：跟代码一样，写作的内容可以托管在 Github 或 Gitlab 中。

· gitbook.com：用于在线编写、发布和托管电子书的网站。

GitBook 的使用场景：

· 搭建公司内部的文档平台，用于公司内部的资料共享。

· 发表开源的电子书，用于在互联网上共享自己的知识，普惠大众。

GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，可以输出 HTML、PDF、eBook 等格式的电子书。所以我更喜欢把 GitBook 定义为文档格式转换工具。

所以，GitBook 不是 Markdown 编辑工具，也不是 Git 版本管理工具。市面上我们可以找到很多 Markdown 编辑器，比如 Typora、MacDown、Bear、MarkdownPad、MarkdownX、JetBrains’s IDE（需要安装插件）、Atom、简书、CSDN 以及 GitBook 自家的 GitBook Editor 等等。

但 GitBook 又与 Markdown 和 Git 息息相关，因为只有将它们结合起来使用，才能将它们的威力发挥到极致！因此，通常我们会选择合适的 Markdown 编辑工具以获得飞一般的写作体验；使用 GitBook 管理文档，预览、制作电子书；同时通过 Git 管理书籍内容的变更，并将其托管到云端（比如 GitHub、GitLab、码云，或者是自己搭建的 Git 服务器），实现多人协作。

GitBook Editor 对于新手来说是个不错的选择(下载地址：https://www.softpedia.com/get/Internet/Other-Internet-Related/GitBook-Editor.shtml  )，它集成了 GitBook、Git、Markdown 等功能，还支持将书籍同步到 gitbook.com 网站，使我们可以很方便地编辑和管理书籍。但是不幸的是，GitBook Editor 的注册和登录需要翻墙，即便注册成功了也可能登录不上，似乎是因为网站最近在升级。

因此，我推荐，也是我目前使用的搭配是 GitBook + Typora + Git。

为什么？

通常，我们最开始学习和使用的办公软件就是 Word、Excel 和 PowerPoint。这里不是说它们已经过时了，不是说 GitBook 能够替代它们。

相反，Microsoft 的办公软件很优秀并且经受了时间的考验，但是正因为它功能丰富，导致稍显臃肿（二八定律：80%的时间里我们只会只用20%的功能），同时因为它存在以二进制格式保存、软件不兼容、格式不兼容、难以进行版本控制、难以实时分享预览、难以多人协作等短板。而这恰恰是 GitBook + Markdown + Git 的长处。

简单来说，GitBook + Markdown + Git 带来的好处有：

· 语法简单

· 兼容性强

· 导出方便

· 专注内容

· 团队协作

所以，如果你和我一样，不满足于传统的写作方式，正在寻找一种令人愉悦的写作方式，那么该尝试使用 GitBook 啦！ 

当然，GitBook 不是万能的，当我们需要复杂排版时，依然需要依托于 Word 等工具。但不用担心，因为我们可以把 Markdown 格式的文档导出为 Word 格式，再进一步加工。

二、GitBook环境搭建

当你并决定尝试使用 GitBook 的时候，首先面临的问题是 —— 如何搭建 GitBook 环境？ 

开始之前我们需要先安装：

· nodejs

· gitbook

因为 GitBook 是基于 Node.js，所以我们首先需要安装 Node.js（下载地址：https://nodejs.org/en/download/  ），找到对应平台的版本安装即可。

现在安装 Node.js 都会默认安装 npm（node 包管理工具），所以我们不用单独安装 npm，打开命令行，执行以下命令安装 GitBook：

$sudo npm install -g gitbook-cli

安装完之后，就会多了一个 gitbook 命令（如果没有，请确认上面的命令是否加了 -g）。

查看 GitBook 的版本：

$ gitbook --version
CLI version: 2.3.0
GitBook version: 3.2.2

更新 GitBook命令：

$ npm update gitbook-cli -g

卸载 GitBook 命令：

$ sudo npm uninstall gitbook-cli -g

注意：

本例中使用的是全局安装 GitBook 命令，还有一种安装方式是本地安装，两种方式有什么不同呢？

本地安装：安装包会被下载到当前所在目录，因此只能在当前目录下使用。

全局安装：安装包会被下载到到特定的系统目录下，安装包能够在所有目录下使用。

例如，查看 macOS 下全局安装被安装到了哪里？

$ which gitbook
/usr/local/bin/gitbook

GitBook 被安装到了 /usr/local/bin/ 目录下，因此可以全局使用。

上面我推荐的是 GitBook + Typora + Git，所以你还需要安装 Typora（一个很棒的支持 macOS、Windows、Linux 的 Markdown 编辑工具）和 Git 版本管理工具。戳下面：

Typora 下载地址：https://typora.io/ 

Git 下载地址：https://git-scm.com/downloads 

Typora 的安装很简单，难点在于需要翻墙才能下载。Git 的安装也很简单，但要用好它需要不少时间，这里就不详细说了。 

三、GitBook的使用

想象一下，现在你准备构建一本书籍，你在硬盘上新建了一个叫 mybook 的文件夹，按照以前的做法，你会新建一个 Word 文档，写上标题，内容。但是现在有了 GitBook，你首先要做的是在 mybook 文件夹下执行以下命令：

# 创建 mybook 文件夹，并切换到这个文件夹下面
$ mkdir mybook && cd mybook 

# 初始化 gitbook 工作目录，创建必要的文件
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

执行完后，你会看到多了两个文件 —— README.md 和 SUMMARY.md，它们的作用如下： 

README.md —— 书籍的介绍写在这个文件里

SUMMARY.md —— 书籍的目录结构在这里配置

这时候，我们启动恭候多时的 Typora 来编辑这两个文件了： 

编辑 SUMMARY.md 文件，内容修改为：

# 目录

* [前言](README.md)
* [第一章](Chapter1/README.md)
* [第1节：衣](Chapter1/衣.md)
* [第2节：食](Chapter1/食.md)
* [第3节：住](Chapter1/住.md)
* [第4节：行](Chapter1/行.md)
* [第二章](Chapter2/README.md)
* [第三章](Chapter3/README.md)
* [第四章](Chapter4/README.md)

然后我们回到命令行，在 mybook 文件夹中再次执行 gitbook init 命令。GitBook 会查找 SUMMARY.md 文件中描述的目录和文件，如果没有则会将其创建。 

Typora 是所见即所得（实时渲染）的 Markdown 编辑器，这时候它是这样的：

接着我们执行 gitbook serve 来预览这本书籍，执行命令后会对 Markdown 格式的文档进行转换，默认转换为 html 格式，最后提示 “Serving book on http://localhost:4000”。嗯，打开浏览器看一下吧：

当你写得差不多，你可以执行 gitbook build 命令构建书籍，默认将生成的静态网站输出到 _book 目录。实际上，这一步也包含在 gitbook serve 里面，因为它们是 HTML，所以 GitBook 通过 Node.js 给你提供服务了。 

当然，build 命令可以指定路径：

$ gitbook build [书籍路径] [输出路径]

serve 命令也可以指定端口： 

$ gitbook serve --port 2333

你还可以生成 PDF 格式的电子书： 

$ gitbook pdf ./ ./mybook.pdf

生成 epub 格式的电子书： 

$ gitbook epub ./ ./mybook.epub

生成 mobi 格式的电子书： 

$ gitbook mobi ./ ./mybook.mobi

如果生成不了，你可能还需要安装一些工具，比如 ebook-convert。或者在 Typora 中安装 Pandoc 进行导出。 

除此之外，别忘了还可以用 Git 做版本管理呀！在 mybook 目录下执行 git init 初始化仓库，执行 git remote add 添加远程仓库（你得先在远端建好）。接着就可以愉快地 commit，push，pull … 啦！

四、gitbook 常用的命令

安装完成了后，我们就可以开始编写内容，进行电子书发布了。具体的操作，大家可以参考《GitBook简明教程》进行学习。我这里给大家推荐3种最常用的命令

gitbook init //初始化目录文件

gitbook help //列出gitbook所有的命令

gitbook --help //输出gitbook-cli的帮助信息

gitbook build //生成静态网页

gitbook serve //生成静态网页并运行服务器

gitbook build --gitbook=2.0.1 //生成时指定gitbook的版本, 本地没有会先下载

gitbook ls //列出本地所有的gitbook版本

gitbook ls-remote //列出远程可用的gitbook版本

gitbook fetch 标签/版本号 //安装对应的gitbook版本

gitbook update //更新到gitbook的最新版本

gitbook uninstall 2.0.1 //卸载对应的gitbook版本

gitbook build --log=debug //指定log的级别

五、Gitbook 配置

GitBook 允许您使用灵活的配置自定义您的电子书。

这些选项在 book.json 文件中指定。对于不熟悉 JSON 语法的作者，您可以使用 JSONlint 等工具验证语法。

常规设置

author

作者姓名，在GitBook.com上，这个字段是预先填写的。

例：

"author" : "victor zhang"

description

电子书的描述，默认值是从 README 中提取出来的。在GitBook.com上，这个字段是预先填写的。

例：

"description" : "Gitbook 教程"

direction

文本的方向。可以是 rtl 或 ltr，默认值取决于语言的值。

例：

"direction" : "ltr"

gitbook

应该使用的GitBook版本。使用SemVer规范，接受类似于 >=3.0.0 的条件。

例：

"gitbook" : "3.0.0",
"gitbook" : ">=3.0.0"

language

Gitbook使用的语言, 版本2.6.4中可选的语言如下：

en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

例：

"language" : "zh-hans",

links

在左侧导航栏添加链接信息

例：

"links" : {
"sidebar" : {
"Home" : "https://github.com/atlantis1024/gitbook-notes"
}
}

root

包含所有图书文件的根文件夹的路径， book.json 文件除外。

例：

"root" : "./docs",

structure

指定 Readme、Summary、Glossary 和 Languages 对应的文件名。

styles

自定义页面样式， 默认情况下各generator对应的css文件

例：

"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}

例如要使 h1、h2 标签有下边框， 可以在 website.css 中设置

h1 , h2{
border-bottom: 1px solid #EFEAEA;
}

title

电子书的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预先填写的。

例：

"title" : "gitbook-notes",

plugins

插件及其配置在 book.json 中指定。有关详细信息。

自 3.0.0 版本开始，GitBook 可以使用主题。有关详细信息，请参阅 the theming section 。

添加插件

"plugins": [
"splitter"
]

添加新插件之后需要运行 gitbook install 来安装新的插件

去除自带插件

Gitbook 默认带有 5 个插件：

· highlight

· search

· sharing

· font-settings

· livereload

"plugins": [
"-search"
]

structure

除了 root 属性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名称（而不是使用默认名称，如README.md）。这些文件必须在项目的根目录下（或 root 的根目录，如果你在 book.json 中配置了 root 属性）。不接受的路径，如：dir / MY_README.md。

pdf

可以使用 book.json 中的一组选项来定制PDF输出：

生成电子书

GitBook 可以生成一个网站，但也可以输出内容作为电子书（ePub，Mobi，PDF）。

# Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf

# Generate an ePub file
$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi

安装 ebook-convert

ebook-convert 可以用来生成电子书（epub，mobi，pdf）。

GNU/Linux

安装 Calibre application.

$ sudo aptitude install calibre

在一些 GNU / Linux 发行版中，节点被安装为 nodejs，您需要手动创建一个符号链接：

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

OS X

安装 Calibre application. 将 calibre.app 移动到应用程序文件夹后，创建一个符号链接到 ebook-convert 工具：

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

您可以使用 $PATH 中的任何目录替换 /usr/bin 。

封面

封面用于所有电子书格式。您可以自己提供一个，也可以使用 autocover plugin 生成一个。

要提供封面，请将 cover.jpg 文件放在书本的根目录下。添加一个 cover_small.jpg 将指定一个较小版本的封面。封面应为 JPEG 文件。

好的封面应该遵守以下准则：

· cover.jpg 的尺寸为 1800x2360 像素，cover_small.jpg 为 200x262

· 没有边界

· 清晰可见的书名

· 任何重要的文字应该在小版本中可见

六、Gitbook 部署

1.托管到 gitbook.com

GitBook.com 是使用 GitBook 格式创建和托管图书的在线平台。它提供托管，协作功能和易于使用的编辑器。

创建新书

如下图所示，根据个人需求，选择一个模板创建你的电子书。

设置书的基本信息

clone 到本地

Gitbook.com 会为每本书创建一个 git 仓库。

如下图所示，拷贝 git 地址，然后 git clone 到本地。

发布

在本地按照 Gitbook 规范编辑电子书，然后 git push 到 Gitbook 的远程仓库。

默认访问地址是：https://用户名.gitbooks.io/项目名/content/

例如：我的用户名为 atlantis1024，一个电子书项目名为 test，则访问路径是： https://atlantis1024.gitbooks.io/test/content/

当然，如果你有自己的域名，也可以设置 Domains 选项，来指定访问路径为你的域。

2.托管到 Github

如果你不希望使用 Gitbook 的仓库，而是想直接使用 Github 的仓库，也是可以的。

首先，你需要绑定你的 Github 账号。最简单的方式当然就是登录 Gitbook.com 时使用 Github 账号登录方式了。否则，你也可以在 Account Settings 中的 Github 设置选项中去进行绑定。

图Account Settings 

绑定了 Github 账号后，你可以在新建电子书时，选择从一个指定的 Github 仓库导入电子书项目。参考下图：

只要你指定的 Github 仓库中的文档内容符合 Gitbook 规范，Gitbook 就会自动根据你的每次更新去构建生成电子书网站。

默认访问地址是：

https://Github用户名.gitbooks.io/Github 仓库/content/

例如：我的用户名为 atlantis1024，Github 仓库名为 gitbook-notes，则访问路径是：

https://atlantis1024.gitbooks.io/gitbook-notes/content/

托管到 Github Pages

也许你以前也了解 Github 的一个功能： GitHub Pages 。它允许用户在 GitHub 仓库托管你的个人、组织或项目的静态页面（自动识别 html、css、javascript）。

建立 xxx.github.io 仓库

要使用这个特性，首先，你必须建立一个严格遵循以下命名要求的仓库：Github账号名.github.io举例，我的 Github 账号为 atlantis1024，则这个仓库应该叫 atlantis1024.github.io。通常，这个仓库被用来作为个人或组织的博客。

建立 gh-pages 分支

完成第1步后，在任意一个 Github 仓库中建立一个名为 gh-pages 的分支。只要 gh-pages 中的内容符合一个静态站点要求，就可以在如下地址中进行访问：https://Github用户名.gitbooks.io/Github 仓库 。例如：我的一个 Github 仓库名为 react-notes，则访问路径是：https://atlantis1024.github.io/react-notes

自动化发布到 gh-pages

如果每次都手动 git push 到远程 gh-pages 分支，略有点麻烦。

怎么实现自动化发布呢？

有两种方法：

1）使用 gh-pages 插件

如果你了解 Nodejs，那么最简单的发布方式就是使用 gh-pages 插件。

先在本地安装插件

$ npm i -D gh-pages

然后，在 package.json 文件中添加脚本命令：

如下：-d 命令参数后面是要发布的静态站点内容的目录

"scripts": {
"deploy": "gh-pages -d build"
},

2）脚本

写一个执行 git 命令的脚本就搞定了。

下面的脚本无论是在 bat 或 sh 脚本中都可以执行。

cd build
git init
git checkout -b gh-pages
git add .
git commit -am "Update"
git push git@github.com:atlantis1024/gitbook-notes gh-pages --force"

官方资源

Gitbook Github

Gitbook 官网

Gitbook Toolchain 文档

Gitbook 帮助中心

教程资源

gitbook-use by zhangjikai

工具

Gitbook 编辑器</