使用github、travis、github pages自动构建发布gitbook页面（国内访问速度会比gitbook快很多）

前言

gitbook使用markdown语法进行写作，自动生成简单漂亮的文档页面，还有海量插件可以使用，并且公开文档都免费提供服务，
使用起来很方便，有配套的软件，就算不懂代码的人用起来也非常简单。

但是有个缺点就是国内访问很慢，慢得连github的pages页面的速度都不如，而且不支持同步github组织的仓库，所以可以考虑将gitbook编译成静态页面发布到pages，
而且希望整个发布过程都是自动的，我们自己后面该文档时要做的就只是写文档（直接文本编辑器或者gitbook编辑器都行），写完后提交推送到github，后面的构建、发布全都不用我们自己操作，都自动完成，于是可以用travis，travis对github十分友好，对于公开的仓库，travis也是免费的

方法和步骤

• 首先保证注册了github(github.com)账号、travis（travis.org）账号
• 在github建立文档仓库
• travis开启同步

新建travis项目

开启同步

• 设置travis项目

  
  
  

  设置

设置项目变量

设置变量

这些变量的名字和功能取决于yml脚本，这里这几个变量含义如下：
GITHUB_TOKEN : github授权码，在github的 Settings -> Developer settings -> Personal access tokens中可以生成一个新的 token，注意一定 不能勾选 Display Value in build log
GIT_NAME,GIT_EMAIL:昵称和邮箱
CUSTOM_DOMAIN:自定义域名，最后github pages中CNAME文件中的内容

• 设置文档工程（仓库）
  github仓库新建.travis.yml文件：

language: node_js

node_js:
  - "8"

# 缓存依赖
cache:
  directories:
    - $HOME/.npm

before_install:
  - export TZ='Asia/Shanghai' # 更改时区

# 依赖安装
install:
  - npm install gitbook-cli -g
  # 安装 gitbook 插件
  - gitbook install

# 构建脚本
script:
    # 自定义输出目录 gitbook build src dest
  - gitbook build . ./build
  # - gitbook build . ./build/$CUSTOM_PATH

# 分支白名单
branches:
  only:
    - master # 只对 master 分支进行构建

# GitHub Pages 部署
deploy:
  provider: pages
  skip_cleanup: true
  # 在项目仪表盘的 Settings -> Environment Variables 中配置
  github_token: $GITHUB_TOKEN
  # 将 build 目录下的内容推送到默认的 gh-pages 分支上，并不会连带 build 目录一起
  local_dir: build
  #fqdn: $CUSTOM_DOMAIN
  name: $GIT_NAME
  email: $GIT_EMAIL
  on:
    branch: master
 

这里CUSTOM_PATH被注释了，如果想域名后面还有子文件夹就这样使用，比如自定义域名gprs.neucrack.com，不使用CUSTOM_PATH，则最后的访问地址就是gprs.neucrack.com，而用了CUSTOM_PATH而且设置CUSTOM_PATH变量值为doc，则最后访问地址就是gprs.neucrack.com/doc，

上面的代码自定义域名我也注释了，因为没有使用，如果使用自定义域名就取消注释

还需要注意的是，在进行部署的过程中，默认是使用 git push --force 进行推送的，也就是说你的目标分支的历史提交记录只会有最新的那一条，如果需要提交历史的话，可以添加 keep-history: true 选项。

• 推送更新
  将新建的.travis.yml文件同步到github，会自动触发travis对项目的构建
  
  

  构建
  
  构建成功后便可以在自定义的域名访问了，通常地址为：用户名/组织名.github.io/项目名，如果使用了类似上面的CUSTOM_PATH的文件夹地址，则访问地址是:用户名/组织名.github.io/项目/CUSTOM_PATH

比如这里有个例子：
构建目标仓库是：https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC
没有使用自定义域名以及文件路径，最后访问地址是：https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/

为了让gitbook能同时有中文和英文，官方有做多语言:Multi-Languages,但是缺点是不能使用语言特殊的插件了.

可以在一个工程中建立两个文件夹,比如en和zh两个文件夹,然后每个文件夹内放一个gitbook工程,这样生成后就会有中英文目录了,这种方法简单方便,中英文在同一个分支进行维护.

另外一种方式,为了让两种语言为两个独立的工程(/分支),将两种语言放在两个分支上，为了将两个分支编译后合并到一个分支的两个文件夹(zh和en)，需要自己写脚本，稍微复杂一点，优点是两个分支可以分开提交互不影响向，不爱折腾不建议用这种方式；可以参考：https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC，生成的页面地址是：https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/zh 和 https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/en.

可以参考另一个仓库：MAIXPY Doc， 这份文档系统包含了多语言和多版本支持，做得比较全面

MaixPy

也可以参考cocos creator的文档

参考文档

使用 Travis CI 自动部署 GitBook 到 GitHub Pages