BY

阅读数:

Contents
  1. 1. 系统环境
  2. 2. 基本使用
    1. 2.1. 安装
    2. 2.2. 新建book
    3. 2.3. 预览book
    4. 2.4. 目录
      1. 2.4.1. 目录分层
        1. 2.4.1.1. 标题区分
        2. 2.4.1.2. 缩进区分
    5. 2.5. 打包发布
  3. 3. 进阶技巧
    1. 3.1. 插件
    2. 3.2. 目录结构
  4. 4. 参考&致谢

随着工作时间越来越久，项目越做越多，很多时候，手里面的技术文档都是零散的技术点。最近一直在着手把项目的技术开发文档(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 的工作机制就很清楚了，完全可以自由地创作了。

基本使用

安装

安装过程非常简单

1
npm install gitbook-cli -g

新建book

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

1
2
3
$ mkdir myBook
$ cd myBook
$ gitbook init

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



预览book

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

1
$ gitbook serve



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



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

注：

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

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

1
2
3
# Introduction

Hello World!

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



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

目录

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

1
2
3
4
5
6
# Summary

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

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



目录分层

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

标题区分

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Summary

## 前言
* [前言](README.md)

## 第一章
* [1.1小节]()
* [1.2小节]()

## 第二章
* [2.1小节]()
* [2.2小节]()

## 第三章
* [3.1小节]()
* [3.2小节]()

最终的样式如下：



缩进区分

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

1
2
3
4
5
6
7
8
9
10
11
12
# Summary

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

最终的样式如下：



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

打包发布

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

1
$ gitbook build

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

进阶技巧

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

插件

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

1
2
3
4
5
6
7
8
9
10
{
     "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 命令来安装新的插件，否则在打包发布的时候会提示错误。

目录结构

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

1
2
3
4
5
6
7
8
9
10
.
├── _book/
├── book.json
├── README.md
├── SUMMARY.md
├── xx1.md
├── xx2.md
├── xx3.md
├── xx4.md
├── ...

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
.
├── _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目录是我们要用到的一些图片资源文件夹，除了用到床图，我们可以把其他本地图片资源也包含进来

参考&致谢

Contents
  1. 1. 系统环境
  2. 2. 基本使用
    1. 2.1. 安装
    2. 2.2. 新建book
    3. 2.3. 预览book
    4. 2.4. 目录
      1. 2.4.1. 目录分层
        1. 2.4.1.1. 标题区分
        2. 2.4.1.2. 缩进区分
    5. 2.5. 打包发布
  3. 3. 进阶技巧
    1. 3.1. 插件
    2. 3.2. 目录结构
  4. 4. 参考&致谢