# 构建自己的电子书-基于GitBook

# 一、GitBook简介

# 1.1 GitBook是什么？

官方给的定义：
- GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).
GitBook 是基于 Node.js 的开源命令行工具，用于输出漂亮的电子书。
GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，能够输出 html，pdf，epub，mobi等多种格式。

# 1.2 GitBook 特性

Markdown 或 AsciiDoc 语法
多类型支持：网站(html)或电子书 (pdf, epub, mobi)
多语言
目录、大纲
封面
模板和变量
模板继承
插件
主题

# 1.3 缺陷

开源项目停止维护
- 活跃的开源项目，意味着不断完善的功能，不断修复bug，及时的反馈，更多社区的帮助...遗憾的是，GitBook开源项目已经停止维护，专注打造的 gitbook.com 网站在国内访问受限。
移动端不适配
- 现在有PC端的流量已经赶不上移动端了，但是 GitBook 对移动设备的支持不太友好。虽然正文部分做到了 responsive，但是菜单栏没有做移动端适配。大部分插件也没有考虑移动端的情形。

# 二、GitBook安装教程

# 2.1 安装环境

GitBook的安装非常简单。您的系统只需满足这两个要求：
1. NodeJS（推荐使用v4.0.0及以上版本）
2. Windows，Linux或Mac OS X
本教程安装环境
- NodeJS (v10.23.1) 最新版本或者较高版本的会报错
- Mac OS Monterey (v12.0.1 M1芯片)
- nvm（v0.39.0）

# 2.2 使用homebrew安装 nvm

创建nvm文件夹
```
mkdir ~/.nvm
```
执行安装命令
```
brew install nvm
```
编辑.zshrc文件
```
vim ~/.zshrc 
```

ps：配置的信息，在你执行安装命令的时候会提示，拷贝对应的信息写入配置文件即可。

更新配置文件：
```
source ~/.zshrc
```
查看版本信息
```
nvm -v
```

# 2.3 使用nvm安装 Node.js

执行安装命令
```
nvm install 10.23.1
```

安装报错

error: Target architecture arm64 is only supported on arm64 and x64 host

解决方案

执行命令：arch -x86_64 zsh

重新安装node命令： nvm install 10.23.1
查看版本信息
```
node -v
```

# 2.3.1 Node.镜像配置

Node.js 安装完成后，我们就可以开始安装 gitbook 了。但是在安装之前，最好先配置一下Node.js 源的下载镜像地址。
因为默认的镜像地址是在国外，国内访问速度极慢，因此我们需要设置国内的镜像地址。国内的我推荐大家使用阿里巴巴的镜像地址 http://registry.npm.taobao.org 。

执行下面的命令，进行配置：

npm config set registry http://registry.npm.taobao.org

# 2.4 安装GitBook

执行安装命令：
```
npm install gitbook-cli -g
```
gitbook-cli 是安装和管理GitBook版本库的程序。它会自动安装GitBook所需的模块来创建一本书。
查看版本信息自动安装gitbook
```
gitbook -V
```
查看版本信息
```
gitbook -V
```

# 三、GitBook基础命令

这里主要介绍一下 GitBook 的命令行工具 gitbook-cli 的一些命令, 首先说明两点:
1. gitbook-cli 和 gitbook 是两个软件
2. gitbook-cli 会将下载的 gitbook 的不同版本放到 ~/.gitbook中, 可以通过设置GITBOOK_DIR环境变量来指定另外的文件夹

# 3.1 初始化 gitbook

gitbook init

该命令主要用户初始化 book，创建必要的 README 和 SUMMARY 文件

# 3.2 输出gitbook的帮助信息

gitbook help

# 3.3 输出gitbook-cli的帮助信息

gitbook --help

# 3.4 下载所需的资源，如插件等

gitbook install

如果插件比较多，下载会花很长时间。可以用 npm install plugin-xxx 这种方式单个下载插件。

# 3.5 生成静态网页

gitbook build

运行完该命令后，会在当前文件夹中生成一个 _book文件夹，其中就是解析出来的静态网站，包含了点子书中的所有信息。可以将它直接放置在如 nginx 、apache server 、tomcat等服务器中直接运行。
用浏览器直接打开生成的 html 文件是可以的，但是无法完成基本的交互。

# 3.6 生成静态网页并运行服务器

gitbook serve

用浏览器直接访问 http://localhost:4000/，就可以看到生成的电子书网站。

# 3.7 生成时指定gitbook的版本, 本地没有会先下载

gitbook build --gitbook=2.0.1

# 3.8 列出本地所有的gitbook版本

gitbook ls

# 3.9 列出远程可用的gitbook版本

gitbook ls-remote

# 3.10 查询版本号

gitbook -V

gitbook --version

# 3.11 安装对应的gitbook版本

gitbook fetch 标签/版本号

# 3.12 更新到gitbook的最新版本

gitbook update

# 3.13 卸载对应的gitbook版本

gitbook uninstall 2.0.1

# 3.14 指定log的级别

gitbook build --log=debug

# 3.15 输出错误信息

gitbook build --debug

# 四、 Markdown

# 4.1 什么是Markdown？

Markdown 是一种方便记忆、书写的纯文本标记语言，用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档：譬如您正在阅读的这份文档。它使用简单的符号标记不同的标题，分割不同的段落，粗体或者斜体某些文字，更棒的是，它还支持高亮一段代码、绘制表格等等一些高阶功能。

# 4.2 Markdown 编辑器

Markdown 编辑器非常多，根据使用场景不同，大致可以分为3类：
1. 平台集成：博客系统，如简书、CSDN等
2. 专业软件：Mou(Mac)、MarkdownPad(Win)、Typora(多平台)、Dillinger(网页版)等
3. 插件集成：有些软件本身不支持 Markdown，但可以通过插件完美兼容 Markdown 语法，如 Sublime Text、VS code等
选择顺手的、适合自己的编辑器，能大大提高码字效率。

# 4.3 Markdown 简明语法

Markdown教程菜鸟教程 (opens new window)

# 4.3.1 斜体和粗体

使用 *或者_ 和 **或者__ 表示斜体和粗体。

示例：

这是 *斜体*
这是 _斜体_
这是 **粗体**
这是 __粗体__
_斜体**中间**加粗_

这是斜体这是斜体这是粗体这是粗体 斜体中间加粗

# 4.3.2 分级标题

在行首加井号表示不同级别的标题 (H1-H6)，例如：# H1, ## H2, ### H3，#### H4。

示例：

# 这是1个#号的标题
## 这是2个#号的标题
### 这是3个#号的标题
#### 这是4个#号的标题
##### 这是5个#号的标题
###### 这是6个#号的标题

# 这是1个#号的标题

# 这是2个#号的标题

# 这是3个#号的标题

# 这是4个#号的标题

# 这是5个#号的标题

# 这是6个#号的标题

# 4.3.3 外链接

使用 [描述](链接地址) 为文字增加外链接。

示例：

这是去往 [blog](http://blog.keepdive.com) 的链接。

这是去往 blog (opens new window) 的链接。

# 4.3.4 无序列表

使用 *，+，- 表示无序列表。

示例：

- 无序列表项 一
- 无序列表项 二
- 无序列表项 三

无序列表项一
无序列表项二
无序列表项三

# 4.3.5 有序列表

使用数字和点表示有序列表。

示例：

1. 有序列表项 一
2. 有序列表项 二
3. 有序列表项 三

有序列表项一
有序列表项二
有序列表项三

# 4.3.6 文字引用

使用 > 表示文字引用。
示例：
```
> 野火烧不尽，春风吹又生。
```
野火烧不尽，春风吹又生。

# 4.3.7 行内代码块

使用`代码` 表示行内代码块。
示例：
```
让我们聊聊 `html`。
```
让我们聊聊 html。

# 4.3.8 代码块

使用 四个缩进空格或者tab 表示代码块。

示例：

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

# 4.3.9 插入图片

使用 ![描述](图片链接地址) 插入图像。
示例
```
![图片](chaozhitehui.png)
```

# 4.3.10 删除线

使用 ~~ 表示删除线。
示例
```
~~这是一段错误的文本。~~
```

~~这是一段错误的文本。~~

# 4.3.11 加强的代码块

代码示例

    public class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello World");
        }
    }

# 4.3.12 表格支持

示例：

| 项目        | 价格   |  数量  |
| --------   | -----:  | :----:  |
| Java     | \$160 |   5     |
| PHP        |   \$120   |   12   |
| Javascript        |    \$210    |  23  |

项目	价格	数量
Java	$160	5
PHP	$120	12
Javascript	$210	23

#

# 4.3.13.分隔线

使用三个或多个星号、中划线、下划线创建分隔线

示例：

三个或更多...
--- ---
中划线
***
星号
___
下划线

中划线

星号

下划线

# 4.3.14 Html 标签

如果上面的语法还不能满足你，甚至可以在 Markdown 语法中嵌套 Html 标签。 HTML中的Markdown语法不会解析。譬如，你可以用 Html 写一个纵跨两行的表格：

<table>
    <tr>
        <th rowspan="2">值班人员</th>
        <th>星期一</th>
        <th>星期二</th>
        <th>星期三</th>
    </tr>
    <tr>
        <td>李强</td>
        <td>张**</td>
        <td>王*</td>
    </tr>
</table>

值班人员	星期一	星期二	星期三
值班人员	李强	张**	王*

# 4.3.15 忽略Markdown格式

如果需要忽略Markdown格式，也就是转义Markdown的关键字，只需要在Markdown关键字前使用反斜杠 \ 即可。

示例：

我不想让\*\*星号被解析\*\*，下划线 \_和下划线\_ 中的文字也不需要处理。

我不想让*星号被解析*，下划线 _和下划线_ 中的文字也不需要处理。

# 五、构建第一本电子书

# 5.1 初始化环境

现在，需要在一个空文件夹中创建自己的一本书。
创建.MyBook文件夹
```
mkdir ~/.MyBook
```
在该文件(~/.MyBook)下执行命令：
```
gitbook init
```
自动创建了两个文件：
- README.md和SUMMARY.md

# 5.2 添加说明到 README.md

# 第一本GitBook

本书由 gitbook 生成。

# 5.3 添加一个 markdown 文件

新建了一个 hello.md 的文件
```
touch hello.md
```

并写入如下内容。

# Hello World

### 欢迎语

欢迎你来到 GitBook 的世界，希望这里有你想要的东西。

# 5.4 添加菜单到 SUMMARY.md


# Summary

* [Introduction](README.md)

* [Hello](hello.md)

# 5.5 启动服务

在终端输入命令

gitbook serve

看到这样的输出，直接在浏览器访问 http://localhost:4000/

# 5.6 文件目录分析

现在去主文件夹(/Users/mike/.MyBook)看可以看到新生成了一个文件夹 _book
- 总体文件结构

.
├── _book
├── hello.md
├── README.md
└── SUMMARY.md

打开文件夹 _book
- 内部文件结构

.
├── gitbook
|    ├── fonts
|    ├── gitbook-plugin-fontsettings
|    ├── gitbook-plugin-highlight
|    ├── gitbook-plugin-livereload
|    ├── gitbook-plugin-lunr
|    ├── gitbook-plugin-search
|    ├── gitbook-plugin-sharing
|    ├── images
|       ├── apple-touch-icon-precomposed-152.png
|       └── favicon.ico
|    ├── gitbook.js
|    ├── style.css
|    └── theme.js
├── hello.html
├── index.html
└── search_index.json

这个文件夹 _book 中包含了点子书中的所有内容，将整个文件夹打包放在任何一个 web 服务器中，都能正常显示。这是个非常简单的例子，之后通过 book.json的配置和插件的扩展，能实现更多个性化的功能。

# 六、 GitBook目录结构

GitBook使用SUMMARY文件管理目录结构，文件支持 Markdown 和 Asciidoc 两种语法。之后的演示都是基于 Markdown 语法。

一个经典的 gitbook 文件目录如下：

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

每一项简单的说明：

文件	重要性	说明
book.json	可选，非常重要	保存配置文件数据
README.md	必选，重要	简介，书籍的简单介绍
SUMMARY.md	可选，非常重要	目录，控制左边侧边栏

接下来，会详细说明每一种文件的作用。

# 6.1、book.json配置文件

没有 book.json 这个文件，也能正常出书。如果你需要个性化添加一些功能，就需要它来配置各种参数。如果需要这个文件来配置参数，需要手动创建一个 book.json文件。它必须是标准的 json 文件，格式错误将导致出书失败。

简单的 book.json 文件示例：

{
    "title": "Hello world",   // 书的标题
    "language":"en",          // 语言
    "plugins": [              // 插件
        "code",               // 添加了一个插件
        "-search"             // 去掉了一个插件
    ],
    "pluginsConfig": {        // 插件的配置
        "code": {             // code 插件配置了一个参数
            "copyButtons": true
        }
    }
}

book.json文件是唯一一个 gitbook 的配置文件。所有的配置都以JSON格式存储在名为 book.json 的文件中。
所有的参数都通过该文件传递，因此，配置项比较多。

# 6.1.1 title

设置书本的标题
```
"title" : "Gitbook 使用"
```

# 6.1.2 author

作者的相关信息
```
"author" : "mike"
```

# 6.1.3 description

本书的简单描述，默认是从 README（第一段）中提取的。
```
"description" : "Gitbook的配置和使用"
```

# 6.1.4 language

Gitbook使用的语言, 版本2.6.4中可选的语言如下：

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

配置使用简体中文

"language" : "zh-hans"

# 6.1.5 gitbook

这个选项是用来指定生成书本的GitBook的版本的。
```
"gitbook" : "3.2.2",
"gitbook" : ">=3.0.0"
```

# 6.1.6 root

指定存放 GitBook 文件（除了 book.json）的根目录
```
"root": "."
"root": "./docs"
```

# 6.1.7 links

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

{"links" : {
    "sidebar" : {
        "首页" : "https://blog.keepdive.com"
    }
}}

# 6.1.8 styles

自定义页面样式，默认情况下各generator对应的css文件

{"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}}

例如使 <h1> <h2>标签有下边框，可以在 website.css 中设置
```
h1 , h2{
    border-bottom: 1px solid #EFEAEA;
}
```

# 6.1.9 plugins

配置使用的插件
```
{
"plugins": [
    "github"
]}
```
添加新插件之后需要运行 gitbook install 来安装新的插件
Gitbook默认带有7个插件：
1. livereload 热加载插件
2. highlight 语法高亮插件
3. search 搜索插件
4. lunr 搜索插件后台服务
5. sharing 分享插件
6. fontsettings 字体设置插件
7. theme-default 主题
如果要去除自带的插件，可以在插件名称前面加 - 移除搜索 search 插件：
```
{
"plugins": [
    "-search"
]}
```

# 6.1.10 pluginsConfig

配置插件的属性

{"pluginsConfig": {
    "fontsettings": {
        "theme": "sepia",
        "family": "serif",
        "size":  1
    }
}}

# 6.1.11 structure

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

变量	含义	默认值
structure.readme	Readme file name	README.md
structure.summary	Summary file name	SUMMARY.md
structure.glossary	Glossary file name	GLOSSARY.md
structure.languages	Languages file name	LANGS.md

# 6.1.12 variables

这个选项定义在模板中使用的变量值。

{
    "variables": {
        "firstbook": "Hello World"
    }
}

# 6.2 README.md 文件

README.md是 gitbook 最基础的文件之一，它一般用来描述这本书最基本的信息。它呈现给读者这本书最初的样子，如果内容不够简洁明了，很可能就没有看下去的欲望了。可以通过 gitbook init 自动创建该文件。
使用其他文件替代README.md
一些项目更愿意将 README.md 文件作为项目的介绍而不是书的介绍。大部分代码托管平台将 README.md 自动显示到项目首页，如果你不喜欢这样。从GitBook >2.0.0 起，就可以在 book.json 中定义某个文件作为README。
```
{
    "structure" : {
        "readme" : "information.md"
    }
}
```

# 6.3 SUMMARY.md 文件

GitBook使用一个SUMMARY.md文件来定义文档的菜单。虽说在官方文档中，它是可选的，但是它相当重要，控制了左边菜单栏的显示内容。它通过 Markdown 中的列表语法来表示文件的父子关系。

紧凑型的

# Summary

### Part I

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

### Part II

* [feedback](part2/feedback.md)
* [tools](part2/tools.md)

----

* [Last part](part3/last.md)

分散型的

也可以通过使用标题或者水平分割线标志将 GitBook 分为几个不同的部分。你看到左侧菜单栏的部分 SUMMARY.md文件

# Summary

### Part I

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

### Part II

* [feedback](part2/feedback.md)
* [tools](part2/tools.md)

----

* [Last part](part3/last.md)

自动生成
如果你的 md 文件是少量的，自己编写 SUMMARY.md 文件当然不费事。但是 md 文件数量非常多时，你可能希望自动生成这些内容，可以参见插件 summary 部分关于自动生成菜单 summary 文件的介绍。

← 三、使用腾讯云COS+PicGO搭建Hexo博客图床教程基于frp实现内网穿透 →