So recently I built a simple portfolio website with Hugo. (Hugo content repo.)

It was a pretty fun experience and I found Hugo is indeed blazing fast. On top of that, I think it has some sensible defaults out of the box, even though it’s not documented very well.

While I am learning Hugo I found the templating part a bit hard to figure out, so I decided to write a summary of it.

First, template lookup is just simple cascading, babe. Meaning for every single content it will look up its template in a hierarchy order and pick the first one to render. If the content couldn’t find any template you will get a 404 error when visiting the intended URL.

Second, the master template (the bread) should be put at layout/_default/baseof.html with main block to park the beef later. (It’s just normal Golang HTML/template stuff)

{{ block "main" . }} {{ end }}

In all other templates, you could use this master template by using

{{ define "main" }}

your beef

{{ end }}

Third, there are two major templates, namely list and single. list is like the index page, and maps to path /; single is the like the detail page, and maps to /:some-content-based-URL.

For example, in the example site I built, there is a UI section in the nav bar, which maps to /uis/ path. Under Hugo’s default configurations, the folder named uis under content folder will be used. And upon visiting /uis/ path, Hugo will look up the template in the order talked about in this documentation page.

There is a catch here is that under version v0.30.2, if you have an empty folder, the list template will not be rendered automatically. You must put a file under the folder, even the content of file could be empty.

The catch is useful when adding static pages. Eg, when adding About, FAQ, or Privacy pages.

To add such a page, first create a folder with the desired name, for example, about, then creating an empty file under the folder. After that just dump whatever static HTML into the list.html template.

In the about case, dump the content to layout/about/list.html.

That’s all about the templating, Happy generating. :)