Hey, hope you’re well! There’s a few prerequisites that you’ll need to meet before this walk through will be useful. Firstly, and hopefully this is obvious, you’ll need a Github Pages site published to see the end result; preferably generated by Hugo but I wouldn’t be surprised if there was some crossover to other static site generators. Secondly, you’ll need your own custom domain. Or, at least the ability to create a CNAME record in the domain you wish to configure. More on that later!

If you haven’t yet created your static site, I’ll take the opportunity to link you to my previous post: Getting started with Hugo Hosted on Github Pages. In the referenced post we configure Hugo, a static site generator and publish the site using Github Actions.

Now, lets get stuck in.

Update Github Repository Settings

1. Firstly, go to your Github Pages Repository and go to Settings

2. Navigate to the Github Pages section

3. Add your desired custom domain. You can use either your apex domain (example.com) or a subdomain (www.example.com or blog.example.com).

So what does this do? After selecting save, Github commits a single file named CNAME to your publishing branch. If you’re unsure what your publishing branch is, it’s the branch shown under source just above the custom domain settings. The problem with this is that when Hugo builds our site through Github Actions that CNAME file is removed. So hold off pushing any new changes that will trigger the Github Action for now! Next we’ll configure our Custom Domain’s DNS.

Update your DNS Settings

First, you’ll need to decide whether you’re going to use your apex domain or a subdomain for your site. Once that’s decided, you only need to go through one of the sub sections below.

Using a Subdomain

1. Go to where you manage your domain’s DNS configuration. Usually, that is your domain registrar.

2. Add a CNAME record pointing to your Github Page. For me, that means adding a new CNAME record named blog pointing to mattdaines.github.io

Initially, I started with a low time-to-live (TTL) for the record. Once I was confident everything was setup and working correctly, I upped the TTL to 24 hours.

At the time of writing I don’t use my apex domain for anything in particular. So, I’ve also setup forwarding on my apex domain to redirect requests to this blog.

Using an Apex Domain

As I use a subdomain I’m less familiar with adding the apex domain as a custom domain but the process appears to be largely similar to adding a subdomain.

1. Go to where you manage your domain’s DNS configuration. Usually, that is your domain registrar.

2. Add an A record pointing to the addresses documented in the Github Pages documentation.

Preventing CNAME file being removed by Github Actions

So, now that we have a custom domain configured how do we prevent our static site generator from removing the required CNAME file that Github creates? Fortunately, with Hugo it’s pretty simple!

1. In your site root, create a directory named static

2. Create a file named CNAME - make sure there’s no file extension

3. Add your custom domain name to this file. For my site that would mean a file containing blog.mattdaines.me.

Remember, you can always reference your publishing branch to check how this file should look.

Before we push/PR any changes we should check that this static file is generated.

1. Open a console to the root of your site

2. Run hugo to build the site

3. The site will publish locally under a directory named public. In the public directory you should see a file named CNAME, in all capital letters. The file should contain your custom domain on a single line with no trailing spaces.

References

And that’s it! Here are some references that helped me.

Github Pages - Custom Domain with Subdomain

Github Pages - Custom Domain with Apex Domain

Hugo - Using a Custom Domain