Gitbook使用教程

# Gitbook使用教程

## 一、GitBook 简介

gitbook 是一个基于node.js命令的工具，可以使用网络常见的github|git和Markdown来制作精美的电子书，而且和typora软件搭配是一款非常好的笔记记录软件，下面我们一起来了解它的入门需知吧

- 语法简单

- 兼容性强

- 导出方便

- 专注内容

- 团队协作

## 二、安装

### 安装软件：Git、Typora

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

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

### 安装 Node.js

GitBook 是一个基于 Node.js 的命令行工具，下载安装 [Node.js]https://nodejs.org/zh-cn/)，安装完成之后，你可以使用下面的命令来检验是否安装成功。

```bash

$ node -v

v7.7.1

```

## 三、使用

### 1.全局安装`gitbook-cli`输入下面的命令来安装 GitBook。

```bash

npm i -g gitbook-cli | npm install gitbook-cli -g

```

更多详情请参照 [GitBook 安装文档](https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md) 来安装 GitBook。

### 2.新建文件夹(英文命名如：readme)

```

gitbook init

```

<img src="./img/2.png" style="zoom: 50%;" />![img](./img/3.png)

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

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

### 3.启动Typora编辑器，引入文件夹

![img](./img/3.png)

### 4.编辑`SUMMARY.md`

```bash

# Summary

* [目录](README.md)

* [第一章](notes/1-0.md)

* [第1节：](notes/1-1.md)

* [第2节：](notes/1-2.md)

* [第3节：](notes/1-3.md)

* [第4节：](notes/1-4.md)

* [第二章](notes/2-0.md)

* [第三章](notes/3-0.md)

* [第四章](notes/4-0.md)

```

### 5.再次执行`gitbook init`，生成新目录结构

![img](./\img\4.png)

### 6.浏览器浏览：`gitbook serve`

```bash

gitbook serve

```

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

<img src="./\img\5.png" alt="5" style="zoom: 50%;" />![](./\img\7.png)

### 7.构建书籍：`gitbook build`

```bash

gitbook build

```

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

- [x] 指定路径：`gitbook build [书籍路径] [输出路径]`

- [x] 指定端口：`gitbook serve --port 2333`

- [x] 生成pdf格式：`gitbook pdf ./ ./mybook.pdf`

- [x] 生成epub格式：`gitbook epub ./ ./mybook.epub`

- [x] 生成 mobi 格式：`gitbook mobi ./ ./mybook.mobi`

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

## 8.gitbook附加命令

```bash

npm i -g gitbook-cli | npm install gitbook-cli -g //安装环境

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 //输出错误信息1234567891011121312345678910111213

```

## 四、目录结构插件信息

GitBook 基本的目录结构如下所示：

```ruby

├── book.json

├── README.md

├── SUMMARY.md

├── notes/

| ├── 1-0.md

| └── 1-1.md

| ├── 1-2.md

| └── 1-3.md

```

下面我们主要来讲讲 book.json 和 SUMMARY.md 文件。

https://www.cnblogs.com/mingyue5826/p/10307051.html

### book.json

主要存放配置信息

```js

{

"plugins": [

"collapsible-menu",

"anchor-navigation-ex",

"tbfed-pagefooter",

"disqus"

"title": "张成的笔记（2018-2020）",

"pluginsConfig": {

"tbfed-pagefooter": {

"copyright": "Copyright &copy zhangcheng 2018-2020",

"modify_label": "文件修订时间：",

"modify_format": "YYYY-MM-DD HH:mm:ss"

"disqus": {

"shortName": "gitbookuse"

}

```

### 配置说明

| 变量 | 描述 |

| ------------- | ------------------------------------------------------------ |

| root | 包含所有图书文件的根文件夹的路径，除了 book.json |

| structure | 指定自述文件，摘要，词汇表等的路径 |

| title | 您的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。 |

| description | 您的书籍的描述，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。 |

| author | 作者名。在GitBook.com上，这个字段是预填的。 |

| isbn | 国际标准书号 ISBN |

| language | 本书的语言类型 —— [ISO code](https://links.jianshu.com/go?to=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FList_of_ISO_639-1_codes) 。默认值是 `en` |

| direction | 文本阅读顺序。可以是 rtl （从右向左）或 ltr （从左向右），默认值依赖于 language 的值。 |

| gitbook | 应该使用的GitBook版本，并接受类似于 `>=3.0.0` 的条件。 |

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

| plugins | 要加载的插件列表([官网插件列表](https://links.jianshu.com/go?to=https%3A%2F%2Fdocs.gitbook.com%2Fv2-changes%2Fimportant-differences%23plugins)) |

| pluginsConfig | 插件的配置 |

### 默认插件

- highlight - 语法高亮插件

- search - 搜索插件

- sharing - 分享插件

- font-settings - 字体设置插件

- livereload - 热加载插件

该文件主要用来存放配置信息，我先放出我的配置文件。

相信很多节点自己也能猜到是什么意思，我还是简单介绍下吧。

搜索

![image-20200716145919634](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3N0bjUxZ2V6ajMwZnkwNGd0OHEuanBn?x-oss-process=image/format,png)

字体

![image-20200716145955656](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3N0bnByd3ppajMwYjIwNXd3ZWwuanBn?x-oss-process=image/format,png)

![image-20200716150040280](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3N0b2lhbmJmajMwODAwNnp0OHQuanBn?x-oss-process=image/format,png)

### 删除默认插件

在平时开发中比如分享给出的都是一些国外的社交网站对于我们没太大用户那么我们可以删除默认配置

在插件配置在加`-`,配置完执行`gitbook install`即可

```json

"plugins": [

"-sharing"

]

123

```

效果如下：

![image-20200716150604078](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3N0dTQzcHI3ajMxcW8waWN3Z2wuanBn?x-oss-process=image/format,png)

右侧不再展示分享相关的按钮

### 常用配置

#### 代码复制

```js

"plugins": [

"code"

]

123

```

效果如下：

![image-20200720142753077](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmN254NTZrajMxN3EwNnNqcnUuanBn?x-oss-process=image/format,png)

代码复制按钮

```js

"plugins": [

"copy-code-button"

]

123

```

![image-20200720144333351](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmbngzMXc2ajMxODYwN2NqcncuanBn?x-oss-process=image/format,png)

#### 目录折叠

```js

"plugins": [

"expandable-chapters"

]

123

```

效果如下：

![image-20200720142951146](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmOW83cnExajMwY20wYmNhYXAuanBn?x-oss-process=image/format,png)

```js

"plugins": [

"expandable-chapters-small"

]

123

```

和上面一样都是折叠目录的，区别就是下面的箭头要细一些。

效果如下：

![image-20200720143153085](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmYnJyOHVnajMwZzIwZWd3ZmUuanBn?x-oss-process=image/format,png)

#### 回到顶部

```js

"plugins": [

"back-to-top-button"

]

123

```

效果如下：

![image-20200720143530843](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmZmsxOTA2ajMxZ3UwZzQwdjAuanBn?x-oss-process=image/format,png)

#### 高级搜索

去除默认的search搜索和lunr，在搜索结果中，关键字会高亮；自带的 search 插件，关键字不会高亮

```js

"plugins": [

"-lunr",

"-search",

"search-pro"

]

12345

```

原生搜索效果：

![image-20200720144425681](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmb3R6NnMwajMxeWUwamdncm8uanBn?x-oss-process=image/format,png)

高级搜索：

![image-20200720144917280](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hmdHdpdTBrajMyMHMwcmkxMnouanBn?x-oss-process=image/format,png)

搜索关键字高亮，支持中文、拼音和英文

#### 分享

分享当前页面，比默认的 sharing 插件多了一些分享方式

```js

"plugins": ["-sharing", "sharing-plus"],

"pluginsConfig": {

"sharing": {

"douban": false,

"facebook": false,

"google": true,

"pocket": false,

"qq": false,

"qzone": true,

"twitter": false,

"weibo": true,

"all": [

"douban", "facebook", "google", "instapaper", "linkedin","twitter", "weibo",

"messenger","qq", "qzone","viber","whatsapp"

]

}

12345678910111213141516

```

参数配置里面true的默认展示图标，false的默认不展示；all里面的会在分享按钮的下拉列表里面全部展示出来。

效果如下：

![image-20200720145713703](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hnMjVkZnN0ajMwaWUwczh3ZzEuanBn?x-oss-process=image/format,png)

分享效果如下：

![image-20200720145824437](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hnM2RleTg5ajMxNWEwdG90Y2wuanBn?x-oss-process=image/format,png)

#### 配置页脚

```js

"plugins": [

"tbfed-pagefooter"

"pluginsConfig": {

"tbfed-pagefooter": {

"copyright":"Copyright &copy mine 2000-2020",

"modify_label": "文件修订时间：",

"modify_format": "YYYY-MM-DD HH:mm:ss"

}

12345678910

```

效果如下：

![image-20200720152236897](https://imgconvert.csdnimg.cn/aHR0cHM6Ly90dmExLnNpbmFpbWcuY24vbGFyZ2UvMDA3UzhaSWxseTFnZ3hnc2tleTE5ajMxOHEwM2lqcnMuanBn?x-oss-process=image/format,png)

### title：设置书本的标题?

```json

"title" : "Gitbook Use"

```

### author：作者的相关信息?

```

"author" : "ds"

```

### description：本书的简单描述?

```json

"description" : "记录Gitbook的配置和一些插件的使用"

```

### language：Gitbook使用的语言?

版本2.6.4中可选的语言如下：

```json

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-tw1

```

配置使用简体中文:

```json

"language" : "zh-hans",

```

### gitbook: 指定使用的gitbook版本?

```json

"gitbook" : "3.2.2",

"gitbook" : ">=3.0.0"12

```

### root：指定根目录?

```json

"root": "."1

```

### links：左侧导航栏添加链接信息?

```json

"links" : {

"sidebar" : {

"个人主页" : "http://www.ds-vip.top"

}

}12345

```

### styles：自定义页面样式?

默认情况下各`generator`对应的`css`文件：

```json

"styles": {

"website": "styles/website.css",

"ebook": "styles/ebook.css",

"pdf": "styles/pdf.css",

"mobi": "styles/mobi.css",

"epub": "styles/epub.css"

}1234567

```

例如使` `标签有下边框，可以在`website.css`中设置，这个可以有。

```css

h1 , h2{

border-bottom: 1px solid #EFEAEA;

}123

```

### plugins：配置使用的插件?

```j'so

"plugins": [

"disqus"

]123

```

- 例如上面添加`disqus`插件：之后需要运行`gitbook install`来安装新的插件。

- Gitbook默认带有5个插件：highlight、search、sharing、font-settings、livereload

- 如果要去除自带的插件，可以在插件名称前面加`-`：

```json

"plugins": [

"-search"

]123

```

### pluginsConfig：配置插件的属性?

```json

"pluginsConfig": {

"fontsettings": {

"theme": "sepia",

"family": "serif",

"size": 1

}

}1234567

```

上面就是配置Gitbook界面那个`A`按钮的默认属性。

### structure?

指定 Readme、Summary、Glossary 和 Languages 对应的文件名，下面是这几个文件对应变量以及默认值：

| 变量 | 含义和默认值 |

| --------------------- | ---------------------------------------------- |

| `structure.readme` | `Readme file name (defaults to README.md)` |

| `structure.summary` | `Summary file name (defaults to SUMMARY.md)` |

| `structure.glossary` | `Glossary file name (defaults to GLOSSARY.md)` |

| `structure.languages` | `Languages file name (defaults to LANGS.md)` |

## GitBook插件?

可以指定插件的版本可以使用 `plugin@0.3.1` ，下面的插件在 GitBook 的 `3.2.3` 版本中可以正常工作，[插件官网](https://plugins.gitbook.com/)。

具体介绍看这里：https://github.com/zhangjikai/gitbook-use/blob/master/plugins.md

- Summary插件：`npm install -g gitbook-summary`

- `book sm`，一个完整的目录文件`SUMMARY.md`就生成了，之后根据自己的需要修改，进一步的命令就不需要了。

## 主题?

我们常用的就是 Book 文档模式，所以只看这部分。

### theme-default?

默认的 Book 主题。将 `showLevel` 设为 `true`，就可以显示标题前面的数字索引，默认不显示。

```json

{

"theme-default": {

"showLevel": true

}

}12345

```

### theme-comscore?

这个主题为标题添加了颜色

```json

{

"plugins": [

"theme-comscore"

]

}12345

```

## book.json配置文件?

### SUMMARY.md

这个文件主要决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系，下面是一个简单的示例：

```csharp

# Summary

* [目录](README.md)

* [第一章](notes/1-0.md)

* [第1节：](notes/1-1.md)

* [第2节：](notes/1-2.md)

* [第3节：](notes/1-3.md)

* [第4节：](notes/1-4.md)

* [第二章](notes/2-0.md)

* [第三章](notes/3-0.md)

* [第四章](notes/4-0.md)

```

这个配置对应的目录结构如下所示:

我们通过使用 `标题` 或者 `水平分割线` 将 GitBook 分为几个不同的部分，如下所示：

```csharp

# Summary

### Part I

* [目录](README.md)

### Part II

* [第一章](notes/1-0.md)

* [第1节：](notes/1-1.md)

* [第2节：](notes/1-2.md)

* [第3节：](notes/1-3.md)

* [第4节：](notes/1-4.md)

---

* [第二章](notes/2-0.md)

---

* [第三章](notes/3-0.md)

---

* [第四章](notes/4-0.md)

```

## 五、用 Git 做版本管理（需要安装插件）

GitBook 有 [插件官网](https://links.jianshu.com/go?to=https%3A%2F%2Fplugins.gitbook.com%2F)，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload，如果要去除自带的插件，可以在插件名称前面加 `-`，比如：

```bash

"plugins": [

"-search"

]

```

如果要配置使用的插件可以在 book.json 文件中加入即可，比如我们添加 [plugin-github](https://links.jianshu.com/go?to=https%3A%2F%2Fplugins.gitbook.com%2Fplugin%2Fgithub)，我们在 book.json 中加入配置如下即可：

```json

{

"plugins": [ "github" ],

"pluginsConfig": {

"github": {

"url": "https://github.com/13469940053/Web_notes"

}

```

然后在终端输入 `gitbook install ./` 即可。

如果要指定插件的版本可以使用 plugin@0.3.1，因为一些插件可能不会随着 GitBook 版本的升级而升级。

# 六、上传到静态服务托管平台

在远端建好git仓库，在 mybook 目录下执行 `git init` 初始化仓库，执行 `git remote add` 添加远程仓库。接着就可以愉快地 commit，push，pull …

## 六、结语

这是我对 GitBook 使用的总结，希望能帮到今后需要的小伙伴。

------