使用 GitBook + GitLab 团队文档协作

我们团队对于文档管理软件的要求有以下几点：

1.支持Markdown
2.支持团队协作
3.文档有版本历史
4.支持导出Html，Pdf等格式。
5.支持树形目录，导出PDF时候可以直接按目录结构导出，这个很重要，目前我还没找到支持按树形目录导出的工具软件。
6.支持图片上传

符合我们要求的我只找到了 GitBook 一个，但是GitBook 无法国内访问，对于团队协作很是不方便。

GitBook 提供了 GitBook Editor ，GitBook cli 这两个工具，一个是编辑文档，一个可以生成文档。只要本地搭建一个Git 服务就完全可以实现本地化了。

GitBook的界面

14829827179843.jpg

构建生成的网页

14829828115374.jpg

工具准备

如果没有团队协作要求，只想生成电子书，只在自己机器上安装GitBook CI 就可以，1，2 就可以省略了。

GitLab 一键安装包 https://about.gitlab.com/downloads/
GitLab Ci Runner https://github.com/gitlabhq/gitlab-ci-runner
GitBook CI https://github.com/GitbookIO/gitbook-cli
GitBook Editor https://www.gitbook.com/editor

这里不阐述GitLab,和GitLab Runner安装步骤，只从 GitLab Runner的配置开始

编辑 .gitlab-ci.yml

# 定义 stages
stages:
  - build
# 定义 job
GenerateHTML:
  stage: build
  script:
    - p=`pwd`
    - echo $p
    - gitbook build

gitlab 执行构建，会在文件夹下生成 _book 的目录。

Running with gitlab-ci-multi-runner 1.5.2 (76fdacd)
Using Shell executor...
Running on rkhdbasic...
Fetching changes...
正删除 _book/
HEAD 现在位于 b58ab18 Updates 开发规范.md
来自 http://192.168.0.102:7000/doc/mobile-platform
   b58ab18..1ffb64d  develop    -> origin/develop
Checking out 1ffb64d4 as develop...
$ p=`pwd`
$ echo $p
/root/builds/6b41a8b6/0/doc/mobile-platform
$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 2 asset files 
info: >> generation finished with success in 2.9s ! 
Build succeeded

CD到echo 打印出来的文件夹路径

    /root/builds/6b41a8b6/0/doc/mobile-platform

下手工执行 gitbook serve 启动，每次构建完成后，服务会自从重新加载。

gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 2 asset files 
info: >> generation finished with success in 2.6s ! 

Starting server ...
Serving book on http://localhost:4000
Restart after change in file _book

打开 ip:4000 就可以查看文档了。

$ gitbook init # 初始化一个仓库

$ gitbook install # 安装插件

$ gitbook serve # 本地预览
$ gitbook serve --port 8001 # 指定端口,默认4000

$ gitbook build  # 输出一个静态网站

$ gitbook pdf # 生成pdf文件

$ gitbook help # 查看帮助