My Hugo setup for GitHub pages

In this post I will introduce my current Hugo setup. I will show you how I configured the git repositories, how I write new posts and how easy it is to publish the generated site on GitHub pages. With a static site generator like Hugo it is really easy to create a blogging environment where your posts and your site is version controlled and stored in git.

Why I’ve changed my first setup

I’ve tried to use one git repository for the generated site and for the posts in markdown together. It would be a great one repository setup. For user pages at GitHub the generated site content needs to be on the master branch. With this limitation the raw markdown files are needed to be on separate branches. To generate the site with Hugo the master branch can be added as a git worktree under the public directory where your site will be generated. I did not like this setup because the master branch has a completely different history and content compared to the branches for the posts. Adding a new post would mean to create a new branch from your content branch and merge it back to there and build the site from that.

Another option is to manage two separate repositories where in one repository you write and store your posts and only the generated site will be stored in the your other GitHub pages repository. I will use the master branch in the site content repository to generate the site from and I write my posts on separate branches in this repository. I will show you how to configure this setup in the following sections.

Maybe I will switch back to the one repository setup some time but now I will try out the second solution to see how well it works for me.

Setup the git repositories

Create an empty content repository on GitHub and clone it:

$ git clone https://github.com/GH_USERNAME/site_content_repo.git 

After cloning the site content repository the theme and the user pages repositories will be added as git submodules. You can find many great themes here for your site.

$ cd site_content_repo

# add a theme as a submodule
$ git submodule add https://github.com/gyorb/hugo-dusk.git themes/hugo-dusk

$ git add themes
$ git commit -m "add new theme"

# add your github user pages repository as a submodule
$ git submodule add https://github.com/GH_USERNAME/GH_USERNAME.github.io.git public

$ git add public
$ git commit -m "add github pages repository"

We are ready with the git repository setup so we can move on how to create a post.

Write a new post

For each new post I create a new branch.

$ git checkout -b post/my_new_post master

# add new hugo post
$ hugo new post/new_post.md

On the newly created branch I can work on the new post until it is finished and ready to publish. When I’m ready with my post I merge that branch into the master branch.

$ git checkout master
$ git merge post/my_new_post

After merging the branch with the new post I can rebuild and publish the site with the new content.

Rebuild and publish the site

After merging the new post to the master branch I can automatically rebuild and publish the site with a small bash script I’ve created. It will automatically rebuild the site, commit the changes and push them to the repositories on GitHub.

The script allows to rebuild the site only from the master branch and warns if there are uncommitted changes, so the published site and the content repository will not be out of sync.

#!/bin/bash

branch_name=$(git rev-parse --abbrev-ref HEAD)
if [[ "master" != "$branch_name" ]]
then
    echo "Site should be rebuilt on master branch."
    exit 1;
fi

if [[ $(git status -s) ]]
then
    echo "Everything should be committed before rebuilding the site."
    exit 1;
fi

# rebuild the site
hugo

# publish the site
cd public

git add .
msg="site rebuilt on `date +%D`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

git push origin master

cd ..

# add submodule (public) changes
git add public
git commit -m "$msg"
git push origin master

Update the theme

If there is a new version of your selected theme updating it is quite easy.

cd themes/hugo-dusk
# get the lates version
git pull origin
cd ../../

# commit the submodule change in your site_content_repo
git add themes
git commit -m 'theme updated'

This is my current blogging setup and I’m pretty happy with it for now.