使用 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 # 查看帮助
客户端
下载 https://www.gitbook.com/editor
打开Gitbook-Editor，选择Do This Later
14829254959404.jpg
选择 New Summary Entry 创建目录，然后再创建文件
14829835058873.jpg
开启Markdown模式
14829836262887.jpg
选择 Repository Settings 可以更改git源。
14829837050554.jpg
