Hosting pages on Github using Rmarkdown and Hugo

Tech R, R Markdown, R Blogdown, Hugo, github

My personal website is created by R package blogdown and Hugo1 and is hosted on Github. This page summarise my steps to setup the site.

Creating github repositories

Two respositories are needed for the site.

  1. I create blog_hugo to host Hugo’s content)

  2. I create <my-user-name>.github.io to host the public folder, which contains the static website.

Installing Blogdown and Hugo

Install blogdown.

It is under heavy development when I write this blog.

# check devetolls
if (!("devtools" %in% installed.packages())) {
  install.packages("devtools")
}
devtools::install_github('rstudio/blogdown')

Install Hugo

As I use Deepin Linux, a debain-based distro, I install Hugo via apt package manager. For other installment choices, read the Hugo installation instructions.

sudo apt install hugo

However, the Hugo in the repository is updated and it does not work for most templates. I manually download its deb package from the release page and install it.

Creating the Site

Creating a Rproject of my new site

  1. Clone blog_hugo to my computer
cd <parent-folder-of-blog_hugo>
git clone <my-blog-hugo-repository> && cd blog_hugo
  1. Create a Rproject based on the existing folder blog_hugo. It is a R project with the git system by default.

Creating a new site

  1. Pick a Hugo theme from http://themes.gohugo.io. I use Academic for my site.
  2. Creating a new site
blogdown::new_site(dir = ".", theme = "gcushen/hugo-academic")

Hosting the Site on Github

Use the submodule to sync my local sites(the public folder) with <my-user-name>.github.io

git submodule add -b master git@github.com:<<my-user-name>/<my-user-name>.github.io.git public

As SSH is used to sync with Github, I need to create my own private key pair set in advance.

cd ~/.ssh && ssh-keygen
cat id_rsa.pub

Then, we copy the key to our github account via the website. More information can be found here

Creating Scripts

Add a serve_site.R script in blog_hugo folder to generate static sites in case Rstudio is not running.

#!/usr/bin/Rscript
blogdown::serve_site()

Add a deploy.sh script in blog_hugo foler to sync the site (and make it executable: chmod +x deploy.sh)

# Go To Public folder
cd public
# Add changes to git.
git add -A

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back
cd ..

The Last Step

Modify the theme as we like and enjoy the new site.

  1. Hugo can be used to hosting other types of pages on Github. More information can be found on its website↩

comments powered by Disqus