随着工作时间越来越久，项目越做越多，很多时候，手里面的技术文档都是零散的技术点。最近一直在着手把项目的技术开发文档(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 为我们创建的第二个文件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 的 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
| └── ...说明：
_book目录是我们打包后要发布的文件目录node_modules目录是我们安装插件后默认生成的目录.gitlab-ci.yml这个是 gitlab 要用的 ci 配置文件，下一章节我们马上就会用到book.json是我们的配置文件content目录是我们的书的内容，所有章节都可以分类继续整理，方便自己查看res目录是我们要用到的一些图片资源文件夹，除了用到床图，我们可以把其他本地图片资源也包含进来
参考&致谢
From: lipeng1667
系列教程
Gitbook使用系列
- GitBook+GitLab撰写发布技术文档-Part1:GitBook篇
- GitBook+GitLab撰写发布技术文档-Part2:GitLab篇
- 自己动手制作电子书的最佳方式（支持PDF、ePub、mobi等格式）
笔记系列
- 完美笔记进化论
- hexo博客博文撰写篇之完美笔记大攻略终极完全版
- Joplin入门指南&实践方案
- 替代Evernote免费开源笔记Joplin-网盘同步笔记历史版本Markdown可视化
- Joplin 插件以及其Markdown语法。All in One!
- Joplin 插件使用推荐
- 为知笔记私有化Docker部署
Gitlab 使用系列
后话
- Gitbook 团队现在基本不再维护 Gitbook 软件，而专注于 Gitbook 网站的开发。可以考虑 mkdocs-material
- Like Gitbook but implemented in Rust
