Hugo on gh-pages
All the power of hugo with the convenience of gh-pages

Traditional web hosting and web application frameworks have become a bit of an annoyance for me. If you use Wordpress or Drupal you likely can sympathize with the never ending stream of updates and such. Many of them actually make your site less stable. Then there is the problem of keeping your site backed up in case your cheap hosting provider accidentally deletes all your work. Well no more…

I am now managing the content of this website in static markdown files compiled with hugo and then hosted for free using gh-pages. This is how I did it…

This is not a hugo tutorial, so I will assume you have built something in hugo and you have run hugo server -w and can view the website locally.

Your config.toml file will probably look something like this:

baseurl = "http://<username><reponame>/"
languageCode = "en-us"
title = "Website Title"
theme = "your-theme"
canonifyurls = true

Now you are ready to start working with gh-pages.

# create the git repository to track your actual website on gh-pages
$ cd public # or whatever your hugo 'publishdir' is set to
$ git init # to create a git repo
$ git add .
$ git commit -am "initial publication of content"
$ git branch -m master gh-pages # rename master branch to gh-pages
# create a new repository on GitHub and then set it up as the remote for this repo
$ git remote add origin<username>/<reponame>.git
$ git push -u origin gh-pages

# now track the whole source in a different git repo
$ cd ..
$ git init
$ git add .
$ git commit -am "source of initial publication"

At this point you should see your website at:

BONUS POINTS: If you want to use a custom domain name, you would do the following.

Change your baseUrl to the new domain.

# cd to parent git repo and modify your config.toml file to reflect the new baseUrl and run
$ hugo --baseUrl=""

Now update the public repo with this change.

$ cd public
$ vim CNAME # you can use whatever editor you want
# add just the domain name to this file and save.  eg:
$ git add .
$ git commit -am "added a CNAME and updated urls"
$ git push origin gh-pages

Then on your domain registrar (like you would do the following:

  • Edit DNS settings
  • If using a subdomain, create a CNAME that points to http://<username><reponame>
  • If using a base domain, create an A Record to either or

Now once the DNS has propagated you will be able to navigate to your domain and see your website.