Gitbook安装与设置
Windows系统
安装 Gitbook 需要 nodejs 环境，请事先安装并配置 nodejs 环境，这里就不多做讲解了，您可以移步到作者的相关文章中查看：使用nvm管理node和npm 和 解压版的nodejs安装与配置
配置与安装
安装并配置 nodejs 环境之后，通过 node -v 命令验证没有问题之后就可以进行 Gitbook 的安装了。前提必须要说一下，请使用系统管理员打开 CMD 控制窗口，步骤如下：
-
使用 npm 命令安装 gitbook-cli，它是在同一系统上安装和使用多个版本的 Gitbook 的实用程序，它将自动安装所需版本的 Gitbook 程序。命令如下：
#可能需要一些时间，耐心等待 npm install -g gitbook-cli -
上一步执行完毕后，通过 gitbook -V 命令查看是否安装成功，注意 V 是大写。命令如下：
#这一步时间超级长，不要认为你机器有问题或者网络有问题 #有报错或者警告也别管，死等即可，出去溜一圈就行 gitbook -V切记，一定要死等结束，真的非常慢这一步。
-
等上一步执行完了再执行一遍 gitbook -V 命令就会立刻列出相应的信息，到这里 Gitbook 是安装完毕了。
使用 Gitbook 创建并管理书
Gitbook 安装完毕就可以创建自己的本地书籍了，在指定地方创建个文件夹（名字自定义即可，英文），CMD 控制台 cd 进入刚才创建的文件夹目录，进行初始化。命令如下：
gitbook init
执行完了 gitbook init 命令，会在刚才的文件夹目录下生成两个文件：README.md 和 SUMMARY.md，这两个文件不能删除，也不能改名。其中 README.md 是说明文件，SUMMARY.md 是目录文件。
既然都是 md 类型的文件，就可以用 Markdown 编辑对它们进行编辑，选什么编辑器看个人喜好，作者用的是 Typora。
下面对 Gitbook 进行详解讲解。
目录结构
一般情况下目录结构如下：
.
├── book.json
├── README.md
├── SUMMARY.md
├── GLOSSARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
目录文件的主要功能：
| 文件名 | 描述 |
|---|---|
| book.json | 配置数据 (可选)，但是作者认为必须得有，个人习惯 |
| README.md | 电子书的前言或简介 (必需) |
| SUMMARY.md | 电子书目录 (作者认为它必须存在) |
| GLOSSARY.md | 词汇/注释术语列表 (可选)，作者从没用过 |
菜单结构
一个本的菜单什么样的，取决于 SUMMARY.md 文件，这就是刚才作为为什么认为它必须存在的原因。
- 指定菜单项目的标题。
- ( ) 指定菜单文章文件的路径。
- 支持子目录的方式，章节和子章节用 tab 键来分级。
- # 或者 — 进行不同 Part 的分类，分别由标题或者水平分割线方式表示不同的部分。
- 区域导航定位，在章节 路径 md 文件结尾使用 # 号加上文章内容中章节的标题就能实现区域导航。
写了这么多，我觉得只要会 Markdown 语法，没有任何难度。如下：
# Summary
### 第I部分
* [第I部分](part1/README.md)
* [标题1](part1/README.md#one)
* [标题2](part1/README.md#two)
### 第II部分
* [第II部分](part2/README.md)
* [标题1](part2/README.md#one)
* [标题2](part2/README.md#two)
----
* [第III部分](part3/three.md)
以上内容仅供参考。
页面文件
Gitbook 书籍的页面文件采用的 Markdown 语法实现的，所以只要你懂 Markdown 语法就可以编辑对应的页面按文件。具体的相关的 Markdown 语法不熟悉的可以参考：菜鸟教程，MarkDown中文网 或者其它的参考网站。
其它
其它还包括一些细节配置，作者认为没有什么必要可描述的。比如页面顶部可以使用 YAML 格式来定义描述信息，这不是必须的，有兴趣的可以自行搜索。再比如专业术语，忽略文件等等配置，作者也没用上，所以还是请您自行搜索。
配置和说明（book.json文件）
Gitbook 还有一些配置可进行设置，主要集中在 book.json 文件中，既然是 json 文件，请一定存储 json 语法格式要求（有注释信息好像也不行），否则在生成 Gitbook 书的时候会报错。
注意：在创建 book.json 文件时，请一定将 book.json 文件保存为 UTF-8 编码格式的，要不中文信息在生成书籍的时候会出现乱码。
具体的 book.json 文件中的配置概览，如下：
| 变量 | 说明 |
|---|---|
| root | 包含所有图书文件的根文件夹的路径，除了 book.json 文件 |
| title | 书籍的标题，默认值从README中提取 |
| description | 籍说明，默认值从自述文件中提取，其实就是生成html里面的那个meta描述 |
| author | 作者姓名，其实就是生成html里面的那个meta作者描述 |
| isbn | 书籍的国际码ISBN |
| language | 语言规范中的语言规范定义，默认值是 en，汉字选用 zh-hans |
| gitbook | GitBook 的版本，使用 SemVer 规范并接受诸如 “>=3.0.0” 的条件 |
| structure | 指定自述，摘要，词汇表等的路径 |
| variables | 这个选项定义书籍中的变量，就是自定义变量 |
| links | 在左侧导航栏最上添加指定的自定义链接 |
| styles | 用来自定义书本的 css |
| plugins | 指定书籍使用的插件列表 |
| pluginsConfig | 配置指定插件的一些配置信息 |
| 导出 PDF 文件的一些配置信息 |
基础配置
参考如下：
{
"root":".",
"author":"Lee",
"title":"Lee Gitbook",
"language":"zh-hans",
"description":"This is gitbook",
"isbn":"000-0-00-000000-0",
"direction":"ltr",
"gitbook":">=3.2.3"
}
structure 结构配置
| 变量 | 说明 |
|---|---|
| structure.readme | 自述文件名（默认为“README.md”） |
| structure.summary | 摘要文件名（默认为“SUMMARY.md”） |
| structure.glossary | 词汇表文件名（默认为“GLOSSARY.md”），作者没用过 |
| structure.languages | 语言文件名（默认为LANGS.md)，作者没用过 |
参考如下：
{
"structure":{
"readme":"README.md",
"summary":"SUMMARY.md"
}
}
variables 变量配置
定义一些书籍中的变量信息，定义在 book.json 中的变量可以在 book 作用域下被访问，如：{{ book.blog }} 双括号语法在书籍中获取其中的数值（说实话用的不多，作者也没用过，个人认为可有可无）。
参考如下：
{
"variables":{
"blog":"https://blog.csdn.net/lili40342"
}
}
links 链接导航
通过 links 配置在左侧导航栏添加指定的链接导航，如：添加自己的博客链接，GIthub链接等等…
参考如下：
{
"links": {
"sidebar": {
"CSDN": "https://blog.csdn.net/lili40342",
"Gitee": "https://gitee.com/lili40342"
}
}
}
styles 自定义样式
通过 styles 配置这个选项用来自定义书本的 css 的。
参考如下：
{
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}
}
pdf 参数配置
PDF输出可以使用book.json中的 pdf 来进行配置：
| 变量 | 说明 |
|---|---|
| pdf.pageNumbers | 将页码添加到每个页面的底部（默认为true） |
| pdf.fontSize | 基本字体大小（默认为12） |
| pdf.fontFamily | 基本字体系列（默认为Arial） |
| pdf.paperSize | 纸张大小，选项为：“a0”，“a1”，“a2”，“a3”，“a4”，“a5”，“a6”，“b0”，“b1”，“b2”，“b3”, “b4”，“b5”，“b6”，“legal”，“letter”，（默认为"a4"） |
| pdf.margin.top | 顶部边距（默认为56） |
| pdf.margin.bottom | 底边距（默认为56） |
| pdf.margin.left | 左边距（默认为62） |
| pdf.margin.right | 右边距（默认为62） |
参考如下：
{
"pdf": {
"pageNumbers": true,
"fontFamily": "Arial",
"fontSize": 12,
"paperSize": "a4",
"margin": {
"right": 62,
"left": 62,
"top": 56,
"bottom": 56
}
}
}
plugins 插件列表
通过 plugins 配置可以配置书籍需要的插件列表。
参考如下：
{
"plugins": [
"github",
"splitter",
...
]
}
pluginsConfig 插件配置
通过 插件配置 可以配置插件列表plugins中对应插件的一些配置选项信息。
参考如下：
{
"plugins": ["favicon"],
"pluginsConfig": {
"favicon": {
"shortcut": "favicon.ico",
"bookmark": "favicon.ico"
}
}
}
总体参考配置示例
最后贴出作者经常用的一个 book.json 完整的配置，可供参考。
{
"root": "src",
"author": "WorkerLee",
"title": "这标题",
"description": "这是描述",
"language": "zh-hans",
"direction": "ltr",
"gitbook": ">=3.2.3",
"structure": {
"readme": "README.md",
"summary": "SUMMARY.md"
},
"links": {
"sidebar": {
"CSDN": "https://blog.csdn.net/lili40342",
"Gitee": "https://gitee.com/lili40342"
}
},
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
},
"plugins": [
"-lunr",
"-search",
"search-pro",
"advanced-emoji",
"tbfed-pagefooter",
"splitter",
"anchor-navigation-ex",
"expandable-chapters-small",
"code",
"copy-code-button",
"alerts",
"hide-element",
"favicon",
"lightbox",
"-sharing"
],
"pluginsConfig": {
"hide-element": {
"elements": [".gitbook-link"]
},
"favicon": {
"shortcut": "favicon.ico",
"bookmark": "favicon.ico"
},
"tbfed-pagefooter": {
"copyright": "Copyright © WorkerLee",
"modify_label": "更新时间：",
"modify_format": "YYYY-MM-DD HH:mm:ss"
},
"anchor-navigation-ex": {
"showLevel": false,
"associatedWithSummary": false,
"printLog": false,
"multipleH1": false,
"mode": "float",
"showGoTop": true,
"float": {
"floatIcon": "fa fa-navicon",
"showLevelIcon": false,
"level1Icon": "fa fa-angle-double-right",
"level2Icon": "fa fa-angle-double-right",
"level3Icon": "fa fa-angle-double-right"
},
"pageTop": {
"showLevelIcon": false,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
}
}
},
"pdf": {
"pageNumbers": true,
"fontFamily": "Arial",
"fontSize": 12,
"paperSize": "a4",
"margin": {
"right": 62,
"left": 62,
"top": 56,
"bottom": 56
}
}
}
至于一些其它的插件，一些主题，具体有什么用，怎么用，还是请各位自行搜索，这里就不多讲解了。
生成书籍
README.md 和 SUMMARY.md 文件内容也维护好了，相应的子页面的内容也编辑好了，book.json 文件也配置版好了，下面就可以生成我们想要的 Gitbook 书了。可以再次使用“gitbook init”命令生成个目录中的各小节md文件，然后你喜欢手动创建也没有任何问题。
安装插件
book.json 文件中会配置很多插件，这些插件默认情况下，有一些是不在本机的，需要先进行插件的安装，命令如下：
#直接进行所有的插件安装，根据配置插件多少决定时间长短，命令运行后有信息提示安装到哪个插件了
#也可以单个插件逐一安装，命令请自行搜索
#这里只给出安装所有插件
gitbook install
编译生成
Gitbook 编译会在当前书籍目录下生成一个“_book”文件夹，里面是一些编译好的静态页面，其实所谓编译生成，就是默认的生成静态 HTML 页面（可直接浏览器查看）。编译命令如下：
gitbook build
在线预览
我们可以通过 nodejs 的平台支撑将编译好的静态页面通过服务器形式进行在线预览访问，Gitbook 默认开启一个 4000 的端口服务，在浏览器中直接可以通过 http://localhost:4000 进行访问。启动服务命令如下：
#看好命令，是serve，并不是server
#并确定好您本机4000端口可用
gitbook serve
到此基本就OK了。
总结（可能遇到问题）
Gitbook 命令
#初始化，其实可以理解为设置一个样板书
gitbook init
#如果初始化到一个新创建的目录中
gitbook init ./directory
#构建生成静态资源
gitbook build
#可以在构建生成资源的时候查看更详细的信息
gitbook build ./ --log=debug --debug
#启动服务
gitbook serve
#列出gitbook所有的命令
gitbook help
#列出gitbook-cli所有的命令
gitbook --help
#生成时指定gitbook的版本, 本地没有会先下载
gitbook build --gitbook=2.0.1
#列出本地所有的gitbook版本
gitbook ls
#安装对应的gitbook版本
gitbook fetch 标签/版本号
#更新到gitbook的最新版本
gitbook update
#卸载对应的gitbook版本
gitbook uninstall 2.0.1
遇到的问题
安装过程中，可能会遇到各种各样的问题，主要错误大家也一定是一个，作者也不挨个表述了，自行搜索即可。但是作者认为，只要保证各个组件的版本兼容，不太会出问题，比如我一直阐述的 nodejs 版本要和 npm 版本进行兼容对应，或者是不要下载太新的版本等等。
推送到 Gitee 或者 GitHub
将 Gitbook 做成自己的知识分享也是不错的选择，具体怎么推送这里也不阐述了，很简单，一搜一大把。
导出 PDF、ePub、Mobi格式文件
目前常见的电子书格式主要主要有三种（ePub, Mobi, PDF），在 Gitbook 中导出这三种格式都依赖于系统本身提供的 ebook-convert 工具支持。所以要想导出 PDF、ePub、Mobi 格式文件，需要先安装 ebook-concert 依赖。相关的信息还需要访问：https://calibre-ebook.com/download，查看相关对应的系统进行相应的安装。
作者认为现在市面上支持 ePub、Mobi 格式的工具较少，所以大部分还是生成 PDF 更合适，但是既然我们用了 Markdown 编辑器，大部分的 Markdown 编辑器都具有到处 PDF 格式的功能，看您怎么选择了。
Linux系统
暂无。