Hugo, Gitlab Pages & Cloudflare

Some tips & gotchas I collected while migrating from Jekyll to Hugo + Gitlab Pages + Cloudflare:

  • Gitlab Pages doesn’t allow users to remove the default gitlab.io URL even if you’ve added your custom domains. Make sure you have a canonical reference in every page.
  • hugo server --baseURL http://192.168.1.2 --bind 192.168.1.2 if you want to make your local testing available on local wifi network.
  • It’s a good practice to end baseURL in your config.toml with a trailing slash.
  • When setting up Cloudflare, Gitlab docs talk about pointing www to your gitlab.io url as a CNAME. I personally prefer pointing it to my main domain, and setting up a 301 in Page Rules.
  • Speaking about Cloudflare, HTML files are not automatically cached. Again, this has to be specifically defined in Page Rules.
  • Use trailing slashes in all your internal links so Cloudflare knows it’s a directory. www.example.com/blog will trigger a 302 to www.example.com/blog/ and an origin pull, causing a long TTFB everytime! I’ve taken it for granted with many years of URL rewrites when running my own server. A List Apart has a good article talking about it.
  • For quite a while I was wondering why my favicons never got cached. I’m assuming adding type="image/x-icon" will fix this.
  • Adding a hash to CSS files is a pretty bad idea for a static website. Maybe it works well for SPAs if you need to do cache-busting.
  • It got really tiring to keep typing the whole string, and it gets worse when your IP changes:
# use an alias in your .zshrc file
alias hs='hugo serve --baseURL http://${ipconfig getifaddr en0}:1313 --bind ${ipconfig getifaddr en0}'

# or if you get a substitution error
alias hs='hugo serve --baseURL http://$(eval ipconfig getifaddr en0):1313 --bind $(eval ipconfig getifaddr en0)'

# put it in a function so you can get it anytime in the terminal
get_ip() {
  eval ipconfig getifaddr en0
}