Forcing your Hugo builds to crash, and why you probably should.

blog image

Hugo is a great static site generator. It’s fast, easy to use, and built on Golang. However, one thing about Hugo that I see a lot of people not talking about, is how you can force your build to crash, based on logic that is specific to your business/website.

You must be thinking, ‘Why would I even want to force my website build to crash?'

The answer is simple, to ensure there are no surprises during build time 👀

For example:

  • You have an “Events” post type, and you want to ensure that the end date is greater than the start date set by the editor. Or you might even want the end time to be at least 1 second more than the start time. Oops!
  • You have a “Blogs” post type, and you want to ensure that every blog going out has an author selected. Ooops!
  • You have a “Contact” page for lead generation, and you want to ensure the email key is compulsorily set. Oooops!
  • You want to ensure an image location set in the front matter, points to a file in your static directory, and not an invalid file. Ooooops!

If you’re like me, you have contingencies (if/else conditions) in place for every edge case to give default values if a someone forgot to fill up a crucial key/value pairs. Yet, sometimes the business logic may not allow you to do this. (Like, HOW do you set a contingency for a user not setting the right event end date?)

Introducing errorf and warnf:

errorf or warnf are functions that log a string into your console. While errorf would force the build to fail (the hugo command will exit -1), the warnf function would simply just print out the warning in your log, without crashing the build. You can feel free to ignore this post entirely, and read up on this directly in Hugo’s Documentation here: errorf/

As these are just print/logging functions, so they need to be wrapped around conditional statements that let Hugo know when they should be executed.

Being logger functions executed within your template, they have access to any .Section variable you have defined.

Using errorf:

The following snippet checks if your front matter contains a start date.

{{with .Params.start_date}}
	<!-- It's a good day! Your params are set. -->
	{{ errorf "Build Failed. start_date is not defined: %q" .Path }}

Depending on your CI/CD pipeline of choice, you could then shoot these error logs to a Slack channel and be rest assured that the world won’t end (yet).

Using warnf:

Using warnf is the exact same as using errorf. Using the same example as above, here is how that would look.

{{with .Params.start_date}}
	<!-- It's a good day! Your params are set. -->
    {{ warnf "Build May Succeed. But your start_date isn't defined %q" .Path }}


Both functions support all formatting verbs of the package, and in both cases (with the snippet shared above), the log would also contain the exact file path to where the error occurred, which becomes easier to decode and figure out.

The Hugo docs also mention an erroridf function to supress and log errors and make builds succeed. I haven’t found the use to use it yet (considering I’d mostly use warnf in this case), you can still read up more about it on the Hugo Docs!

Liked this story? Share it with someone who needs to see it 👇