A few months ago, I attended an R ladies NYC workshop on creating websites with Blogdown and Hugo themes. with For the R user who is looking to generate their own webpage - look no further!

The Blogdown R package has powerful capabilities without needing to learn html or java, and Hugo has a seemingly endless choice of beautiful website themes.

Why use Github pages to deploy the website? First, it’s free - every github user has a free domain to use. Second, it’s easily linked to your github profile. Third, it really encourages you to version control your website!

Here, I am going to walk through a step-by-step guide to generate a webpage from beginning to end, using Blogdown, Hugo and Github pages.

Part 1: Build your website

Choose a theme for your website

Hugo has a wide array of website themes, which can be found here. Themes dictate both the aethetics and the format of a website. Choose wisely - once you start with a certain theme, it’s hard to switch themes later.

After you’ve chosen a theme, click “Homepage” on the theme website, which leads you to the owner’s github repository for the theme. We will use this github project (e.g. “user/themename”) as input to the blogdown::new_website function.

Use blogdown to generate a website template

Now we’re ready to start working with blogdown. Start a new R project, and then generate a new blogdown website using your chosen theme.

install.packages('blogdown')
install.packages('hugo')
library(blogdown)
blogdown::new_site(theme = "user/themename")

Edit content on your website

Every theme has a slightly different setup, but we will walk through the basic overview. I also recommend reading the theme documentation for more details.

• Config and/or menu files: Contain the backbone structure of your website. Config files designate the url, theme, and title of your website. Menu files designate the “widgets” or components of your website (which varies by theme). Disclaimer: depending on the theme, these files may be in the main directory or different locations (e.g. in the “data” or “config” folders) and might end with either “.toml” or “.yml”.
• Content: Where most of your editing will take place. The organization of this folder will vary depending on your chosen theme, and the files here should coincide with your menu.
• Static: The storage location for any static files that you add to your website. For example, you can add PDF files or images that you link in the content.
• Themes: Stores the necessary code to build the website using your chosen theme. Do not edit!
• Public: Contains the live website, built from the contents and configurations. Do not edit!

Preview your changes

Blogdown also makes it really easy to preview changes. With this commmand, the webpage will display in the viewer panel and can be expanded to full view, just like any other html document.

blogdown::serve_site()

There is some trial-and-error to figure out how changes in the content files correspond to changes in the website. Try making a simple change first, like changing the title of your webpage in the config file, and see how it changes your webpage.

Do I need to run serve_site() after every change I make?
It depends. After running it once, the webpage preview will automatically refresh after each time you save changes to existing files, but if you remove or add new widgets, you will need to re-run the command to view those structural changes.

Part 2: Link the website to Github & Github pages

Make a ‘webpage’ repository

Websites change, and websites also break… but this all becomes much more manageable with version control! First, you want to make a new github repository, and link it to a new R project.

Not familiar with linking github and R? When making a new new R project, choose the option ‘from version control’, then ‘Github’. On the next page, add the link to your git repository.

The ‘public’ folder should not be added to this repository! An easy way to deal with this is to add the public directory to your .gitignore file.

When you’re happy with the content of your webpage, add, commit and push the website content to the ‘webpage’ repository.

Make a ‘github pages’ repository

Hugo, like many other website platforms, separates the editable content of your website from the live website content, also commonly referred to as the “public” content. To deploy the website, we will sync the “public” folder to Github pages.

First, make a new repository on github called username.github.io. Github pages will automatically generate a webpage from any repository with this specific name, so unfortunately you cannot be creative here. Then, add the ‘username.github.io’ repository as a submodule of the ‘webpage’ repository.

For these few lines of code, we need to excute git commands in terminal, outside of R studio.

cd /path-to-webpage/** 
rm -rf public
git submodule add -b master https://github.com/username/username.github.io.git public

This enables the ‘username.github.io.git’ repository to contain only the ‘public’ directory of your website.

Finally, update the website address in the config.toml file. Simply replace “baseURL” with your github pages url (https://username.github.io).

Deploy your changes to the live website

When you’re ready to make your webpage live, the process is pretty painless. Simply add, commit and push your public website content to the github pages repsitory, and the webpage will automatically update at https://username.github.io.

cd webpage/public
git add . 
git commit -m "my message here"
git push origin master 

You now have a functioning website built with github, R and hugo!

Further reading

• For additional information and trouble-shooting, see the related Hugo documentation for hosting websites on github pages.

• For an excellent resource on using github with R, check out this excellent resource: Happy Git with R.

• For more blogdown details, far beyond the scope covered here: Blogdown documentation