Using bookdown with gh-pages

Deploying bookdown to gh-pages with GitHub Actions

R and Shiny Training: If you find this blog to be interesting, please note that I offer personalized and group-based training sessions that may be reserved through Buy me a Coffee. Additionally, I provide training services in the Spanish language and am available to discuss means by which I may contribute to your Shiny project.

Update: I added an “if” statement to push to gh-pages only when you push directly to main or merge a pull request. This is to avoid updating the site before the pull request has been reviewed.

Motivation

Here I explain how to use GitHub Actions to deploy a bookdown site to gh-pages. This approach is more simple than what I used for the R4DS in Spanish project, and also simpler than some of the approaches I have seen in other blogs.

GitHub Actions

GitHub Actions is a Continuous Integration (CI) tool that allows you to automate tasks such as building and deploying your bookdown site. In this post, I will explain how to use GitHub Actions to deploy a bookdown site to gh-pages.

For the R4DS in Spanish project we proceeded in the following order to facilitate contributions:

1. Each user had to translate a chapter in RMarkdown format and submit a pull request.
2. Once the pull request was approved, the chapter was merged into the main branch.
3. GitHub Actions detected the merge and the site for Spanish version of the book was updated.

The problem with this approach is that, while it was simpler for contributors, Netlify had some recent changes. One of these changes was disabling the Ubuntu 16 image, which was used in the chain of steps to build the bookdown site. This left us unable to update the rendered site for R4DS in Spanish.

But we can also use GitHub Actions without Netlify. This is the approach that I implemented now. If you look at the configuration file for GitHub Actions in the R4DS in Spanish repository, you will see that it is very simple. It consists in the following steps:

1. Configure a virtual machine.
2. Build the bookdown site.
3. Update the site for the project.

These steps should be ideal for teams where different people are working on the same project and changing different files at the same time, and this will avoid pushing many different local versions of the site to the repository while focusing on the contents.

For the first step, the gh-actions configuration installs R and all the dependencies for the R4DS in Spanish project site. The simplest option we found was to create a DESCRIPTION file with all the dependencies, as one would do with an R package (https://github.com/cienciadedatos/r4ds/blob/traduccion/DESCRIPTION).

For the second step, the bookdown configuration is set to render the site in the docs folder. This is the default folder that GitHub Pages uses to render sites. This is ideal for a single person working on the project, but it is not ideal for a team of people working on the same project.

For the third step, we make it ideal for a team of people working on the same project. The gh-actions configuration uses an SSH key that we added to GitHub secrets. This SSH key is used to push the rendered site to the gh-pages branch, is it stored safely, and users without access to the repository’ secrets will see a 404 page (error page). With the SSH key configured, the gh-actions configuration clones the gh-pages branch, then updates it locally, and then writes the changes to that branch.

With GitHub Pages configured to serve the site from the gh-pagesbranch in the root folder, the site is updated automatically. This allows to update https://cienciadedatos.github.io/r4ds/ easily, which we redirect to http://es.r4ds.hadley.nz/ with a CNAME file.