Get to grips with Hugo templates

The Hugo static website generator is an incredibly flexible site builder, but this very flexibility means that the way it matches page templates to page content can seem unclear. I’ve been using Hugo for some time now and I only ‘got it’ just recently. What follows is essentially a summary for my future reference, but hopefully it’ll help other Hugo users too.

Built with Hugo’s template scheme

Within a site project folder, Hugo adds two key folders: content and layouts. There are others, but these two provide the core functionality. Let’s look at contents first.

Any folder within contents is a Hugo ‘section’: a branch in tree of pages you are setting up. Typically a section will have a section index page and a number of subsidiary pages. Each of these pages’ contents are placed in a markdown file. Say you have a section called bibliography that contains a file mycenae.md. This page will be rendered as /bibliography/mycenae/index.html.

The folder also contains two further files: crete.md and anatolia.md, respectively rendered as /bibliography/crete/index.html and /bibliography/anatolia/index.html.

We also need a page — to be rendered as /bibliography/index.html — from which the reader can select any of these three bibliographies. Its content is placed in either _index.md or index.md. Which of these you choose depends on how you want the page rendered, which brings us to the layouts folder.

This folder is where your HTML page templates reside. It can contain folders for each of your sections; if so, Hugo will look in them for the relevant templates. Any it can’t find what it’s looking for there, it will look in the special _defaults folder. In fact, for simple sites, _defaults is generally all you need.

I’ll cover the assembly of templates shortly; for now it’s enough to know that you need two templates, section.html and single.html, and possibly a third, list.html. This brings us back to content:

  • _index.md pages will be rendered using either section.html or list.html; section.html takes precedence if they are both present.
  • index.md pages are rendered using single.html — this is usually what you’ll use if a section contains no pages other than the index.
  • Other .md pages are rendered using single.html. Recall mycenae.md, above? That is rendered using single.html.

These are simply the fall-back templates; you may choose to have section-specific version of each of these in section folders under layouts.

You can override the template selection in a content file’s front matter. For example, you may want a one section page to use its own template: just add the layout key to its _index.md or index.md file’s front matter and reference the name of the alternative template. A case in point: thanks to Hugo’s rules of template precedence, most of my section pages use section.html, but one of them has layout: list in its front matter to force it to use list.html instead.

I’ve talked about section indexes — what about the main index page, the home page? Well, it’s just another _index.md file, this time placed in the contents folder alongside however many section folders you have:

project/contents/_index.md
project/contents/bibliographies/_index.md
project/contents/bibliographies/crete.md
project/contents/bibliographies/mycenae.md
project/contents/locations/_index.md
project/contents/locations/crete.md
project/contents/locations/greece.md

The equivalent template is the unique index.html, placed in /layouts or /layouts/_defaults.

Note that the contents folder should have only one .md file, _index.md or index.md.

Let’s have a quick look at template assembly. Hugo uses a file called baseof.html as the foundation template. Here you can add HTML that’s common to all pages within a section, or by default (ie. it’s placed in _defaults rather than a layouts section folder) across the site. Within baseof.html you can specify template units using the block command:

{{ block "<BLOCK_NAME>" . }}{{ end }}

You then define blocks called for each of your template types. For example, one section.html contains simply:

{{ define "header" }}
    {{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
    {{ .Params.headline }}
    {{ .Content }}
{{ end }}

Blocks are declared with the define command. When Hugo needs a section template, it constructs one from section.html and baseof.html: the blocks defined in the former file are inserted into the placeholders in the latter file. Hugo then injects the content from the content file.

When combined with the partial command, which pulls in sub-templates from the partials folder within layouts, the define and block commands give you a powerful way of breaking HTML templates down into small, re-usable and manageable chunks. It’s much easier to edit a 5-10 line chunk of code safe in the knowledge that the update will appear everywhere it needs to than to edit the same code in a set of 200-line templates.

And by naming and preparing the templates correctly, you can be sure Hugo will pull in the correct one for each of your content files.

Tap Homebrew to easily install and upgrade your own apps

The package manager I use on macOS is Homebrew, Brew for short. This is a great open source tool for installing command-line apps and utilities, and keeping them up to date. It’s essentially the Mac version of the Raspberry Pi’s apt. So much of the software I use on a regular basis — the nano text editor, Node.js, Python 3, the shellcheck shell script linter, the hugo website builder, the sass CSS wrangler and a whole load more — were added and are maintained using Brew.

Provide your own apps through Homebrew
Continue reading

PreviewMarkdown 1.1.0 released, ready for Big Sur

Another day, another update. This time it’s PreviewMarkdown, my macOS utility for providing QuickLook file previews and icon thumbnails in Finder. It runs under Catalina and above, and this version makes some adjustments to support Big Sur.

Pop up a Markdown file preview

You can read more about using PreviewMarkdown — just run it once to register its app extensions, and that’s it — it the product page here. You can download PreviewMarkdown from the Mac App Store.

MNU 1.4.0 released — and it’s ready for Big Sur, Apple Silicon

The latest version of MNU, 1.4.0, can be downloaded from my software site. The focus of this update is to support the changes brought in by Big Sur’s updated, iOS-esque UI: in this case, no more roll-down sheets, and iOS-style dialogs and square icons.

MNU under Big Sur
Big Sur: more space, Sur-ely?
Continue reading