《了不起的Markdown》第八章
第8章 自由地写作——GitBook
在如今这样开放的互联网时代，每个人都可以是一个独立的品牌，可以表达自己的观点，也可以写一本自己的书。豆瓣阅读、百度阅读、网易云阅读、简书、知乎等平台都提供了很好的创作环境，可是它们也都有一定的门槛，那如何才能自由地、无门槛地进行写作呢?GitBook为我们提供了这种可能。
小提示： 本书所提及的GitBook在没有特殊说明的情况下，均是指GitBook 命令行工具。由于www.gitbook.com在国内访问体验较差，因此不多作介绍。
8.1 你好，GitBook
GitBook命令行工具是基于Node.js开发的，通过命令行可以创建、编辑和管理电子书。GitBook是目前最流行的开源书籍写作工具，其在写作方面主要有以下几点优势。
- 支持Markdown和AsciiDoc语法。
- 支持多语言，支持变量、模板和模板继承。
- 可以导出静态站点或电子书（支持PDF、ePub、mobi等格式）。
- 有丰富的插件。
- 可以使用Git管理写作内容，方便多人协作和版本管理。
- 可以将内容托管在GitHub或Gitlab中。
使用GitBook可以搭建公司内部文档，用于内部的资料共享；也可以发布开源电子书，用于在互联网上分享知识。
8.1.1 环境配置
安装GitBook前需要先安装Node.js，然后再通过命令来安装GitBook。
npm install gitbook-cli -g
8.1.2 快速开始
1. 创建静态站点
先通过一个例子来快速了解GitBook的工作流程。
第1步，初始化工作目录
根据上述代码，初始化完成后会创建两个md格式的文件。
- README . md：用于编写书籍的前言或介绍。
- SUMMARY . md：用于配置书籍的目录结构。
第2步：定义目录结构
在SUMMARY.md文件中定义书籍的目录结构，主要有两种方法。
方法➊：先定义好目录结构，再通过gitbook init命令自动生成目录结构对应的文件夹和Markdown文件。
方法➋：先创建好文件夹和Markdown文件再来编辑目录结构。
这里我们使用方法➊，在SUMMARY . md中定义书籍的目录结构
# SUMMARY
* [项目简介](README.md)
* [快速开始](docs/快速开始.md)
* [环境搭建](docs/环境搭建.md)
* [简单使用](docs/简单使用.md)
* [深入学习](docs/深入学习.md)
- 在项目根目录下执行
gitbook init
所有不存在的文件夹和文件都会被新建出来。注意： gitbook init只支持生成两级目录。
第3步：启动服务
gitbook serve
执行gitbook serve命令后，会先执行gitbook build编译书籍，如果编译没有问题，就会打开一个Web服务器，默认监听4000端口。如果编译有问题，则会抛出错误信息。
第4步：查看效果
用浏览器打开http://localhost:4000/查看书籍站点的显示效果。
2. 开始写作
推荐的写作工具组合是：GitBook（书籍管理）+Typora（编辑器）+SourceTree（版本控制），对于编写和管理电子书来说，这是一种非常高效的组合。当然，使用VS Code也是一个不错的选择。
前面的的第3章和第4章已经介绍过Typora和VS Code。而SourceTree是一款Git可视化管理工具，如果你熟悉Git，那么SourceTree是很容易快速上手的，关于SourceTree的更多内容可以参考https://www.sourcetreeapp.com/。
3. 发布电子书
GitBook不仅可以生成静态网站，也可以生成3种格式（即ePub、mobi、PDF）的电子书。
- 生成PDF格式的电子书
gitbook pdf ./mygitbook.pdf
4. 发布上线
如果想要开源，可以把书籍托管到GitHub上，然后绑定自己的域名。一个比较好的例子是https://github.com/rootsongjc/kubernetes-handbook。
8.2 配置GitBook
8.2.1 GitBook的项目结构
- GitBook的项目结构
.
|—— book.json # 配置书籍（可选）
|—— README.md # 书籍的前言/介绍（可选）
|—— SUMMARY.md # 配置的书籍目录（可选）
|—— GLOSSARY.md # 配置书籍的词汇/注释术语列表（列表）
|—— .gitignore # 配置要忽略的文件
|—— cover_small.jpg # 封面图片（小）
|—— cover.jpg # 封面图片
|—— 第一章/ # 书籍内容
| |—— README.md
| |——something.md
1. 配置项目结构
book.json是全局配置文件，可以自定义项目的根目录、自述文件、摘要、词汇表、多语言等文件的文件名。
- 在book.json中可配置的变量
| 变量 | 描述 |
|---|---|
| root | 配置书籍的根目录，默认只是当前目录 |
| structure | 配置自述文件、摘要、词汇表的文件名 |
| title | 配置书名，若不配置，则默认从自述文件README第一段中提取 |
| description | 配置书籍的描述，若不配置，则默认从自述文件中提取 |
| author | 配置作者姓名 |
| isbn | 配置本书的国标码ISBN |
| language | 配置本书语言的ISO代码，默认值是en，这个值是用来做国际化和本地化的 |
| direction | 配置文本方向。可以是rtl或ltr，默认值取决于language值 |
| gitbook | 指定Gitbook版本，使用SemVer规范接受“>=3.0.0”这样的样式 |
- 配置 book.json 的一个示例
{
"title": "Gitbook使用指南",
"description": "Gitbook入门指南",
"author": "XXX"
"output.name": "site", // 构建输出的文件名，使用默认即可，此项可删除
"language": "zh-hans", // 英文：en；中文简体：zh-hans；中文繁体：zh
"gitbook": "3.2.2",
"root": "." // 根目录为当前目录，使用默认即可，此项可删除
}
a. 自定义根目录和文件名
在GitBook项目中，默认所有文件都是从根目录开始查找的，如果想自定义根目录，需要在book.json中通过root指定根目录。例如，将docs指定为项目的根目录。
{
......
"root": "./docs"
}
除root变量之外，还可以自定义GitBook的自述文件、摘要、词汇表和语言文件的名称，这些文件必须在书籍的根目录（或每种语言图书的根目录）下。
| 变量 | 描述 |
|---|---|
| structure.readme | 自述文件名（默认为README.md） |
| structure.summary | 摘要文件名（默认为SUMMARY.md） |
| structure.glossary | 词汇表文件名（默认为GLOSSARY.md） |
| structure.languages | 语言文件名（默认为LANGS.md） |
- 也可以自定义文件名和摘要
{
......
"structure": {
"readme": "myIntroduction.md",
"summary": "mySummary.md"