Contents
1. Gitbook 简介
1.1 Gitbook 是什么
Gitbook 是一个使用 Git 和 Markdown 来构建电子书籍的开源工具。它既可以生成一个静态网站，也可以输出内容作为电子书（ePub，Mobi，PDF）。Gitbook 可以在本地、Github、VPS 等平台上部署，本文采用的是借助 Node.js 在本地部署然后推送到 Github Page 托管的方式，其余的就不再赘述了。
效果演示：本网站的 Found-monthly 就是用Gitbook搭建的。
1.2 准备工作
工欲善其事，必先利其器。在开始搭建 Gitbook 电子书籍之前，你需要先了解一下 Markdown 基本语法、Git 及 Github 基本使用，然后作出如下准备：
- Node.js 环境：Gitbook 在本地部署时所需要的环境。
- Markdown 编辑器：推荐使用 Typora，用来编写 Gitbook 文档的具体内容。
- Git 工具 +Github 账号：用于将 Gitbook 托管到 Github 存储库上。
- 翻墙工具：推荐使用 SSR，本文所提到的部分工具的官网需要翻墙才能打开。
2. Gitbook 本地部署
2.1 Gitbook 本地安装
Step1：安装 Node.js
- 因为 GitBook 是基于 Node.js 的，所以我们首先需要下载安装 Node.js（对应平台的 .msi版本即可）
- 测试：打开cmd，输入 node -v和 npm -v，若显示node和npm的版本号即安装成功。
Step2：安装 gitbook-cli 工具
- gitbook-cli 是一个在系统上安装和使用 Gitbook 的工具，它将自动安装所需版本的 Gitbook 来构建一本书。
-
现在安装 Node.js 都会默认安装 npm（node 包管理工具），所以我们不用单独安装 npm，打开命令行，执行以下命令安装 GitBook
1npm install -g gitbook-cli - 安装完之后，就会多了一个 gitbook 命令（如果没有，请确认上面的命令是否加了 -g）
Step3：安装 Git
- 官网下载 Git：https://www.git-scm.com/download/win
- 安装过程中一路 next 即可，安装成功后桌面右键单击出现 Git GUI Here 以及 Git Bash Here
Step4：安装 Typora
- 官网下载 Typora：https://www.typora.io/
- 说明：Typora 可以配合 pandoc 插件将 Markdown 转换成其他格式的文件
2.2 Gitbook 本地使用
Step1：初始化 Gitbook
- 新建一个存储 Gitbook 的文件夹（即工作区），切换到该目录，然后用如下命令初始化：
1gitbook init
执行完后，你会看到多了两个文件 —— README.md 和 SUMMARY.md，它们的作用如下：
12README.md —— 书籍的介绍写在这个文件里SUMMARY.md —— 书籍的目录结构在这里配置
Step2：用 Typora 编辑一个示例
- 编辑 SUMMARY.md 文件，内容修改为：
1234567891011# 目录- [前言](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)
Step3：在本地部署 Gitbook
- 回到命令行，在 Gitbook 的工作区文件夹中再次执行 gitbook init 命令。GitBook 会查找 SUMMARY.md 文件中描述的目录和文件，如果没有则会将其创建。
- 接着我们再执行 gitbook serve 命令，将其部署在本地，打开 Chrome 访问：http://localhost:4000，即可看到本地部署的 Gitbook（注：serve 命令可以指定端口 gitbook serve --port 2333）
- 当你写得差不多，你可以执行 gitbook build 命令构建书籍，默认将生成的静态网站输出到 _book 目录。实际上，这一步也包含在 gitbook serve 里面（注：build 命令可以指定路径 gitbook build [书籍路径] [输出路径]，如果你想查看输出目录详细的记录，可使用 gitbook build ./ --log=debug --debug 来查看）
重要说明：
- 问题描述：使用 gitbook build 或者 git serve 时偶发出现不规律性编译错误的问题，每次修改要编译屡次才能成功，为后续的 Github page 部署带来了很大的麻烦。
-
解决办法：修改 C:\Users\Administrator\.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js 文件中的 112 行（将 confirm: true 改成 confirm: false）
2.3 Gitbook 导出其他格式
Step1：安装 calibre 软件
- Gitbook 可以将电子书或文档导出为 PDF、ePub、Mobi 等格式，导出这三种格式需要依赖 calibre 软件提供的 ebook-convert 库。
- calibre 官网下载：https://calibre-ebook.com/download，新版本在安装时已自动配置了环境变量，无需手动添加，安装完后在命令行中用 ebook-convert --version 验证一下。
Step2：将 Gitbook 导出其他格式
- 生成 PDF 格式的电子书： gitbook pdf ./ ./mybook.pdf
- 生成 epub 格式的电子书： gitbook epub ./ ./mybook.epub
- 生成 mobi 格式的电子书： gitbook mobi ./ ./mybook.mobi
3. Gitbook 配置文件
如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。配置文件写完后，需要重启服务或者重新打包才能应用配置。Gitbook 的配置文件是 book.json， 请在项目的根目录处自行创建。
3.1 配置文件主要参数
- title：标题
- author：作者
- description：描述，对应 Gitbook 网站的 description
- language：使用的语言， zh-hans 是简体中文，会对应到页面的 <html lang="zh-hans" >
- structure：指定 Readme、Summary、Glossary 和 Languages 对应的文件名
- plugins：使用的插件列表，所有的插件都在这里写出来，然后使用 gitbook install 来安装。
- pluginsConfig：插件的配置信息，如果插件需要配置参数，那么在这里填写。
- links：目前可以给侧导航栏添加链接信息
- styles：自定义页面样式，各种格式对应各自的 css 文件
3.2 Gitbook 的常用插件
3.2.1 Gitbook 插件简介
[1] 为什么要用插件？
Gitbook 默认自带以下 5 个插件：highlight：代码高亮、search：导航栏查询功能（不支持中文）、sharing：右上角分享功能、font-settings：字体设置（最上方的”A”符号）、livereload：为 Gitbook 实时重新加载。Gitbook 插件可以解决一些网站不太方便的地方，如侧边栏导航不能收缩，自带搜索不支持中文等问题。
[2] 去哪里找插件？
除了下文推荐的插件之外，Gitbook 还支持许多其他插件，可以从NPM 上搜索 Gitbook 相关的插件。
[3] 插件安装方法：
- Step1：在项目的根目录中创建 book.json 文件，然后在 plugins 参数中添加插件名。
- Step2：使用 gitbook install 来安装插件，重启服务 gitbook serve 或者重新打包 gitbook build 就能看见效果。
注意：
- 编写 json 时字符串不能用“单引号”括起，最后的那个不能有“逗号”。
- 如果要卸载自带的 font-settings，插件处应写成 -fontsettings，中间不要加 -。
- gitbook install 有时会出现问题，多试几次可能就好了。
3.2.2 Gitbook 插件推荐
[1] 支持中文的搜索框
|
1 2 3 4 5 6 7 |
{ "plugins": [ "-lunr", "-search", "search-pro" ], } |
[2] 左侧章节目录可折叠
|
1 2 3 4 5 |
{ "plugins": [ "expandable-chapters-small" ], } |
[3] 侧边栏宽度可调节
|
1 2 3 4 5 |
{ "plugins": [ "splitter" ], } |
[4] 回到顶部按钮
|
1 2 3 4 5 |
{ "plugins": [ "back-to-top-button" ], } |
[5] 右上角添加 github 图标跳转
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "plugins": [ "-sharing", "github" ], "pluginsConfig": { "github": { "url": "https://github.com/Logistic98/Found-monthly" }, } } |
[6] 阅读量计数
|
1 2 3 4 5 |
{ "plugins": [ "pageview-count" ], } |
[7] 隐藏元素
可以隐藏不想看到的元素， hide-element 是通过 HTML 元素的 class 名字来查找要隐藏的元素，想要隐藏元素找到元素的样式类名加到插件配置里面就可以隐藏元素了。
|
1 2 3 4 5 6 7 8 9 10 |
{ "plugins": [ "hide-element" ], "pluginsConfig": { "hide-element": { "elements": [".gitbook-link"] }, } } |
经过该配置之后，导航栏中 Published by GitBook 就被隐藏了。
[8] 代码块行号、复制
|
1 2 3 4 5 |
{ "plugins": [ "code" ], } |
[9] 复选框支持
|
1 2 3 4 5 |
{ "plugins": [ "todo" ], } |
[10] 修改标题栏图标
|
1 2 3 4 5 6 7 8 |
{ "plugins": [ "custom-favicon" ], "pluginsConfig": { "favicon": "./static/logo.ico" }, } |
把 ico 格式的图标放到项目里（这个插件只能用 ico 图标），路径可以设置为相对路径
[11] 添加悬浮目录
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "plugins" : [ "page-toc-button" ], "pluginsConfig": { "page-toc-button": { "maxTocDepth": 2, "minTocSize": 2 }, } } |
maxTocDepth：标题的最大深度（最大支持到 2，即为 h1+h2+h3）
minTocSize：显示 toc 按钮的最小 toc 条目数
[12] 添加版权信息和最后修改时间
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "plugins": [ "tbfed-pagefooter" ], "pluginsConfig": { "tbfed-pagefooter": { "copyright":"Copyright © blackcat.monster 2020", "modify_label": "该文件修订时间：", "modify_format": "YYYY-MM-DD HH:mm:ss" }, } } |
3.3 Gitbook 成品配置
以下是我配好的 book.json 文件，仅供参考。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
{ "title": "Found-weekly", "description": "记录分享新发现的科技见闻，每月28号更新", "author": "Mortal", "output.name": "site", "language": "zh-hans", "gitbook": "3.2.3", "root": ".", "links": { "sidebar": { "BlackCatの小窝": "https://www.blackcat.monster" } }, "plugins": [ "-lunr", "-search", "-sharing", "-fontsettings", "highlight", "livereload", "search-pro", "expandable-chapters-small", "splitter", "back-to-top-button", "github", "pageview-count", "hide-element", "code", "todo", "custom-favicon", "page-toc-button", "tbfed-pagefooter" ], "pluginsConfig": { "github": { "url": "https://github.com/Logistic98/Found-monthly" }, "hide-element": { "elements": [".gitbook-link"] }, "favicon": "./static/logo.ico", "page-toc-button": { "maxTocDepth": 2, "minTocSize": 2 }, "tbfed-pagefooter": { "copyright":"Copyright © blackcat.monster", "modify_label": "该文件修订时间：", "modify_format": "YYYY-MM-DD HH:mm:ss" } } } |
4. 托管到 Github Page
这部分需要使用 Git 和 Github 网站，可以参见我的另一篇博文：Git 及 Github 基本使用
由于 Gitbook 生成的项目跟文档的源码是两个部分，所以可以把文档放到 master 分支上，部署的网站放到 gh-pages 分支。
4.1 本地项目提交到 Github 仓库
[1] 创建git忽略文件
有些文件是不需要纳入到版本控制之中的，在项目根目录创建一个名为 .gitignore的git忽略文件，编辑内容如下：
|
1 2 |
# 忽略gitbook生成的项目目录 _book |
下面是一些 .gitignore文件忽略的匹配规则：
|
1 2 3 4 5 |
*.a # 忽略所有 .a 结尾的文件 !lib.a # 但 lib.a 除外 /TODO # 仅仅忽略项目根目录下的 TODO 文件，不包括 subdir/TODO build/ # 忽略 build/ 目录下的所有文件 doc/*.txt # 会忽略 doc/notes.txt 但不包括 doc/server/arch.txt |
注意： .gitignore只能忽略那些原来没有被track的文件，如果某些文件已经被纳入了版本管理中，则修改 .gitignore文件是无效的。那么解决方法就是先把本地缓存删除（改变成未track状态），然后再提交。
[2] SSH KEY
由于本地 Git 仓库和 Github 仓库之间的传输是通过 SSH 加密的，所以连接时需要设置一下：
Step1：先看一下 C:\Users\xxx 有没有.ssh 目录，有的话看下里面有没有 id_rsa 和 id_rsa.pub 这两个文件，有就跳到下一步，没有就通过下面命令创建:
|
1 |
$ ssh-keygen -t rsa -C "xxx@xxx.com" |
然后一路回车，这时你就会在用户下的.ssh 目录里找到 id_rsa 和 id_rsa.pub 这两个文件
Step2：登录 Github,找到右上角的图标，打开点进里面的 Settings，再选中里面的 SSH and GPG KEYS，点击右上角的 New SSH key，然后 Title 里面随便填，再把刚才 id_rsa.pub 里面的内容复制到 Title 下面的 Key 内容框里面，最后点击 Add SSH key，这样就完成了 SSH Key 的加密。
[3] 初次部署
|
1 2 3 4 5 6 7 8 9 10 11 12 |
[1] 设置用户名和邮箱 git config --global user.name "Your Name" # 填Github的用户名 git config --global user.email "xxx@example.com" # 填Github的邮箱地址 [2] 将项目从本地提交到仓库 git init # 创建git工作区 git add . # 提交所有文件到暂存区 git status # 查看git状态 git commit -m 'description' # 提交到仓库，''内的是描述信息 [3] 连接到远程仓库，并将代码推送至远程仓库 git remote add origin URL # 连接到远程仓库并创建别名 git pull origin master --allow-unrelated-histories # 取回远程仓库分支的更新，再与本地的分支合并 git push -u origin master # 将本地仓库推送至远程仓库 |
说明：
- 用户名和邮箱设置：在 github 仓库主页显示谁提交了该文件，要根据 github 的注册信息来填写，不要填错了。
- git init 后，在文件夹内生成.git 文件（如果没有，则 查看——勾选“隐藏的项目”）
- 仓库地址可在 clone or download 按钮下取得（即仓库的浏览器地址栏末尾加 .git）
- 使用 git pull origin master 命令报错： fatal:refusing to merge unrelated histories
- 错误原因：如果合并了两个不同的开始提交的仓库，在新的 git 会发现这两个仓库可能不是同一个，为了防止开发者上传错误，于是就出现了此提示。
- 解决办法：如我在 Github 新建一个仓库，写了 License，然后把本地一个写了很久仓库上传。这时会发现 github 的仓库和本地的没有一个共同的 commit 所以 git 不让提交，认为是写错了 origin ，如果开发者确定是这个 origin 就可以使用 –allow-unrelated-histories 告诉 git 允许不相关历史合并
- 使用 git push origin master 命令报错： error:failed to push some refs to URL
- 错误原因：直接在 GitHub 上修改后，内容已经和本地不一致了，必须要合并（merge）
- 解决办法：先使用 git pull origin master 命令下载到本地并合并，自动弹出的 vim 编辑器（按 i 进行编辑，说明为什么合并，可选择不修改，ESC 进入命令行模式然后输入 :wq 退出），再 git push origin master
- 使用 git add .命令报错：warning: LF will be replaced by CRLF
- 原因：在 Unix 系统中，行尾用换行（LF）表示。在窗口中，用回车（CR）和换行（LF）（CRLF）表示一行。当您从 unix 系统上载的 git 中获取代码时，它们将只有 LF。
-
解决办法：如果您是在 Windows 计算机上工作的单个开发人员，并且您不关心 git 自动将 LF 替换为 CRLF，则可以通过在 git 命令行中键入以下内容来关闭此警告
1git config core.autocrlf true
[4] 后续使用
|
1 2 3 4 5 |
git add . # 提交所有文件到暂存区 git status # 查看git状态 git commit -m 'description' # 提交到仓库，''内的是描述信息 git pull origin master # 取回远程仓库分支的更新，再与本地的分支合并 git push origin master # 将本地仓库推送至远程仓库 |
为了提交方便，可以创建一个脚本文件 commit.sh 来自动执行，内容如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# 解决使用git add命令时报错LF will be replaced by CRLF的问题 echo '执行命令：git config auto.crlf true\n' git config auto.crlf true # 保存所有的修改 echo '执行命令：git add -A\n' git add -A # 把修改的文件提交 echo "执行命令：git commit -m 'update gitbook'\n" git commit -m 'update gitbook' # 将本地仓库推送至远程仓库 echo '执行命令：git push origin master\n' git push origin master |
4.2 上传到 Github 仓库的 gh-pages 分支
打包命令太多，为了部署方便，可以创建一个脚本文件 deploy.sh 来自动执行，内容如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
# 构建Gitbook echo '执行命令：gitbook build .' gitbook build . # 进入生成的文件夹 echo "执行命令：cd ./_book\n" cd ./_book # 初始化一个仓库，仅仅是做了一个初始化的操作，项目里的文件还没有被跟踪 echo "执行命令：git init\n" git init # 解决使用git add命令时报错LF will be replaced by CRLF的问题 echo '执行命令：git config auto.crlf true\n' git config auto.crlf true # 保存所有的修改 echo "执行命令：git add -A" git add -A # 把修改的文件提交 echo "执行命令：commit -m 'deploy gitbook'" git commit -m 'deploy gitbook' # 发布到 https://<USERNAME>.github.io/<REPO> echo "执行命令：git push -f https://github.com/Logistic98/Found-monthly.git master:gh-pages" git push -f https://github.com/Logistic98/Found-monthly.git master:gh-pages # 返回到上一次的工作目录 echo "回到刚才工作目录" cd - |
注意脚本文件代码中仓库地址要替换成你自己的地址。
文件保存后，在终端执行如下命令，把生成的项目推送到 github 仓库上的 gh-pages 分支：
|
1 |
bash deploy.sh |
执行成功后，打开你的 github 仓库，然后选择 branch 分支，会发现多了一个 gh-pages 分支，打开这个分之后，里面会有一个 index.html 文件，说明部署的代码上传成功了。
4.3 查看 GitHub Page 网站
在 Github 网站上的项目仓库右侧，有一个 Environments，点进去之后再点击 View deployment，即可查看部署好的 GitHub Page。至此，我们的 Gitbook 就已经搭建完成了。
5. 使用 PicGo 将图片上传到 Github 图床
由于 Gitbook 使用的是 Markdown 语法，如何保存图片也是一个问题，我目前有两种解决方案：
- Typora+Chevereto+ShareX：在 VPS 自建图床，借助 ShareX 工具上传，具体配置详见我的另一篇博客–搭建 Chevereto 私有图床
- Typora+Github+PicGo：用 Github 仓库作为图床，借助 PicGo 工具上传，具体配置下面会详细来说。
由于 Typora 可以配合 PicGo 实现本地图片插入时自动上传 Github，所以个人习惯使用后者来管理图片，图片跟随者 Gitbook 一同上传到 Github 仓库进行托管。
5.1 获取 Github 的 Token
[1] 点击右上角头像，点击 Settings
[2] 点击 Deverloper settings
[3] 点击 Personal Access Token 再点击 Generate new token
[4] 填写信息，勾选 repo,拉到最下点击 Generate token
[5] 保存生成的 Token
5.2 安装配置 PicGo
[1] 下载 PicGo：https://github.com/Molunerfinn/picgo/releases
[2] 在 PicGo 的图床设置里配置如下五条信息
5.3 配置 Typora 的图片自动上传
文件——偏好设置——图像——插入图片时选择“上传图片”（如果没有这个选项请更新 Typora 的版本）——勾选“对本地位置的图片应用上述规则”）——配置 PicGo 路径
配置完成后，点击“验证图片上传选项”按钮，验证通过即可实现“插入本地图片时自动上传 Github 图床仓库”
说明：即便配置成功了，有时因为网络原因，使用 Typora 或 PicGo 上传还是会失败，可以多试几次。
6. 参考资料
[2] gitbook 使用教程 from segmentfault
[3] gitbook 常用插件 from segmentfault
[4] GitBook 插件整理 – book.json 配置 from Gitbook
[5] github+picgo+typora 搭建免费图床 from DedicationTechnology
[6] gitbook build/serve 失败，Error: ENOENT: no such file or directory, stat … from 尚码园
