Yihui Xie’s new blogdown package is a brilliantly elegant and simple tool for creating R-themed blogs and web sites. Starting your own blog is as simple as one line of R code:
By default, blogdown uses Hugo, a static web site generator written in Google’s Go programming language. This has a number of advantages over Jekyll (the site generator that powers GitHub Pages) and from personal experience, everything just seems to work more smoothly.
Previously I wrote about automatically deploying an R Markdown Jekyll blog with Travis. In this post, I am going to explain how you can use Travis to knit your R Markdown blog posts, then publish them with Hugo/blogdown.
Why Travis? In the official blogdown documentation, Yihui recommends Netflify, a rival service, instead. However, for the time being at least, Netlify doesn’t have R support. This means that any R Markdown (vs plain Markdown) posts you write will need to be built locally before pushing them to your Git repository, and therefore you can only maintain R-infused content from a computer with R + blogdown installed.
In an ideal world, you should be able to create content from any computer (or device) that has a web browser. Therefore we will push plain text to Git and have Travis compile all the R chunks for us, then automatically push the built site to GitHub Pages.
A few weeks ago Neal Richardson published a post on a similar topic, but that guide is a bit more complicated than it needs to be, because it doesn’t take advantage of Travis’s native GitHub Pages support.
You should be able to get up and running extremely quickly, with minimal Git knowledge required. Want to see a fully working example? Take a look at this site’s GitHub repository. For a minimal (non-Travis) blogdown site, see this example site.
Install blogdown with
then, in an empty folder, create a site.
For a crash course in blogdown and Git for beginners, read my post Getting started with blogdown. More complete information is available in the official blogdown book as well as the online Hugo documentation.
Want a web site that looks like mine? Run
then switch your
hugo-tea in your
Linking GitHub to Travis
This follows my earlier guide.
Create a GitHub personal access token, making sure the “repo” box is ticked so it has permission to push to repositories. Copy the token to your clipboard.
On Travis, enable the GitHub repository corresponding to your blogdown site. In Settings, create a new environment variable called
GITHUB_PAT and paste your token into the Value field.
In the root of your directory, create a file called
.travis.yml containing the following.
language: r cache: packages branches: only: - source r_github_packages: - rstudio/blogdown before_script: - Rscript -e 'blogdown::install_hugo(version = "0.20.7")' script: - Rscript -e 'blogdown::build_site()' deploy: provider: pages skip_cleanup: true github_token: $GITHUB_PAT on: branch: source local_dir: public target_branch: master
If you are hosting your site on
username.github.io—like my site—there is no need to change any of the settings above.
You push your code to a branch called
source and the compiled site is deployed to
If, instead, you have a Project Page (i.e. if the repository is called anything other than
username.github.io), you can replace
gh-pages. Or just leave it how it is—just make sure your repo settings have the
target_branch set as the “Source” for GitHub Pages.
Travis’s R environment was originally designed for testing R packages, not building web sites.
As a result, Travis will complain if it doesn’t find a
DESCRIPTION file—the minimum requirement of an R package—in your repository.
It is enough to add a placeholder
DESCRIPTION file with the following arbitrary contents:
Package: arbitrary Title: Does not matter. Version: 0.0.1
This is enough to convince Travis to proceed.
Now, when you push a new commit to the
source branch of your GitHub repository, Travis will clone it, build the site and push it to the
In my experience it takes about two minutes from pushing changes to the updated site being live.
If you have nothing better to do then you can watch Travis as it tries to deploy your blog. There’s no need to monitor it, though: if it fails for any reason, you’ll receive an e-mail.
Hopefully this guide helps. If you have any questions or feedback, feel free to leave a comment below or contact me.