How to make a website with R blogdown, Hugo, and GitHub

Blogdown and Hugo

First thing’s first: the blogdown package and Hugo need to be installed. You can also begin choosing your theme at this point - find a theme here.

In R Studio:

# install Blogdown from Github
install.packages('devtools')
devtools::install_github('rstudio/blogdown')

# use blogdown to install Hugo
library(blogdown)
install_hugo()

Github

Set up your Github repositories. We’ll follow the “User Page” example where your website is going to use your Github username: username.github.io.

Using the + icon in the upper right corner of your github page, create the following new repositories. Don’t bother creating a README.md, as blogdown needs an empty directory. I think. At any rate, you don’t need a README.

• username.github.io, replacing ‘username’ with your username. This will be used to host your site on the master branch, using the ‘public’ folder produced from Hugo
• website-hugo - This repository will contain all the source files from blogdown/Hugo

Back to RStudio

Next we need to create the site in RStudio using blogdown and Hugo, and then link this with the two repositories. In my normal research life, I tend to use R Projects with the built-in git capabilities, but for some reason, that gave me a lot of problems in this case. So I created an R Project for the Hugo source files, but then manually added Git to the folder and manually linked it with Github via Git Bash (rather than just intializaing the R Project straight from the Github repository, which is what I usually do. That kept crashing for me today).

So, either create an R Project or just use a dedicated working directory for your website source files. If not using an R Project, set your working directory using setwd("path/to/your/folder"). Note that commands such as new_site() and serve_site() will load your website in the RStudio viewer, and you will need to hit the stop sign to exit viewing mode and go back to coding.

This is also where you will install your theme, found here. Being an academic type, I chose Academic.

# create your site
library(blogdown)
new_site() # then hit stop

# install theme
install_theme("gcushen/hugo-academic", theme_example = TRUE, update_config = TRUE)

# make/view website with new theme
serve_site() # then hit stop

You’ll notice there are now a bunch of folders and files in your working directory, including the ‘public’ folder. Don’t move anything manually - we’ll do it in Git Bash.

Git Bash/Terminal

This part got a little fuzzy for me, because I ran into several problems including SSH authentication, the R Project Git confusion I mentioned above, and I seemed to also have a problem using the git submodule command on an empty repo. So this could probably be tweaked over time, because I’m not sure if all the steps I took are required in sequence.

Open your terminal/Git Bash and cd to your project directory for the source files (website-hugo to match my github repo, in my case). If you’re not set up with SSH yet, do that here.

Remove the public folder

rm -r public/

Initialize a git repository

git init
git remote add origin git@github.com:username/website-hugo.git

Try linking the public folder with your username.github.io repo via a submodule now, but it didn’t work for me just yet…

git submodule add git@github.com:username/username.github.io.git public

Instead, I had to commit and push my hugo source files first, then run the submodule command

git add -A
git commit -m 'initial commit'
git push origin master

git submodule add git@github.com:username/username.github.io.git public

Leave Git Bash open, but go back to R Studio

Back to RStudio

Not really sure if this is necessary…but make a few changes to site, such as altering the config file or trying new_post("Hello World"), then “compile” the site again.

# make a test post if you're into that
new_post('Hello World')

# compile site changes: preview within R Studio
serve_site() # then hit stop

# compile site without preview:
build_site()

Back to Git Bash

Now we need to commit our new changes and push them to the “public” folder. So, if you were already in your project directory:

cd public

git add -A
git commit -m 'initial site'
git push origin master

And Voila! your website should now be available at username.github.io, and you should have a whole mess of files in your username.github.io repository now. Repeat those steps for any website changes you make:

• work on your site in RStudio
• run build_site()
• open Git Bash, cd to your public folder, and add/commit/push changes

I had also made a local repository for username.github.io…but I’m not sure if that’s necessary either. I haven’t used it yet, and you can always recreate the files pretty easily with blogdown/Hugo.

New page types

Blogdown contains wrapper functions to run Huge commands. So instead of hugo new post/my-article-name.md, you enter wrapper functions directly into the console, such as new_post(title="My article name"), plus additional arguments as needed (see code examples below.)

I’m learning this as we speak with this blog post, but the rmd = TRUE argument took me a moment.

# to make a new blog post, using Rmd instead of md:
new_post(title='How to make a website with R blogdown, Hugo, and GitHub', 
         rmd = TRUE, 
         categories = c('R', 'Hugo', 'Github','website'), 
         tags = c('R'))

# to make a new publication page:
new_content(path = 'publication/food-energy-water-nexus.md',
            kind = 'publication')

Deleting files from website

There’s no way to remove files from the website without re-generating the full public folder. There’s no problem when adding content, such as new posts, but the only (?) way to remove a post is to:

• manually delete the contents of the public folder on your computer from the website-huge folder
• delete the contents of jdeines.github.io using that cloned repository and commit
• re-run build_site(), which will regenerate all of the pages
• then add/commit/push that to Github.

Updating your theme

You can update your theme by forcing a new installation of the theme. Note that this will overwrite any changes you’ve made, and you will need to specifically check your config.toml and front matter on all content pages to ensure they match the settings in the new files. It’s a good idea to rename the current theme folder under the themes folder to ensure you can revert back if things go wonky.

To install the academic theme again:

# update theme by overwriting
install_theme("gcushen/hugo-academic", theme_example = FALSE, update_config = TRUE, force = TRUE)

I also made a new site with the updated theme in order to easily check for differences in the settings but not muddy my website project. To do this, I:

• In RStudio, go to File > New Project > New Directory and select build a website
• Fill out the form, and for the academic theme enter ‘gushen/hugo-academic’ in the theme option. Uncheck the boxes.

Recommended Workflow

Modified from The Blogdown Docs

• Open the project in RStudio
• Set options(servr.daemon = FALSE), since true repetedly crashed my RStudio. You can also add this to your .Rprofile if you’d prefer
• To preview site, click the RStudio Add-in Serve Site. You can keep this active as your work to update as you go (or encounter errors as you go, very helpful)
• Under Tools > Project Options, be sure that the “preview site” box is unchecked under Build Tools.
• To publish, RESTART the R session and run blogdown::hugo_build(). This will process your website into the public/ directory.
• Note: never hit the knit button

My submodule connection broke somehow, so I then:

• delete the contents of a separate R project which houses my website files
• copy and paste the public/ directory into this folder
• push those changes to my jdeines.github.io repository

Someday I’ll fix that. There are some updated? instructions for that here.