开发工具总结（12）之GitBook制作文档并发布到GitHub

版权声明：本文为博主原创文章，未经博主允许不得转载。https://www.jianshu.com/p/5c1e57211333

转载请标明出处：
https://www.jianshu.com/p/5c1e57211333

本文出自 AWeiLoveAndroid的博客

---

在线文档制作工具系列篇 ↓：

• 第一篇：GitBook制作文档并发布到GitHub

• 第二篇：Hexo制作文档并发布到GitHub

• 第三篇：Jekyll制作文档并发布到GitHub

• 第四篇：Vuepress制作文档并发布到GitHub

---

熟悉git的朋友们，如果使用GitBook，一定会是最佳搭档。因为gitbook是最简洁的，你只要写好你的MD文档，然后用gitbook命令生成html相关文件，传到github即可浏览。或者你直接登陆gitbook，使用网页端编辑，然后也可以直接预览效果。下面讲解一下Gitbook如何制作文档。

一、GitBook制作文档并发布到GitHub

1、npm全局安装GitBook 命令行工具

命令行： npm install gitbook-cli -g

如图所示：

npm安装gitbook命令行

下载后的相关路径为：

C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-asciidoc
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-html
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-markdown
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-fontsettings
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-highlight
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-livereload
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-lunr
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-search
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-sharing
C:\Users\Administrator\AppData\Roaming\npm-cache\gitbook-plugin-theme-default

在npm-cache\registry.npm.taobao.org路径也有：

C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-asciidoc
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-html
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-markdown
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-fontsettings
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-highlight
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\itbook-plugin-livereload
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-lunr
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-search
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-sharing
C:\Users\Administrator\AppData\Roaming\npm-cache\registry.npm.taobao.org\gitbook-plugin-theme-default

临时缓存路径（其中xxx换成电脑里面具体的数字字母组合即可）：

C:\Users\Administrator\AppData\Local\Temp\tmp-xxxode_modules\gitbook\node_modules\

2、创建文件和初始化

1.新建一个文件夹

mkdir gitbook-note

2.进入到文件夹

cd gitbook-note

3.进行初始化

gitbook init

初次初始化会安装GitBook， 这里下载的是GitBook-3.2.3，如果不翻墙非常慢。

初始化

翻墙之后，就很快了。如图：

git init命令行（必须翻墙）

gitbook init会自动生成两个文件README.md和SUMMARY.md：

• README.md: 书的介绍文字，如前言、简介，在章节中也可做为章节的简介。

readme内容

• SUMMARY.md: 定制书籍的章节结构和顺序。

SUMMARY内容

3、查看本地文件并发布到github

运行命令行gitbook serve，然后打开浏览器输入localhost:4000。

网页中查看

我们运行命令行gitbook serve，会生成文件夹_book，打开会发现生成是的html等能被浏览器识别的文件，能够部署在服务器或者github中,可以直接上传到github。

4、修改文件

修改目录：目录结构一定要用*才可以，用其它的符号都不行。

修改目录

然后各自的文件夹里面写各自的章节内容就好了。

最后效果如图所示：

修改后的网页

5、其它配置

项目根目录新建GLOSSARY.md，该文件用于词汇、术语列表（可选）。
示例：

## test
测试定义

新建book.json文件，里面可以存放一些自定义配置（该文件可选）。

常用的配置选项有：

• title：电子书名
• description：书籍的描述
• author：作者名
• language：本书的语言类型
• direction：文本阅读顺序

常用设置

"plugins": ["expandable-chapters-small"]

开启可折叠目录插件配置

"pluginsConfig": {
​    "expandable-chapters-small":{}
}

安装和使用可折叠目录插件：（未安装的话，先配置这个，然后可以执行命令gitbook install进行安装）

安装命令示意图如下：

安装可折叠目录插件

gitbook插件下载地址： https://plugins.gitbook.com/plugin/prism

---

二、错误解决方案

1、使用https://github.com/liushilive/gitbook-plugin-books/出现的错误：

出现的错误

解决方案：

首先下载Katex，如图：

下载katex

如果还不行，就全局安装相应模块npm install -g books-cli。会首先下载Chromium r609904

如果太慢，建议打开淘宝镜像下载：https://npm.taobao.org/mirrors/chromium-browser-snapshots/Win/609904/

下载到这个目录里面了：C:\Users\Administrator\AppData\Roaming\npm\node_modules\books-cli\node_modules\puppeteer.local-chromium\

2、安装过程出现的错误：ERROR: Failed to download Chromium r609904! Set "PUPPETEER_SKIP_CHROMIUM_DOWNLOAD" env variable to skip download.

解决方式：使用国内Chromium源：npm config set puppeteer_download_host=https://npm.taobao.org/mirrors

正常情况如图所示：

下载books-cli