How I Created This Website Using Hugo and GitHub Pages

As we know from an earlier post this site is a statically generated Hugo site hosted on GitHub Pages, so I thought it would be interesting to do a post detailing the steps involved in getting the site up and running. These instructions should work on a linux based OS or on MacOS.

Firstly, what will we need. You will need to install git, hugo and have a GitHub account.

The first thing I did was log into the GiHub site and create two repos, one for hosting the site and one source repo as follows

sitename
sitename_source

Next, we open a terminal window, create a folder for the project and change into that new folder

mkdir projectname
cd projectname

Now we can use Hugo to build a new skeleton site, then change into the site directory

hugo new site sitename
cd sitename

Time to create our local git repository for our site source

git init
git remote add origin <sitename_source url>
git add .
git commit -m "Initial commit"

Whatever Hugo theme you choose will have installation instructions that you can follow in order to add it to your new site. I chose the mainroad theme that I added by adding a git submodule.

git submodule add https://github.com/vimux/mainroad.git themes/mainroad

Hugo themes will typically come with an example site so I found that the best thing to do is to copy this into the main directory of my site and then update the config.toml file and add my content.

cp -r themes/mainroad/exampleSite/* .

This is where you now make your changes to suit your content. The best themes should have a guide on how to update the config.toml file. Any images you have will go into the static folder and your posts will go into content. Once you have added your content you can build the site locally and check it out.

hugo server -D

Once you are happy with how the site looks locally, you can add the theme and content to you source repository and push it to GitHub

git add .
git commit -m "added theme and content"
git push --set-upstream origin master

Now we can build our site and push it out to the repository in which we will actually be hosting the site

hugo
cd public
git init
git remote add origin <sitename url>
git add .
git commit -m "Initial commit"
git push --set-upstream origin master

Once pushed, go to your site repository, then settings and pages. Set Source to Branch:master, then you can test it by clicking the “published at” link.

Congratulations, you now have a Hugo generated site hosted on GitHub Pages.

If you have a custom domain that you want to use, you will need a CNAME file in the root of your GitHub Pages repository containing the domain, so mine just contains

linuxpaulm.club

Next, you will need to log into your account with your domain registrar and add four A records with host @ and the following IP addresses

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

You will also need to add a CNAME record with the host “www” and the value of

<your github account>.github.io.

Note the last . is required.

Finally, go back to your GitHub Pages repository, go to settings, then pages and add your domain under Custom Domain; now you can wait for DNS to propagate.

As a bonus, here is the script I run from the site root directory when I add a new post to automate everything

#!/usr/bin/env bash

  

set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

  

git add .

git commit -m "Add site files"

git push --set-upstream origin master

  

hugo

cd public

  

git add .

msg="rebuilding site $(date)"

if [ -n "$*" ]; then

msg="$*"

fi

git commit -m "Add site files"

git push --set-upstream origin master