GitBook使用

Posted 2020-10-03

一、什么是GitBook

GitBook是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书。支持输出多种文档格式：

• 静态站点：GitBook默认输出该种格式，生成的静态站点可直接托管搭载Github Pages服务上；
• PDF：需要安装gitbook-pdf依赖；
• eBook：需要安装ebook-convert；
• 单html网页：支持将内容输出为单页的HTML，不过一般用在将电子书格式转换为PDF或eBook的中间过程；
• JSON：一般用于电子书的调试或元数据提取

二、安装GitBook

2.1. 前提条件

• nodejs（npm）

2.2. 安装过程

第一步：安装gitbook-cli

E:\Workspace> npm install -g gitbook-cli

 第二步：安装gitbook（注意：首次执行命令时，会下载gitbook，请耐心等候...）

E:\Workspace> gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

 

三、使用gitbook

3.1. 编辑书籍

3.1.1. 根据书籍目录来创建书籍骨架

第一步：创建SUMMARY.md文件，其内容如下

# Summary

* [简介](README.md)
* [第一章](chapter1/README.md)
    * [第一节](chapter1/section1.md)
    * [第二节](chapter1/section2.md)
* [第二章](chapter2/README.md)
    * [第一节](chapter2/section1.md)
    * [第二节](chapter2/section2.md)
* [结束](end/README.md)

 此时该目录下只有一个文件即SUMMARY.md

E:\Workspace>dir
 驱动器 E 中的卷是 文档
 卷的序列号是 82DC-9853

 E:\Workspace的目录

2017/08/17  02:16    <DIR>          .
2017/08/17  02:16    <DIR>          ..
2017/08/17  01:47               310 SUMMARY.md

  第二步：创建书籍骨架

E:\Workspace> gitbook init
info: create README.md
info: create chapter1/README.md
info: create chapter1/section1.md
info: create chapter1/section2.md
info: create chapter2/README.md
info: create chapter2/section1.md
info: create chapter2/section2.md
info: create end/README.md
info: create SUMMARY.md
info: initialization is finished

 init命令会依据SUMMARY.md里面的内容为每个章节创建空白的文件。这样分别编辑各章节的文件内容即可。后续若需要更新章节资料，请相应的修改SUMMARY.md文件和相关的章节文件中的内容。

 

3.2. 生成图书

3.2.1. 生成静态站点

E:\Workspace> 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 9 pages
info: found 8 asset files
info: >> generation finished with success in 2.5s !

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

 执行完成以后，在浏览器中键入http://localhost:4000，即可浏览到你编辑的书籍资料。同时你可以看到在目录中会多出一个_book的目录，其中的内容就是serve命令所产生的静态网页内容。

 

3.3. gitbook常用命令

• 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 builid --debug //输出错误信息

https://www.gitbook.com/explore?lang=zh