随着工作时间越来越久，项目越做越多，很多时候，手里面的技术文档都是零散的技术点。最近一直在着手把项目的技术开发文档(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 写出来的页面是一样的。

注：

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

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

# Introduction
 
Hello World!

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

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

目录

现在我们把注意力放到 gitbook 为我们创建的第二个文件SUMMARY.md上，这个文件决定了我们的目录结构。 一个比较简单的目录结构如下：

# Summary
 
* [前言](README.md)
* [第一章](xx.md)
* [第二章](xx.md)
* [第三章](xx.md)

xx.md就是我们每个章节独立的 markdown 文件，所以用 gitbook 写一本书真的非常方便，一个目录文件，和若干个你的书的内容就好了。

目录分层

简单的目录有一个小的问题就是我们目录都只有一级，如果想要分层，比如第一章有1，2，3个小节，该怎么办呢？ 这里有两种方式：

标题区分

我们把SUMMARY.md文件修改成如下内容

# Summary
 
## 前言
* [前言](README.md)
 
## 第一章
* [1.1小节]()
* [1.2小节]()
 
## 第二章
* [2.1小节]()
* [2.2小节]()
 
## 第三章
* [3.1小节]()
* [3.2小节]()

最终的样式如下：

缩进区分

我们还可以用缩进的方式对目录进行级别的区分

# Summary
 
* [前言](README.md)
* [第一章]()
    * [1.1小节]()
    * [1.2小节]()
* [第二章]()
    * [2.1小节]()
    * [2.2小节]()
* [第三章]()
    * [3.1小节]()
    * [3.2小节]()

最终的样式如下：

大家可以根据自己的喜好选择不同的样式，也可以把这两者结合起来一起用，as you wish.

打包发布

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

$ gitbook build

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