Getting started with blogdown - WRUGdown

Blogdown is an R package that allows people to write web sites, especially weblogs, including R code and its output.

By default, blogdown uses a programme called Hugo, which converts Markdown files into static web sites. This is a bit like Jekyll, the software behind GitHub Pages.

What blogdown adds is the ability to write R Markdown posts. These are converted directly into HTML via the rmarkdown R package, which itself uses pandoc.

The writing process works like this¹:

As you can see, you have the choice of writing your posts in R Markdown, or, assuming you aren’t including any executed R code, in Markdown directly. However, Hugo’s own flavour of Markdown, “Blackfriday”, is different to R Markdown syntax, which is based on pandoc. This can get very confusing quite quickly, so just write everything in R Markdown. If you don’t need to run R chunks, simply don’t include any in your .Rmd file.

Installation

Blogdown and Hugo are easy to install on Windows, unlike Jekyll, which is written in Ruby and generally a pain in the arse. To install blogdown, run

devtools::install_github('rstudio/blogdown')

whence you can install Hugo directly from within R:

blogdown::install_hugo()

Create a new site

In RStudio, go File > New Project… > New Directory > Empty Project. Then run

blogdown::create_site()

and everything you need to get started will magically appear!

Write a post

Everything works exactly like a regular R Markdown document, except a few options in the YAML header. Some sample posts are generated when you first create the site, so you can try editing these.

To create a new post, run

blogdown::new_post('Title of your post goes here')

or simply create an .Rmd document from scratch in the content/post/ folder. So that everything appears in the right order in a blog feed, file names should be prefixed with the publication date, in the format YYYY-MM-DD-. You will see in this folder that some posts are in plain Markdown as .md files and processed by Hugo. Files written in the .Rmd format (probably everything you are likely to write) are converted into html by blogdown and stored here, then served by Hugo.

Publish to GitHub Pages

Some subtleties here, as the blogdown documentation is incomplete. Rather than GitHub Pages, blogdown’s authors recommend alternative services such as Netlify or Updog, but I have not tried those yet.

To begin, create a GitHub account if you do not already have one. GitHub Pages sites appear on the web at the address username.github.io/repository_name. You will also need to install git on your computer: download it from git-scm.com, install it and make sure it is on your PATH.

Now, in theory we can only track changes in the generated site, which would involve initialising a Git repository in your blogdown site directory’s public/ folder. This seems silly to me: we never edit the HTML files directly so surely we want to keep track of the source code as well.

In this case, create a new repository on GitHub and call it whatever you like. Go into the repository settings and scroll down to where it says “GitHub Pages”. Click on the dropdown box, underneath where it says “Source”. Select master branch /docs folder. This means it will serve up a web site from your content, but only that stored in the docs/ subfolder. Everything else will be tracked for version control, however.

Of course, everything is actually being served into the public/ folder, so we need to fix that. Open config.toml and add/modify the top of the file to include this line:

publishDir = "docs"

Now when you regenerate the site using

blogdown::serve_site()

blogdown::build_site()

it should put everything in docs/ instead of public/. You can delete the public/ folder now as it is no longer needed.

In the main directory, create an empty file called .nojekyll. You can do this in R using file.create('.nojekyll'). This stops GitHub from trying to process your site using Jekyll; when you upload it, it will already have been generated by Hugo.

Now, back in RStudio, go to Tools > Project Options… > Git/SVN. At the “Version control system” dropdown box, select “Git”. A dialogue box will ask if you would like to initialise a new Git repository. Say “yes”.

You should get a tab appearing in the top-right of your RStudio session that says “Git”. Open this pane and tick all the boxes next to the files (or docs/ and .nojekyll at the very least). Click “Commit” and enter a suitably descriptive message (“Initial commit” is popular for your first one), click “Commit” and close the pop-up dialogues once everything has completed.

We want to connect our local git repository with the one on GitHub. To do that, in your Git tab, click More > Shell…. A command prompt (terminal) will open. Don’t panic; just enter the following lines (which will be suggested to you on your GitHub repository page):

git remote add origin https://github.com/USERNAME/REPONAME.git
git push -u origin master

replacing USERNAME with your own GitHub username and REPONAME with the name of your repository. When prompted, enter your GitHub username and/or password (you can avoid being prompted for your username by connecting via SSH).

Close the terminal—you shouldn’t been needing it again.

Wait a few minutes and then visit http://USERNAME.github.io/REPONAME. What do you see?

In future, you can commit and then push changes to the Web using the “Push” button in RStudio.

Incidentally, this flow diagram was created using DiagrammerR.↩