Working with Hugo Templates

Hugo uses templates to generate HTML pages. This lets you control your generated HTML content with the help of simple logic. For example, logic such as ranging over all blog posts so that you can print them one at a time onto the page. Hugo uses the Go html/template library.

A template can describe an entire page, or just a small portion of a page (for example, just the copyright notice, the header, the footer, etc.). When this happens it is called a partial template, and that template can be reused just about anywhere else in your website. Partials are especially useful in Hugo themes, as it gives you the option to override just a small part of the layout to suit your needs. As mentioned in my previous post, overriding any file in a theme is as simple as dropping in your own version of the file with the same name. Thus templates can be overriden the same way.

Modifying the Hyde-X theme

The Hyde-X theme by default provides nice looking links at the top of each post, based on the post’s meta content (such as the links marked “hugo” and “blog” which you can see at the top of this post). However, Hyde-X only supports those links for categories, and I wanted links for tags, which are two different meta data taxonomies.

This brought me to my first encounter with Hugo templating.

To solve this, first I extracted the links section into its own partial template, where it could be customized independently from the rest of the theme. Then I made a configuration item to control which taxonomies to create links for.

Here are some of the quirks I encountered along the way:

Contributing back

Instead of overriding the theme just on my own personal website, I thought this feature could be generally useful to others who are using the theme. So I made a pull request to contribute this back to the community.