Validating themes: how to avoid tripping over changes in Hugo

I’m just getting started with Hugo, but I’ve been using it long enough to see the breakneck pace at which Hugo is developing. I spent some time trying to get a promising theme working, where it said on the tin “Requires Hugo 0.15 or later”. Fine, I’ve got 0.17. One minor detail: the home page rendered nearly blank, the partial bracketed with “with .Site.Params.Header” was not rendered. To make a long story short: the theme referred to variables in config.toml using CamelCase, and somewhere between 0.15 and 0.17 it became mandatory to refer to them in lowercase. The theme author obviously hadn’t upgraded yet and was surprised that his theme had broken. As a theme user, it was not obvious that the Hugo upgrade had caused this.

Once I figured it out, it was an easy fix, but it triggered me to think: if I start depending on Hugo for my web site, I’d like to be able to upgrade with confidence, and not have rendering issues go undetected.

I started looking if I could find a way to have Hugo warn about undefined references. Obviously, just adding a flag to Hugo to warn about undefined references won’t fly, because the “with” clause specifically tests for whether or not the object is defined and thus should suppress the warning.

So, what can one do to prevent this? Any best practices for testing themes? I come from a world where rspec rules suppreme (and I’m new to the Go ecosystem, but I’m willing to learn anything that is likely to be accepted by the theme author). Just a simple smoketest like “The home page should include a div#banner”, “div#banner should include an img href=/img/banner.jpg” would have prevented this, and (when done in a way that exercises all the moving parts of a theme) would give me the confidence to go ahead with Hugo. I’m not afraid of fixing stuff after an upgrade, I’m afraid of not knowing it broke in the first place!

Apologies if I’m asking the obvious, but my limited GoogleFu didn’t turn up much!

I have no good answer for you.

  • We try the very best to avoid breaking stuff, and if we do we try to update the themes (I made 100 pull request to rename RSSlink to RSSLink recently)
  • There are not many restrictions on “what a Hugo theme” is, so it is hard to make any good validator for it, but we should maybe try
  • We build a demo site for most of the themes at – we may expand that to report a little better about “what works”, right now we just don’t show the demo link if a theme fails.

1 Like

Well, that is a perfectly good answer as well! I’ll look into tools like Nightwatch ( to safeguard my site.

FWIW, I found the offending references in the theme I was using with this command:

grep -R '\.Site\.Params\.[A-Z]'

Not sure it would catch everything, but it allowed me to fix the demo for 0.17. Hmmm, looks like I’ll need to upgrade again :slight_smile:

On an added note: You will get a pretty good indication if you check the exit code after a Hugo build, ie. hugo && echo $?