GitBook安装，组织文档并发布到GitHub的Pages中展示

GitBook是一个基于Node.js的一款文档编辑工具。它的功能类似金山WPS中的Word或者微软Office中的Word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。 当然，以上的功能WPS、Office可能做得更好，但是，GitBook还有更最强大的功能：它可以用文档建立一个网站，让更多人了解你写的书，另外，最最核心的是，他支持Git，也就意味着，它是一个分布式的文档编辑工具。 你可以随时随地来编写你的文档，也可以多人共同编写文档，哪怕多人编写同一页文档，它也能记录每个人的内容，然后告诉你他们之间的区别，也能记录你的每一次改动，你可以查看每一次的书写记录和变化，哪怕你将文档都删除了，它也能找回来！ 这就是它继承Git后的厉害之处！

你可以在自己电脑上使用GitBook来写一本书，也可以通过 GitBook.com 线方式写一本书。 还可以在自己电脑上安装桌面版的GitBook编辑器。完整的中文文档在gitbook.hushuang.me上。

分布式、多人协同的全新书写方式！在GitBook中，你可以使用Markdown或者AsciiDoc语法，加上几个命令就能创建一本漂亮的图书。这种便利就像Node.js一样。GitBook支持GitHub或者git来管理文章的改动和版本。

一、GitBook安装

1、下载、安装Node.js,https://nodejs.org/en/。使用下面命令检测是否安装成功

node -v
v12.16.0

2、安装GitBook

C:\Users\ginge>npm install gitbook-cli -g
C:\Users\ginge\AppData\Roaming\npm\gitbook -> C:\Users\ginge\AppData\Roaming\npm\node_modules\gitbook-cli\bin\gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 23.913s

安装完成后检验是否安装成功

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

GitBook准备工作做好之后，进入第一个你要书写的目录，输入如下命令。

F:\0.GitBook\测试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 —— 书籍的目录结构在这里配置，其默认内容如下所示：

# Summary

* [Introduction](README.md)

3、使用Typora来编写.md文件，https://www.typora.io/。

增加目录结构：修改：SUMMARY.md：

# Summary

* [Introduction](README.md)
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

如编辑SUMMARY.md后，再次执行gitbook init，生成新的目录结构。

二、用GitBook组织文档

1、浏览器浏览gitbook serve 

执行 gitbook serve 来预览这本书籍，执行命令后会对 Markdown 格式的文档进行转换，默认转换为 html 格式，最后提示 “Serving book on http://localhost:4000”

2、构建书籍gitbook build

运行gitbook build命令会在书籍坐在目录生成一个_book文件夹，里面的内容即为生成的html文件，可以通过使用gitbook build命令来生成网页而不开启服务器。

默认：将生成的静态网站输出到 _book 目录

• 指定路径：gitbook build [书籍路径] [输出路径]。为了在GitHub上访问，使用gitbook build . docs。
• 指定端口：gitbook serve --port 2333
• 生成pdf格式：gitbook pdf ./ ./mybook.pdf
• 生成epub格式：gitbook epub ./ ./mybook.epub
• 生成 mobi 格式：gitbook mobi ./ ./mybook.mobi

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

三、GitBook展示到GitHub的Pages中，用Git做版本管理

0、在编写的book目录下执行gitbook build . docs构建GitBook书籍。

1、在远端建立好git仓库。

2、在编写的book目录下，将编写的book发布到GitHub。示例步骤：

git init
git add *
git commit -m "first commit"
git remote add origin https://github.com/gingerredjade/python-core-tech.git
git push -u origin master

3、最终目的将我们本地编辑的文档通过GitHub的Pages功能实现在线访问。

• 在python-core-tech项目里点击settings，找到GitHub Pages；
• Source选择使用docs目录下的内容来呈现项目文档（注意！gitbook构建时一定要使用gitbook build . docs，否则这里的选项是金禁用的！）
• 选择后页面会自动刷新生成访问地址，接下来只要访问地址即可。

四、GitBook的使用方式

您可以通过以下方式使用示例的python-core-tech书：

• GitHub地址：https://github.com/gingerredjade/python-core-tech
• GitBook在线浏览：https://gingerredjade.github.io/python-core-tech/
• 下载离线版：可在GitHub上标签releases版本供开放下载。

五、GitBook配置目录的折叠功能

1、先在电子书根目录里新建一个book.json文件，内容如下：

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

2、还在放book.json的书籍的根目录，执行gitbook install命令。

六、GitBook目录添加数字

1、先在电子书根目录里新建一个book.json文件，内容如下：

{
    "pluginsConfig": {
        "theme-default": {
             "showLevel": true
        }
    }
}

参考：http://caibaojian.com/gitbook/