Gitbook使用教程

# Gitbook使用教程

## 一炸裆、GitBook 簡介

gitbook 是一個(gè)基于node.js命令的工具誓禁，可以使用網(wǎng)絡(luò)常見的github|git和Markdown來制作精美的電子書，而且和typora軟件搭配是一款非常好的筆記記錄軟件吱抚，下面我們一起來了解它的入門需知吧

- 語法簡單

- 兼容性強(qiáng)

- 導(dǎo)出方便

- 專注內(nèi)容

- 團(tuán)隊(duì)協(xié)作

## 二、安裝

### 安裝軟件：Git丐重、Typora

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

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

### 安裝 Node.js

GitBook 是一個(gè)基于 Node.js 的命令行工具捅位，下載安裝 [Node.js]https://nodejs.org/zh-cn/)轧葛，安裝完成之后，你可以使用下面的命令來檢驗(yàn)是否安裝成功艇搀。

```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 —— 書籍的介紹寫在這個(gè)文件里

>? ? ? SUMMARY.md —— 書籍的目錄結(jié)構(gòu)在這里配置

### 3.啟動(dòng)Typora編輯器衷笋，引入文件夾

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

### 4.編輯`SUMMARY.md`

```bash

# Summary

* [目錄](README.md)

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

? ? * [第1節(jié)：](notes/1-1.md)

? ? * [第2節(jié)：](notes/1-2.md)

? ? * [第3節(jié)：](notes/1-3.md)

? ? * [第4節(jié)：](notes/1-4.md)

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

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

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

```

### 5.再次執(zhí)行`gitbook init`，生成新目錄結(jié)構(gòu)

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

### 6.瀏覽器瀏覽：`gitbook serve`

```bash

gitbook serve

```

執(zhí)行 `gitbook serve` 來預(yù)覽這本書籍矩屁，執(zhí)行命令后會(huì)對(duì) Markdown 格式的文檔進(jìn)行轉(zhuǎn)換辟宗，默認(rèn)轉(zhuǎn)換為 html 格式，最后提示 “Serving book on [http://localhost:4000](http://localhost:4000/)”

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

### 7.構(gòu)建書籍：`gitbook build`

```bash

gitbook build

```

- [x] 默認(rèn)：將生成的靜態(tài)網(wǎng)站輸出到 _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 進(jìn)行導(dǎo)出晨抡。

## 8.gitbook附加命令

```bash

npm i -g gitbook-cli |? npm install gitbook-cli -g? //安裝環(huán)境

gitbook init //初始化目錄文件

gitbook help //列出gitbook所有的命令

gitbook --help //輸出gitbook-cli的幫助信息

gitbook build //生成靜態(tài)網(wǎng)頁

gitbook serve //生成靜態(tài)網(wǎng)頁并運(yùn)行服務(wù)器

gitbook build --gitbook=2.0.1 //生成時(shí)指定gitbook的版本, 本地沒有會(huì)先下載

gitbook ls //列出本地所有的gitbook版本

gitbook ls-remote //列出遠(yuǎn)程可用的gitbook版本

gitbook fetch 標(biāo)簽/版本號(hào) //安裝對(duì)應(yīng)的gitbook版本

gitbook update //更新到gitbook的最新版本

gitbook uninstall 2.0.1 //卸載對(duì)應(yīng)的gitbook版本

gitbook build --log=debug //指定log的級(jí)別

gitbook builid --debug //輸出錯(cuò)誤信息1234567891011121312345678910111213

```

## 四、目錄結(jié)構(gòu) 插件信息

GitBook 基本的目錄結(jié)構(gòu)如下所示：

```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": "文件修訂時(shí)間：",

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

? ? },

? ? "disqus": {

? ? ? "shortName": "gitbookuse"

? ? }

? }

}

```

### 配置說明

| 變量? ? ? ? ? | 描述? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? |

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

| root? ? ? ? ? | 包含所有圖書文件的根文件夾的路徑耘柱，除了 book.json? ? ? ? ? ? |

| structure? ? | 指定自述文件，摘要棍现，詞匯表等的路徑? ? ? ? ? ? ? ? ? ? ? ? ? |

| title? ? ? ? | 您的書名调煎，默認(rèn)值是從 README 中提取出來的。在 GitBook.com 上己肮，這個(gè)字段是預(yù)填的士袄。 |

| description? | 您的書籍的描述，默認(rèn)值是從 README 中提取出來的谎僻。在 GitBook.com 上娄柳，這個(gè)字段是預(yù)填的。 |

| author? ? ? ? | 作者名艘绍。在GitBook.com上赤拒，這個(gè)字段是預(yù)填的。? ? ? ? ? ? ? ? ? |

| isbn? ? ? ? ? | 國際標(biāo)準(zhǔn)書號(hào) ISBN? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? |

| language? ? ? | 本書的語言類型 —— [ISO code](https://links.jianshu.com/go?to=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FList_of_ISO_639-1_codes) 。默認(rèn)值是 `en` |

| direction? ? | 文本閱讀順序挎挖≌饩矗可以是 rtl （從右向左）或 ltr （從左向右），默認(rèn)值依賴于 language 的值蕉朵。 |

| gitbook? ? ? | 應(yīng)該使用的GitBook版本崔涂，并接受類似于 `>=3.0.0` 的條件。? ? ? |

| links? ? ? ? | 在左側(cè)導(dǎo)航欄添加鏈接信息? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? |

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

| pluginsConfig | 插件的配置? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? |

### 默認(rèn)插件

- highlight - 語法高亮插件

- search - 搜索插件

- sharing - 分享插件

- font-settings - 字體設(shè)置插件

- livereload - 熱加載插件

該文件主要用來存放配置信息始衅，我先放出我的配置文件冷蚂。

相信很多節(jié)點(diǎn)自己也能猜到是什么意思，我還是簡單介紹下吧觅闽。

搜索

![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)

### 刪除默認(rèn)插件

在平時(shí)開發(fā)中比如分享給出的都是一些國外的社交網(wǎng)站對(duì)于我們沒太大用戶那么我們可以刪除默認(rèn)配置

在插件配置在加`-`,配置完執(zhí)行`gitbook install`即可

```json

"plugins": [

? ? "-sharing"

? ]

123

```

效果如下：

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

右側(cè)不再展示分享相關(guān)的按鈕

### 常用配置

#### 代碼復(fù)制

```js

"plugins": [

? ? "code"

? ]

123

```

效果如下：

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

代碼復(fù)制按鈕

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

```

和上面一樣都是折疊目錄的帝雇，區(qū)別就是下面的箭頭要細(xì)一些。

效果如下：

![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)

#### 高級(jí)搜索

去除默認(rèn)的search搜索和lunr蛉拙，在搜索結(jié)果中尸闸，關(guān)鍵字會(huì)高亮；自帶的 search 插件孕锄，關(guān)鍵字不會(huì)高亮

```js

"plugins": [

? ? ? ? ? "-lunr",

? ? ? ? ? "-search",

? ? ? ? ? "search-pro"

? ? ]

12345

```

原生搜索效果：

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

高級(jí)搜索：

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

搜索關(guān)鍵字高亮吮廉，支持中文、拼音和英文

#### 分享

分享當(dāng)前頁面畸肆，比默認(rèn)的 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

```

參數(shù)配置里面true的默認(rèn)展示圖標(biāo)宦芦，false的默認(rèn)不展示；all里面的會(huì)在分享按鈕的下拉列表里面全部展示出來轴脐。

效果如下：

![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": "文件修訂時(shí)間：",

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

? ? ? ? }

? ? }

12345678910

```

效果如下：

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

### title：設(shè)置書本的標(biāo)題?

```json

"title" : "Gitbook Use"

```

### author：作者的相關(guān)信息?

```

"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：左側(cè)導(dǎo)航欄添加鏈接信息?

```json

"links" : {

? ? "sidebar" : {

? ? ? ? "個(gè)人主頁" : "http://www.ds-vip.top"

? ? }

}12345

```

### styles：自定義頁面樣式?

默認(rèn)情況下各`generator`對(duì)應(yīng)的`css`文件：

```json

"styles": {

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

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

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

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

? ? "epub": "styles/epub.css"

}1234567

```

例如使` `標(biāo)簽有下邊框调卑，可以在`website.css`中設(shè)置，這個(gè)可以有大咱。

```css

h1 , h2{

? ? border-bottom: 1px solid #EFEAEA;

}123

```

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

```j'so

"plugins": [

? ? "disqus"

]123

```

- 例如上面添加`disqus`插件：之后需要運(yùn)行`gitbook install`來安裝新的插件恬涧。

- Gitbook默認(rèn)帶有5個(gè)插件：highlight、search碴巾、sharing溯捆、font-settings、livereload

- 如果要去除自帶的插件厦瓢，可以在插件名稱前面加`-`：

```json

"plugins": [

? ? "-search"

]123

```

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

```json

"pluginsConfig": {

? ? "fontsettings": {

? ? ? ? "theme": "sepia",

? ? ? ? "family": "serif",

? ? ? ? "size":? 1

? ? }

}1234567

```

上面就是配置Gitbook界面那個(gè)`A`按鈕的默認(rèn)屬性提揍。

### structure?

指定 Readme、Summary煮仇、Glossary 和 Languages 對(duì)應(yīng)的文件名劳跃，下面是這幾個(gè)文件對(duì)應(yīng)變量以及默認(rèn)值：

| 變量? ? ? ? ? ? ? ? ? | 含義和默認(rèn)值? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? |

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

| `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` 版本中可以正常工作浙垫，[插件官網(wǎng)](https://plugins.gitbook.com/)售碳。

具體介紹看這里：https://github.com/zhangjikai/gitbook-use/blob/master/plugins.md

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

- `book sm`，一個(gè)完整的目錄文件`SUMMARY.md`就生成了，之后根據(jù)自己的需要修改贸人，進(jìn)一步的命令就不需要了。

## 主題?

我們常用的就是 Book 文檔模式佃声，所以只看這部分艺智。

### theme-default?

默認(rèn)的 Book 主題。將 `showLevel` 設(shè)為 `true`圾亏，就可以顯示標(biāo)題前面的數(shù)字索引十拣，默認(rèn)不顯示。

```json

{

? ? "theme-default": {

? ? ? ? "showLevel": true

? ? }

}12345

```

### theme-comscore?

這個(gè)主題為標(biāo)題添加了顏色

```json

{

"plugins": [

? ? ? ? "theme-comscore"

? ? ]

}12345

```

## book.json配置文件?

### SUMMARY.md

這個(gè)文件主要決定 GitBook 的章節(jié)目錄志鹃，它通過 Markdown 中的列表語法來表示文件的父子關(guān)系夭问，下面是一個(gè)簡單的示例：

```csharp

# Summary

* [目錄](README.md)

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

? ? * [第1節(jié)：](notes/1-1.md)

? ? * [第2節(jié)：](notes/1-2.md)

? ? * [第3節(jié)：](notes/1-3.md)

? ? * [第4節(jié)：](notes/1-4.md)

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

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

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

```

這個(gè)配置對(duì)應(yīng)的目錄結(jié)構(gòu)如下所示:

我們通過使用 `標(biāo)題` 或者 `水平分割線` 將 GitBook 分為幾個(gè)不同的部分，如下所示：

```csharp

# Summary

### Part I

* [目錄](README.md)

### Part II

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

? ? * [第1節(jié)：](notes/1-1.md)

? ? * [第2節(jié)：](notes/1-2.md)

? ? * [第3節(jié)：](notes/1-3.md)

? ? * [第4節(jié)：](notes/1-4.md)

---

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

---

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

---

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

```

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

GitBook 有 [插件官網(wǎng)](https://links.jianshu.com/go?to=https%3A%2F%2Fplugins.gitbook.com%2F)缰趋，默認(rèn)帶有 5 個(gè)插件，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柑肴，因?yàn)橐恍┎寮赡懿粫?huì)隨著 GitBook 版本的升級(jí)而升級(jí)。

# 六韧骗、上傳到靜態(tài)服務(wù)托管平臺(tái)

在遠(yuǎn)端建好git倉庫嘉抒，在 mybook 目錄下執(zhí)行 `git init` 初始化倉庫，執(zhí)行 `git remote add` 添加遠(yuǎn)程倉庫袍暴。接著就可以愉快地 commit些侍，push，pull …

## 六政模、結(jié)語

這是我對(duì) GitBook 使用的總結(jié)岗宣，希望能幫到今后需要的小伙伴。

------