【Gitbook】GitBook+GitLab撰写发布技术文档-Part1:GitBook篇

随着工作时间越来越久，项目越做越多，很多时候，手里面的技术文档都是零散的技术点。最近一直在着手把项目的技术开发文档(Technical Document)系统地整理一下。正好看到了非常棒的 GitBook 工具，又顺带研究了如何借助 Gitlab 的 CI/CD 功能实现自动部署。
正好开个简短的教程，介绍一下 GitBook + GitLab怎样来撰写并发布文档。
第一部分先来介绍一下 GitBook。

系统环境

惯例列出来我们的环境以及用到的工具。

MacOS 10.12
Node.js (版本 > 4.0.0)
Atom/MWebLite

其实 Gitbook 有官方的编辑器，但是似乎对中文的支持不是很好，而且会有 bug，虽然最新版本做了优化，Mardown 格式的文字有些会自动显示成最终样式，而我个人还是比较喜欢原生的 markdown，所以我个人就没有用官方的编辑器。
如果读者注册了 gitbook，并且打算文章都发布到 gitbook 官网上的话，还是建议可以使用官方的编辑器。因为我的目标是发布到公司内网的 gitlab 上，所以这里就用 atom 或者 MWebLite 来编写文档。
其实这篇文章过后，大家对 Gitbook 的工作机制就很清楚了，完全可以自由地创作了。

基本使用

安装

安装过程非常简单

npm install gitbook-cli -g

新建book

安装成功后，我们就可以开始用gitbook 的命令来进行各种操作了。如果熟悉hexo的同学会发现，其实大同小异，只不过一个用来写blog，一个用来写 book。

$ mkdir myBook
$ cd myBook
$ gitbook init

初始化后，我们能在myBook目录下看到两个 markdown 文f件。这两个文件就是我们写一本书唯二必须要用的文件了。

预览book

先不做任何变动，模拟一下我们发布之后的页面的成品吧。

$ gitbook serve

我们打开浏览器，在浏览器中输入0.0.0.0:4000就可以在本地预览了。

可以看到，左侧是我们的菜单栏，自带一个搜索栏，右侧就是我们的 book 的内容了，右上角有默认的诸如 twitter,facebook 等分享快捷方式。基本上和其他人用 gitbook 写出来的页面是一样的。

注：
gitbook 新版本提供了本地预览功能的热更新，也就是说本地预览的页面会随着我们写书的内容变化而自动更新，这着实是一个很使用的功能。
在命令行ctrl+c可以关闭本地服务器，即预览页面。

我们可以尝试修改一下书的内容，看一下页面的变化。打开README.md文件，修改成如下内容：

# Introduction
 
Hello World!

再回头看一眼我们的预览页面，是不是自动变成了下面的样子。

关于 gitbook 自建的 README.md 文件我就不做过多的介绍了，都是一些 Markdown 的基本语法，相信使用 gitbook 的各位一定是对 markdown 语法非常熟悉的了。

打包发布

通过预览模式，我们可以随时掌握书籍的更新内容。当你完成了部分章节或者全书的编写后，我们需要把写好的内容打包并发布。

$ gitbook build

执行完上面的命令后，我们会发现在根目录下出现了_build文件夹，里面的文件就是我们需要发布的内容，你可以把所有的内容放到你的网站目录下，或者 gitlab/github 的 page页面，就实现了 gitbook 的线上发布了~

进阶技巧

看完上面的章节，你已经可以独立完成一本书的编写和发布，接下来的章节，我们提供一些进阶的技巧，你可以安装一些插件、更直观地规划你的目录结构等等。

插件

和众多开源的软件一样，gitbook 也有一些插件，这些插件可以让你的书更加完美。这里我仅附上我个人觉得比较有用的几个插件，更多的插件，可以访问社区来获取。
插件的引入和修改都是在配置文件中完成的，那我们可以在根目录下创建book.json文件来修改当前书的一些配置，因为是 json 格式的，所以诸如书的标题、作者、内容等都可以在配置文件中完成，我们重点来说插件。

{
     "plugins": [
          "-lunr",
          "-search",
          "search-plus",
          "splitter",
          "copy-code-button",
          "expandable-chapters-small"
     ]
}

以上是我的book.json配置文件，只有一个关于插件的配置项，其实总共就4个

search-plus 让搜索支持中文，注意需要先把默认的两个插件lunr和serach禁用掉，禁用的方式就是在前面加上-号
spliter 菜单栏宽度可调节
copy-code-button 代码可以一键 copy
expandable-chapters-small 菜单栏可以折叠

注：
如果引入了新的插件，需要通过gitbook install 命令来安装新的插件，否则在打包发布的时候会提示错误。

目录结构

一个基本的目录结构是这样的

.
├── _book/
├── book.json
├── README.md
├── SUMMARY.md
├── xx1.md
├── xx2.md
├── xx3.md
├── xx4.md
├── ...

不过为了我们自己方便，个人建议的目录结构如下

.
├── _book/
├── node_modules/
├── .gitlab-ci.yml
├── book.json
├── SUMMARY.md
├── content/
|   ├── chapter1/
|       ├── README.md
|       └── something.md
|   ├── chapter2/
|       ├── README.md
|       └── something.md
├── res/
|   ├── 1.png
|   └── 2.jpg
|   └── 3.jpeg
|   └── ...

说明：