Getting Started with Hugo or: How I Learned Hugo Doesn't Like GitHub Pages and Used Netlify Instead

· 6 min read

Getting Started With Static Site Generators

Knowing that this would need to be easy if it was going to happen, Static Site Generators were a no-brainer. The real question was: Jekyll or Hugo?

Unsurprisingly, the internet had opinions. In the end I found the information I needed on forestry.io.

Jekyll looks like it’s been around longer, but Hugo looked better designed for what I want - a simple site to host content. I’m unlikely to have time to be building my own features so the more expansive in-built functionality was a positive and the absence of Jekyll’s extensibility wasn’t an issue.

I was anxious about Hugo’s mentioned “non-standard” templating syntax, but given everything was going to be new to me I figured it wouldn’t make much of a difference!

Having a go with Hugo

Having decided on Hugo, I was pleased to discover that the documentation for my first steps was pleasantly straightforward. Beyond a brief foray into Windows package managers (I went with Chocolatey, Scoop would have served perfectly well I have no doubt!), The test website was up and running locally in minutes. Success! I was high on a cloud of satisfied progress.

From there I mocked up this website, created my first post, and that was it! 15 minutes of reading, making decisions, and following a simple tutorial and a had a website. I was starting to wonder why I’d taken this long to do it!

GitHub Pages Pain

The obvious next step was getting the site off localhost and onto the web. A quick scroll back up the wonderful source of all things website-building, the Tech Nottingham Slack #homebrew-website-club, gave me a starter option: GitHub Pages. As I my repository was hosted in GitHub anyway this seemed like the obvious choice.

How wrong I was.

I’ll give Hugo its due: There is Documentation. However, I don’t feel there are quite enough warnings on the page that if you don’t do everything in exactly the right order, you will enter a world of pain in which you spend an hour digging into submodules trying to unpick things.

I got there eventually, but the following caveats are worth noting:

  1. I would recommend leaving step 2 (creating the github.io repo) until after step 5. Working with two repos made things confusing and I found myself doing actions on the wrong repo.
  2. Otherwise, it is extremely important to do everything in the listed order, particularly steps 5 and 6. Failure to do this will increase your chance of ending up in Submodule Hell.
  3. As anyone who has ever worked with Git Submodules knows, they hate you and are poised for the opportunity to make your life a misery. I found that:
  • Git does Not like you using an empty repo as a submodule. I got lots of errors along the lines of
     fatal: 'origin/master' is not a commit and a branch 'master' cannot be created from it

​ The only way I could fix this was by making sure there was a commit against the repo

  • If your submodule creation goes wrong and you have to redo it, you may find yourself seeing a lot of this error:
     A git directory for 'public' is found locally with remote(s):
       origin        https://github.com/<username>/<username>.github.io.git
     If you want to reuse this local git directory instead of cloning again from
       https://github.com/<username>/<username>.github.io.git
     use the '--force' option. If the local git directory is not the correct repo
     or you are unsure what this means choose another name with the '--name' option.

To fix this, not only did I have to delete the “public” folder in the base directory, I had to delete it in .git/modules AND make sure there was no reference in .gitmodules.

I did also have a number of failures around not committing everything to the repo and accidentally losing files (it had been an exhausting week!), but I got there eventually!

Once I had managed to unpick errors and finally get back to a working setup, updating was reasonably simple - make your changes, build the site, run the deploy.sh script which pushed the changes to the .github.io repo that the site is hosted from. I have found that site updates coming through can be intermittent - sometimes you have to go to /index.html in order for changes to be picked up.

Moving to Netlify

A second foray back into #homebrew-website-club resulted in congratulations on finally getting a website up (thanks all!) and expressions of similar experiences with Hugo and GitHub Pages.

All in all, minus distractions, following Hugo’s docs took about half an hour. It would have taken about 15 minutes if I’d followed the instructions (more on that later).

In order to move, I had to:

  • Remove the submodule link on the public directory
  • Add a netlify.toml

That was it, basically! Netlify’s UI was very easy to use and swept me along with it so impressively that I got tripped up forgetting to do the latter - you’re likely to get errors if you don’t have the following line (or similar) in your netlify config:

[context.deploy-preview.environment]
  HUGO_VERSION = "0.73.0"

It appears that in production modes netlify uses a higher version by default, but in that first build it’ll fail without it.

After actually following the steps (it appears this is a personal flaw) the build ran through and I was live again!

Summary

  • Hugo was very easy to set up, I’m glad I went with it
  • GitHub pages in general seem to be quite nice, but they seemed to be very tightly coupled with Jekyll - the difference in support for the two models was significant
  • Netlify on the other hand was a very easy experience. I can’t comment on what it’s like if you’re using Jekyll though

All in all, the Netlify method is much closer to what I’m familiar with in deployment pipelines - I push a change to the defined branch. a hook picks up the change and deploys it. I’m in control of what I push, I can have work in progress strewn all over the place like any self-respecting organised developer…

Moving swiftly onwards, this feels much more normal and controlled than the deploy.sh method advised for GitHub Pages - having to make sure that anything I didn’t want to deploy was a draft or stashed/not currently in the workspace before I hit deploy was altogether too unsafe for me!

I’ll be sticking with Netlify. Now, it’s on to the next challenge: Actually writing some content!