Hugo on Github Pages

Notes on how to public a Hugo website on GitHub Pages.

When you start using GitHub Pages, you will probably use GitHub’s default static site generator - Jekyll. I love Jekyll, but I’m also becoming rather frond of Hugo. Hugo is an increasingly popular static site generator, known for its speed, and I love how quickly I see feedback when I tweak a Markdown file and see the page reload almost instantly. Hugo also has an ever-improving set of external helpers to enable richer features.

Switching to Hugo as the static site generator is relatively straightforward, and there are excellent instructions for how to host Hugo sites on GitHub Pages in the Hugo documentation. I won’t repeat them here, as I followed those steps and they worked - almost.

When I deployed using those instructions, the homepage showed the contents of the project README.md. This is because:

1. By default, Hugo generates the site in a folder called public.
2. By default, GitHub Pages renders the index page in the root of the project.
3. My GitHub Pages settings were using the root folder in the main branch.

Go into your project’s Settings/Pages configuration and there is an option to change the folder where GitHub Pages builds the site. The Deploy phase of your gh-pages.yml sets up a new branch called gh-pages containing the content of the ./public folder. Therefore this setting should ensure that your Pages site is based on branch gh-pages and the root folder.

Once you have made these changes, when you deploy the site, GitHub Pages should display your Hugo site.