6.3 GitHub

你可以使用 GitHub Pages (https://pages.github.com) 在 GitHub 上免费托管你的书籍。GitHub 支持 Jekyll (http://jekyllrb.com), 它是一个静态网站生成器，能够将一系列 Markdown 文件转换为网站。这可能是 GitHub Pages 最常见的用法，但是 GitHub 还支持任意静态 HTML 文件，因此你可以在 GitHub 上托管书籍的 HTML 输出文件。其关键是创建一个隐藏文件 .nojekyll，它告诉 GitHub 你的网站不是通过 Jekyll 构建的，因为 bookdown 的 HTML 输出文件已经是一个独立的网站。

# 假设你已经初始化了一个 git 储存库，并且已经在书籍储存库的目录下

# 创建一个隐藏文件 .nojekyll
touch .nojekyll
# 将其添加入 git 版本控制中，这样她就不会再 RStudio 中显示
git add .nojekyll

如果你使用 Windows，那么可能没有 touch 命令，这时你可以在 R 中使用 file.create('.nojekyll') 来创建一个文件。

发布书籍的一种方法将书籍的 HTML 文件放入 master 分支中的 /docs 文件夹，然后从该文件夹将书籍作为 GitHub Pagse 站点发布，就像 GitHub Help中描述的那样。首先，在配置文件 _bookdown.yml 中添加一行 output_dir:"docs"，将书籍的输出目录设置为 /docs。然后，将更改推送到 GitHub ，再转到存储库的设置，在“GitHub Pages”配置项下将“Source”选项更改为“master branch/docs folder”。使用该方法时，.nojekyll 文件必须位于 /docs 文件夹中。

另一种方法是先在存储库中创建一个 gh-pages 分支，再构建书籍，将 HTML 输出（包括图像、CSS 和 JavaScript 文件等所有外部资源）放入该分支，然后将该分支推送到远程存储库。如果你的书籍存储库没有 gh-pages 分支，可以使用以下命令创建一个分支：

# 假设你已经初始化了一个 git 储存库，并且已经在书籍储存库的目录下

# 创建一个名为 gh-pages 的分支，并清除全部文件
git checkout --orphan gh-pages
git rm -rf .

# 创建一个隐藏文件 .nojekyll
touch .nojekyll
git add .nojekyll

git commit -m "Initial commit"
git push origin gh-pages

设置好 GIT 之后，剩下的工作可以通过脚本（Shell、R 或 Makefile，取决于你的偏好）实现自动化。总的来说，首先将书籍编译为 HTML，然后运行 git 命令将文件推送到 GitHub，但你可能不希望在本地反复手动执行这些操作，这时可以通过云来完成。由于在云上实现发布过程的完全自动化将会非常方便，因此一旦设置正确，接下来所要做的就是编写书籍并将 Rmd 源文件推送到 GitHub，你创作的书将始终在服务器端自动构建和发布。

你可以选择使用的一个云服务是 Travis CI (https://travis-ci.com)。 它对于 GitHub 上的共有储存库提供的服务是免费的，并且是为软件包的持续集成 (CI) 而设计的。Travis CI 能够连接到 GitHub, 即每当你推送更改到 GitHub 时，Travis 能够被触发在最新版本的储存库上运行某些命令/脚本。13这些命令储存在你的储存库根目录下名为 .travis.yml 的 YAML 文件中。它们通常用于测试软件，但实际上它们的用途十分开放，这意味着你可以在 Travis（虚拟）机器上运行任意命令。也就是说，你当然可以在 Travis 上运行自己的脚本来构建书籍。注意，Travis 目前仅支持 Ubuntu 和 Mac OS X，因此你应该对于 Linux/Unix 命令有一些基本的了解。

下一个问题是，怎样将在 Travis 中构建的书籍发布到 GitHub？大体上说，你需要授予 Travis 对你的 GitHub 储存库的写访问权限。该授权能够通过集中方式完成，对于初学者来说最简单的方式是个人访问令牌 (personal access token)。以下是你可以遵循的几个操作步骤：

  1. 对于你在 GitHub 上的账户创建一个 个人访问令牌 (personal access token)（请确保启用“repo”作用域 (“repo” scope)，以便可以通过此令牌写入你的 GitHub 储存库）。
  2. 通过命令 travis encrypt 将其加密并放在环境变量 GITHUB_PAT 里，然后储存在 .travis.yml 文件中。例如 travis encrypt GITHUB_PAT=TOKEN。如果你不知道如何安装或使用 Travis 命令行工具，只需要将这个环境变量通过 https://travis-ci.com/user/repo/settings 储存起来，其中 user 是你的 GitHub ID，repo 是储存库的名称。
  3. 你可以使用你的 GitHub 令牌在 Travis 上克隆先前创建的这个 gh-pages 分支，向其添加从 R Markdown 转换而来的 HTML 输出文件（不要忘记添加图片和 CSS 样式文件），然后推送到远程储存库。

假设你正在 master 分支中（你存放 Rmd 源文件的分支），并且已经编译好书籍，放在 _book 目录中。接下来你可以在 Travis 中做的是：

# 如果你还没有进行配置的话，设置好你的用户名和邮箱
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

# 将储存库克隆到书籍输出目录 book-output
git clone -b gh-pages \
  https://${GITHUB_PAT}@github.com/${TRAVIS_REPO_SLUG}.git \
  book-output
cd book-output
git rm -rf *
cp -r ../_book/* ./
git add --all *
git commit -m "Update the book"
git push -q origin gh-pages

变量名 GITHUB_PAT 和目录名 book-output 可以是任意名称。只要名称没有与已经存在的变量名或目录名冲突，你就可以使用喜欢的任何名字。上述脚本与我们在第 5.1 节提到的书籍构建脚本可以放在 master 分支作为 as Shell 脚本。例如，你可以将它们命名为 _build.sh 和 _deploy.sh。那么，你的 .travis.yml 文件可能是这样的：

language: r
pandoc_version: 1.19.2.1

env:
  global:
    - secure: A_LONG_ENCRYPTED_STRING

before_script:
  - chmod +x ./_build.sh
  - chmod +x ./_deploy.sh

script:
  - ./_build.sh
  - ./_deploy.sh

language 选项告诉 Travis 需要使用安装了 R 的虚拟机。secure 字段是加密的个人访问令牌 (personal access token )。如果你已经使用 Travis 上的 Web 界面而不是命令行工具 travis encrypt 保存了 GITHUB_PAT 变量，则可以忽略这项设置。

由于 Travis 服务主要用于检查 R 软件包，因此还需要一个（假的）DESCRIPTION 文件，使得书籍存储库像是一个 R 软件包一样。这个文件中唯一一个真正重要的是软件包依赖项这一配置。所有依赖项都将通过 devtools 包安装。如果依赖项在 CRAN 或 BioConductor 上，只需在 DESCRIPTION 文件的 Imports 字段中列出即可。如果它在 GitHub 上，您可以使用 Remotes 字段列出它的存储库名称。下面展示了一个例子：

Package: placeholder
Type: Book
Title: Does not matter.
Version: 0.0.1
Imports: bookdown, ggplot2
Remotes: rstudio/bookdown

如果你使用 Travis 的 container-based infrastructure，你可以在 .travis.yml 中使用 sudo: false 启用缓存。通常你至少需要缓存两类目录：图片目录（例如 _main_files）以及缓存目录（例如 _main_cache）。如果你指定了 knitr 代码块选项 fig.path 和 cache.path，这些目录的名称可能不同，但是我强烈建议不要改变这些设置。图片和缓存目录都存放在书籍根目录中的 _bookdown_files 目录下。启用了 knitr 图片和缓存的 .travis.yml 文件可能具有如下的 sudo 和 cache 附加配置：

sudo: false

cache:
  packages: yes
  directories:
    - $TRAVIS_BUILD_DIR/_bookdown_files

如果构建书籍非常耗时，你可以在 Travis 上使用上面的配置来节省时间。注意，packages:yes 表示安装在 Travis 上的 R 包也被缓存。

以上所有脚本和配置都可以在 bookdown-demo 存储库中找到：https://github.com/rstudio/bookdown-demo/。如果你将它们复制到自己的存储库中，请记住使用自己的加密变量 GITHUB_PAT 更改 .travis.yml 文件中的 secure 字段。

GitHub 和 Travis CI 当然不是构建和出版你的书籍的唯一选择。你可以在自己的服务器上自由地存储和发布这本书。

  1. 你需要先在 GitHub 上为你的储存库授权 Travis CI 服务。有关如何开始使用 Travis CI，请参阅 https://docs.travis-ci.com/user/getting-started/。↩︎