R markdown on GitHub Pages | automated with GitHub Actions
How to publish bookdown projects with GitHub Actions on GitHub Pages
A 10 step guide to a completely automated and pure GitHub workflow for hosting your bookdown project on GitHub Pages. No Travis. No Jekyll. No Hugo. Not local.
After writing the first parts of my Bayesian Network Compendium in a classical LaTeX document, I was looking for the optimal solution to receive continuous feedback on the manuscript and make it available to a wide audience while still working it.
Overleaf is a great tool for reviewing LaTeX documents. You share a link to the document with people you’d like to contribute — either by writing or commenting. This process is great if you publish after completion of the manuscript as it is customary in peer-reviewed scientific journal articles.
However, I aimed for an open source and continuous publishing method, where every one can contribute by giving feedback, ask for a specific topic to be covered or fix mistakes by still ensuring a peer-review quality. Similar to wikipedia but less public and more specific. Additionally, running R code directly in the document would be great. That was the point when I came across the R-package bookdown which could meet basically all my requirements.
bookdown could meet all my requirements.
The Concept of bookdown
With bookdown you can write your manuscript in R-Markdown (.Rmd vs .md) and publish it as a website online. It’s straight forward to use even if your only little familiar with R and Rstudio (whereas the latter being no precondition though). Bookdown basically creates for each chapter a separate .Rmd file, compiles them to .html and wraps it in a nice theme. You can also compile it to .epubs and .pdf but I won’t go into that in this article.
The .html files (which were compiled from the .Rmd files) are all stored within the _book directory which basically serves as a static website.
There are multiple ways to publish your book or manuscript online with bookdown.
To publish it on your own webserver, you just copy-paste the _book directory.
Bookdown ships with the command bookdown::publish_book() to directly publish on the R Studio Connect server where you first have to register.
To host on GitHub Pages the recommended way to connect with bookdown is via Jekyll (a static website builder) or by pushing the locally rendered .html files on a branch named gh-pages and tell GitHub to publish from this branch. This manual process can be automatized in a script.
Alternatively, the fully “Githubian-way” is using GitHub Action instead of Jekyll. The concept is easy: After pushing your uncompiled bookdown project (no _book directory, no .html files) to your GitHub project repository, you create a second branch gh-pages . Then you add a GitHub Action workflow to the master branch and… voilà, there’s your first bookdown publication rendered and published by GitHub only.
Let me guide you through the process step by step.
- We install the R package bookdown
- We configure our bookdown project with GIT and connect to GitHub
- We setup a Github Action workflow for rendering on GitHub and deployment to GitHub Pages.
Jump to step 3 if you already have your bookdown project on Github.
I Install bookdown
I assume you have a running and updated R and RStudio installation.
- Download the GitHub Repository as a zip file and unzip it in your new project directory
2. Install the bookdown R package
3. Open the R Project from the demo repository in R Studio.
4. Open within R Studio the file index.Rmd and render the demo bookdown
You should now see in the viewer pane of R Studio the rendered demo page. Check the official manual for more detailed information.
II Setup your bookdown Project with GIT & GitHub
5. Let’s first clean up our project directory and initialize a new GIT repository
6. Create an empty GitHub Repository testbookdown-repo on Github.com
7. Connect your local GIT repository to the fresh repository on GitHub and push your master branch
III Create a Github Action workflow
Start here, if you already have your bookdown project on GitHub but keep an eye on step 5!
8. Create a local empty gh-pages branch and push to testbookdown-repo on GitHub.
9. Create GitHub secrets GH_PAT and EMAIL. GH_PAT is a personal access token with repository access. EMAIL is the mail address you use to login to GitHub.
- GH_PAT: Go to the developer settings of your GitHub account and create a new token. Copy the code you’ll receive and go to your repository’s secrets in the tab “settings” (https://github.com/<username>/testbookdown-repo/settings/secrets) and create a new secret named
GH_PATand paste the code of the token. - EMAIL: Go to your repository’s secrets in the tab “settings” (https://github.com/<username>/testbookdown-repo/settings/secrets) and create a new secret named
EMAILand enter your mail address that you use to login to GitHub.
10. Go back to your R Studio session (master branch) and add with this command
automatically the GitHub Workflow shown below in the required directory: .github/workflow/deploy_bookdown.yml
The workflow basically consists of two parts. First it sets up a container with an R installation set for compiling bookdown projects. After rendering the book it stores the _book/ directory which is in the second part deployed to GitHub Pages.
GitHub usually automatically chooses the branch gh-pages with an index.html file present to publish on GitHub Pages. This can be changed in the repository settings. That’s also where you find the link to your GitHub Page.
Continuous Review Process with GitHub
Check out my next article on how our team makes use of GitHub to continuously extend, review and integrate changes in the text while always having the latest version online. I’ll also show how to get all out of bookdown and make full use of LaTeX.
