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

前言

大部分使用过 GitBook 的同学都应该有部署静态页面的经历,GitBook 有直接部署静态页面到 GitHub 上的功能,但这样并不能解决原稿件的备份和同步问题,因为 GitBook 默认的部署只会将生成的 _book 的内容同步到仓库中。

现在有一个需求,我们只需要将撰写好的 Markdown 文档推到仓库中,就可以自动编译出静态页面并部署到 GitHub Pages 上。


方案

  1. GitBook 官方提供从 GitHub 生成书籍的功能,并提供了自定义域名绑定等类似于 GitHub Pages 的服务

  2. 脚本大法好!

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

第 1 种方案已经满足了我们的需求了,唯一不足的地方就是服务有时候会被墙住。

第 2 种方案也可以满足我们的需求,但会受到环境的影响,需要保证工作环境配置好 Node.js(当然这也不是什么难事)。

接下来,我们主要讲一下第 3 种方案。有关 Travis CI 的介绍请移步 Travis CI


创建 Personal access tokens

Personal access tokens 类似传统的 OAuth access tokens,可以无需通过账号密码的方式操作仓库。

Settings -> Developer settings -> Personal access tokens 中可以生成一个新的 token。

权限控制只需要勾选 repo 就可以了,生成的 token 只会显示一次


配置 Travis CI

注册部分就不再赘述了,完成后需要在 account 中对指定仓库开启服务。在对应仓库的 Settings 中开启 Build only if .travis.yml is present。你还可以开启 Limit concurrent jobs 限制并发任务。为了使配置文件更具通用性,我们需要在 Environment Variables 中添加几个要用到的环境变量:

  • GITHUB_TOKEN(生成的 Personal access tokens)
  • GIT_NAME(部署时的提交者名称)
  • GIT_EMAIL(部署时的提交者邮箱)
  • CUSTOM_DOMAIN(自定义域名)
  • CUSTOM_PATH(自定义输出目录)

因为 Travis CI 的日志是公开的,所以要注意不要对敏感的内容开启 Display value in build log,比如你的 GITHUB_TOKEN,否则其它看到日志的人就可以操作你的仓库了。

Settings


编写 .travis.yml

整个配置文件的过程分为安装依赖 -> 执行构建脚本 -> 部署静态页面。Travis CI 提供了 GitHub Pages 的部署服务,所以我们不需要自己写部署脚本,仅仅配置一下就可以进行快速部署:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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/$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

  • 如果部署的 GitBook 就是你的主页的话,那么你就不需要自定义路径,在构建脚本过程中只需要进行 gitbook build,并在部署中指定 local_dir_book 即可。这样你就可以直接通过自定义的域名访问了。

  • 如果不是主页,那就需要自定义路径了,比如我需要通过 book.uooo.me/my-book 进行访问,那么 CUSTOM_PATH 就是 my-book 了,构建的时候就会把内容输出到这个文件夹中,部署的时候就会看到这个文件夹孤零零地待在 gh-pages 分支里了。

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


推送

最后一步就是把配置文件推送到仓库上,Travis CI 只要检测到仓库发生变动就会自动根据配置文件进行构建部署,此外还会发送构建结果到你的邮箱中。

推送的时候不要忘记把本地构建出的用于测试的文件目录(上文的 build_book 等)添加到 .gitignore 文件中。

如果需要的话,还可以把构建的状态标识添加到仓库的 README.md 中:


后记

具体示例可以参照我的这个仓库 XuToTo/mongoose-docs-zh

相比通过 Travis CI 部署 GitBook 来说,部署 Hexo 静态博客更能体现这种方案的便利性,我将会在另一篇文章中简单介绍一下。

参考