作者：Yihui Xie
    译者：郑宝童
    日期：2021.06.21

    You can host your book on GitHub for free via GitHub Pages (https://pages.github.com). GitHub supports Jekyll (http://jekyllrb.com), a static website builder, to build a website from Markdown files. That may be the more common use case of GitHub Pages, but GitHub also supports arbitrary static HTML files, so you can just host the HTML output files of your book on GitHub. The key is to create a hidden file .nojekyll that tells GitHub that your website is not to be built via Jekyll, since the bookdown HTML output is already a standalone website.

    您可以通过 GitHub Pages (https://pages.github.com) 在 GitHub 上免费托管您的书。 GitHub 支持 Jekyll (http://jekyllrb.com)，它是一个静态网站构建器，可以从 Markdown 文件构建网站。这可能是 GitHub Pages 更常见的用例，但 GitHub 还支持任意静态 HTML 文件，因此您也可以将图书的 HTML 输出文件托管在 GitHub 上。关键是创建一个隐藏文件 .nojekyll ，它告诉 GitHub 你的网站不是通过 Jekyll 构建的，因为 bookdown HTML 输出已经是一个独立的网站。

    1. # assume you have initialized the git repository,
    2. # and are under the directory of the book repository now
    3. # create a hidden file .nojekyll
    4. touch .nojekyll
    5. # add to git here because will not show up in RStudio
    6. git add .nojekyll

    If you are on Windows, you may not have the touch command, and you can create the file in R using file.create('.nojekyll'). One approach is to publish your book as a GitHub Pages site from a /docs folder on your master branch as described in GitHub Help. First, set the output directory of your book to be /docs by adding the line output_dir: "docs" to the configuration file _bookdown.yml. Then, after pushing your changes to GitHub, go to your repository’s settings and under “GitHub Pages” change the “Source” to be “master branch /docs folder”. In this case, the .nojekyll file has to be in the /docs folder.

    如果您使用的是 Windows，您可能没有 touch 命令，您可以使用 file.create('.nojekyll') 在 R 中创建文件。
    一种方法是将您的图书作为 GitHub Pages 站点从您的主分支上的/docs 文件夹发布，如GitHub Help中所述。首先，通过将行 output_dir: "docs" 添加到配置文件 _bookdown.yml 中，将图书的输出目录设置为 /docs 。然后，将更改推送到 GitHub 后，转到存储库的设置，在“GitHub 页面”下将“Source”更改为“master branch /docs folder”。在这种情况下， .nojekyll 文件必须位于 /docs 文件夹中。

    An alternative approach is to create a gh-pages branch in your repository, build the book, put the HTML output (including all external resources like images, CSS, and JavaScript files) in this branch, and push the branch to the remote repository. If your book repository does not have the gh-pages branch, you may use the following commands to create one:

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

    1. # assume you have initialized the git repository,
    2. # and are under the directory of the book repository now
    3. # create a branch named gh-pages and clean up everything
    4. git checkout --orphan gh-pages
    5. git rm -rf .
    6. # create a hidden file .nojekyll
    7. touch .nojekyll
    8. git add .nojekyll
    9. git commit -m"Initial commit"
    10. git push origin gh-pages

    After you have set up GIT, the rest of work can be automated via a script (Shell, R, or Makefile, depending on your preference). Basically, you compile the book to HTML, then run git commands to push the files to GitHub, but you probably do not want to do this over and over again manually and locally. It can be very handy to automate the publishing process completely on the cloud, so once it is set up correctly, all you have to do next is write the book and push the Rmd source files to GitHub, and your book will always be automatically built and published from the server side.

    设置 GIT 后，其余的工作可以通过脚本（Shell、R 或 Makefile，选哪个取决于您的偏好）自动化。基本上，您将本书编译为 HTML，然后运行 git 命令将文件推送到 GitHub，但您可能不想手动和本地一遍又一遍地执行此操作。在云端完全自动化出版过程会非常方便，所以一旦设置正确，接下来你要做的就是写书并将 Rmd 源文件推送到 GitHub，你的书将始终自动构建并从服务器端发布。

    One service that you can utilize is Travis CI (https://travis-ci.org). It is free for public repositories on GitHub, and was designed for continuous integration (CI) of software packages. Travis CI can be connected to GitHub in the sense that whenever you push to GitHub, Travis can be triggered to run certain commands/scripts on the latest version of your repository.12 These commands are specified in a YAML file named .travis.yml in the root directory of your repository, and they are usually for the purpose of testing software, but in fact they are quite open-ended, meaning that you can run arbitrary commands on a Travis (virtual) machine. That means you can certainly run your own scripts to build your book on Travis. Note that Travis only supports Ubuntu and Mac OS X at the moment, so you should have some basic knowledge about Linux/Unix commands.

    您可以使用的一项服务是 Travis CI (https://travis-ci.org)。它对 GitHub 上的公共存储库是免费的，专为软件包的持续集成 (continuous integration ，CI) 而设计。 Travis CI 可以连接到 GitHub，因为每当您推送到 GitHub 时，都可以触发 Travis 在最新版本的存储库上运行某些命令/脚本。12 这些命令在名为 .travis.yml 的 YAML 文件中,它存放在你的repository的根目录中，它们通常用于测试软件，但实际上它们是非常开放的，这意味着您可以在 Travis（虚拟）机器上运行任意命令。这也意味着您可以在 Travis 上运行自己的脚本来构建您的书。注意 Travis 目前只支持 Ubuntu 和 Mac OS X，所以你应该对 Linux/Unix 命令有一些基本的了解。

    The next question is, how to publish the book built on Travis to GitHub? Basically you have to grant Travis write access to your GitHub repository. This authorization can be done in several ways, and the easiest one to beginners may be a personal access token. Here are a few steps you may follow:

    下一个问题是，如何将基于 Travis 构建的书发布到 GitHub？基本上，您必须授予 Travis 对 GitHub 存储库的写访问权限。这种授权可以通过多种方式完成，对初学者来说最简单的方式可能是个人访问令牌。以下是您可以遵循的几个步骤：

    1. Create a personal access token for your account on GitHub (make sure to enable the “repo” scope so that using this token will enable writing to your GitHub repos).
    1. 在 GitHub 上为您的帐户创建个人访问令牌（personal access token）（确保启用“repo”scope ，以便使用此 token 启用写入您的 GitHub 存储库的权限）。
      1. Encrypt it in the environment variable GITHUB_PAT via command line travis encrypt and store it in .travis.yml, e.g travis encrypt GITHUB_PAT=TOKEN. If you do not know how to install or use the Travis command-line tool, simply save this environment variable via https://travis-ci.org/user/repo/settings where user is your GitHub ID, and repo is the name of the repository.

    1. 通过命令行在环境变量 GITHUB_PAT 中加密它 travis encrypt 并将其存储在 .travis.yml ，例如 travis encrypt GITHUB_PAT=TOKEN 。如果您不知道如何安装或使用 Travis 命令行工具，只需通过 https://travis-ci.org/user/repo/settings 保存此环境变量，其中 user 是您的 GitHub ID，以及 repo是存储库的名称。

      1. You can clone this gh-pages branch on Travis using your GitHub token, add the HTML output files from R Markdown (do not forget to add figures and CSS style files as well), and push to the remote repository.

    2. 您可以使用 GitHub 令牌在 Travis 上克隆这个 gh-pages 分支，添加来自 R Markdown 的 HTML 输出文件（不要忘记添加图形和 CSS 样式文件），然后推送到远程存储库。

    Assume you are in the master branch right now (where you put the Rmd source files), and have compiled the book to the _book directory. What you can do next on Travis is:
    假设你现在在 master 分支（你放置 Rmd 源文件的地方），并且已经将这本书编译到 _book 目录。你接下来可以在 Travis 上做的是：

    1. # configure your name and email if you have not done so
    2. git config --global user.email "you@example.com"
    3. git config --global user.name "Your Name"
    4. # clone the repository to the book-output directory
    5. git clone -b gh-pages \
    6.   https://${GITHUB_PAT}@github.com/${TRAVIS_REPO_SLUG}.git \
    7.   book-output
    8. cd book-output
    9. git rm -rf *
    10. cp -r ../_book/* ./
    11. git add --all *
    12. git commit -m"Update the book"
    13. git push -q origin gh-pages

    The variable name GITHUB_PAT and the directory name book-output are arbitrary, and you can use any names you prefer, as long as the names do not conflict with existing environment variable names or directory names. This script, together with the build script we mentioned in Section 5.1, can be put in the master branch as Shell scripts, e.g., you can name them as _build.sh and _deploy.sh. Then your .travis.yml may look like this:
    变量名 GITHUB_PAT 和目录名 book-output 是任意的，您可以使用任何您喜欢的名称，只要名称不与现有的环境变量名称或目录名称冲突。该脚本与我们在第 5.1节中提到的构建脚本一起，可以作为 Shell 脚本放在 master 分支中，例如，您可以将它们命名为 _build.sh和 _deploy.sh 。那么您的 .travis.yml 可能如下所示：

    1. language: r
    2. pandoc_version: 1.19.2.1
    3. env:
    4.   global:
    5.     - secure: A_LONG_ENCRYPTED_STRING
    6. before_script:
    7.   - chmod +x ./_build.sh
    8.   - chmod +x ./_deploy.sh
    9. script:
    10.   - ./_build.sh
    11.   - ./_deploy.sh

    The language key tells Travis to use a virtual machine that has R installed. The secure key is your encrypted personal access token. If you have already saved the GITHUB_PAT variable using the web interface on Travis instead of the command-line tool travis encrypt, you can leave out this key.

    language 键告诉 Travis 使用安装了 R 的虚拟机。secure 密钥是您加密的个人访问令牌。如果您已经使用 Travis 上的 Web 界面而不是命令行工具 travis encrypt 保存了 GITHUB_PAT 变量，则可以省略此密钥。

    Since this Travis service is primarily for checking R packages, you will also need a (fake) DESCRIPTION file as if the book repository were an R package. The only thing in this file that really matters is the specification of dependencies. All dependencies will be installed via the devtools package. If a dependency is on CRAN or BioConductor, you can simply list it in the Imports field of the DESCRIPTION file. If it is on GitHub, you may use the Remotes field to list its repository name. Below is an example:

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

    1. Package: placeholder
    2. Type: Book
    3. Title: Does not matter.
    4. Version: 0.0.1
    5. Imports: bookdown, ggplot2
    6. Remotes: rstudio/bookdown

    If you use the container-based infrastructure on Travis, you can enable caching by using sudo: false in .travis.yml. Normally you should cache at least two types of directories: the figure directory (e.g., _main_files) and the cache directory (e.g., _main_cache). These directory names may also be different if you have specified the knitr chunk options fig.path and cache.path, but I’d strongly recommend you not to change these options. The figure and cache directories are stored under the _bookdown_files directory of the book root directory. A .travis.yml file that has enabled caching of knitr figure and cache directories may have additional configurations sudo and cache like this:

    如果您在 Travis 上使用基于容器的基础架构，则可以通过在 .travis.yml 中使用 sudo: false 启用缓存。通常你应该缓存至少两种类型的目录：图形目录（例如，_main_files）和缓存目录（例如，_main_cache）。如果您指定了 knitr 块选项 fig.path 和 cache.path ，这些目录名称也可能不同，但我强烈建议您不要更改这些选项。图和缓存目录存储在书根目录的 _bookdown_files目录下。启用了 knitr 图形和缓存目录缓存的 .travis.yml 文件可能有额外的配置 sudo 和 cache，如下所示：

    1. sudo: false
    2. cache:
    3.   packages: yes
    4.   directories:
    5.     - $TRAVIS_BUILD_DIR/_bookdown_files

    If your book is very time-consuming to build, you may use the above configurations on Travis to save time. Note that packages: yes means the R packages installed on Travis are also cached.

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

    All above scripts and configurations can be found in the bookdown-demo repository: https://github.com/rstudio/bookdown-demo/. If you copy them to your own repository, please remember to change the secure key in .travis.yml using your own encrypted variable GITHUB_PAT.

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

    GitHub and Travis CI are certainly not the only choices to build and publish your book. You are free to store and publish the book on your own server.

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

    1. You need to authorize the Travis CI service for your repository on GitHub first. See https://docs.travis-ci.com/user/getting-started/ for how to get started with Travis CI.↩︎