How to Configure Hugo Site With Github Pages for Custom Domain

Published On: Dec 24, 2018

TL;DR This post walks through the specific configuration required in Hugo's config.toml file to setup custom domain on

Hosting a static site on Github is pretty easy but there are some obscure configurations needed to get everything setup properly. This post walks through few of those for setting up hugo generated site with Github.

Hugo’s official documentation on how to Host on GitHub has almost all the details that is required to configure Hugo and successfully host your static website on GitHub Pages. I got lost in the custom domain step on which the page does not have much details, except setting up the CNAME file. It then defers to the official Github page for any custom domain configuration.

Let’s start with config.toml

I struggled quite a bit with the baseURL config. The official Hugo page instructs to use <USERNAME><PROJECT>/ whereas few online blogs and forums mentions to use https://<USERNAME><PROJECT>/ or //<USERNAME><PROJECT>/. I tried all of these in vain but then with some hit and trial (and realization in hindsight) that using, the actual domain name, only makes sense. No need to specify github project URL or anything else.

This might be obvious to others, but I struggled and thought to put it out to the world to save others from going through this.

baseurl = ""	#config for github pages
publishDir = "docs"                     #config for github pages

theme = "hugo-editorial"
# Define the number of posts per page
paginate = 9
date_format1 = "Jan 2, 2006" #this config is not working
DefaultContentLanguage = "en"

Entry into CNAME file

This file should have the domain name entry without any http, https or www protocols or prefixes.

And that’s all you need. Make sure to enable HTTPS support as it comes for free with GitHub Pages hosting and Chrome won’t flag your site as insecure. You will find it under project Settings → GitHub Pages sections → Enforce HTTPS.

See Also