Julien Maury


The power of Hugo's lookup

The power of Hugo's lookup

Julien Maury's photo
Julien Maury
ยทNov 1, 2021ยท

3 min read

Subscribe to my newsletter and never miss my upcoming articles

Hugo is such a great framework with a minimalist approach and powerful features such as the template's lookup.

Hugo separates content written in markdown, from layouts, written in HTML and Golang. Markdown is a universal language for content working as a syntactic sugar for HTML.

Getting started ๐Ÿš€

Hugo provides an intuitive way to organize templates. It searches in a specific order, so you don't have to struggle to find the right one, and the naming convention is quite clever compared to many CMS and frameworks.

To get started, you only need a few files in a _default/ folder within the layouts/ directory:

  โ”œโ”€โ”€ _default
  โ”‚   โ”œโ”€โ”€ baseof.html
  โ”‚   โ”œโ”€โ”€ list.html
  โ”‚   โ””โ”€โ”€ single.html
  โ””โ”€โ”€ index.html

This way, you can create the _default/baseof.html file containing your website's HTML skeleton, and other files only have to override blocks of HTML contents.

The single.html file handles the appearance of regular pages, and the list.html is the default template for list views. The index.html manages the front page. All templates inherit from baseof.html.

This inheritance allows for dynamic templating and prevents unnecessary repetitions.

Posts vs. pages ๐Ÿ™Œ

The idea is to only tweak the necessary elements, so if most views have the same appearance, it's no use multiplying templates.

However, you can customize the template for each content type by adding a dedicated folder in the layouts/ directory.

Let's say you have a blog section on your website, and all markdown posts are in the content/posts/ folder. You can create the layouts/posts/ directory and put a singe.html file inside. It will also inherit from _default/baseof.html, but you will be able to fully customize the template.

As the _default/single.html is the default template for regular pages, you probably do not want to display the date, tags, categories, or estimated reading time features everywhere.

If you need another HTML skeleton for single views, you can use layouts/posts/single-baseof.html.

You can get more ๐Ÿค“

If we go a bit deeper, Hugo lets you define intermediary templates for each content type. Most of the time, you won't need that granularity, but it can be helpful for websites with lots of content and many different layouts.

Indeed, it's sometimes more clever to start from a new starter template than trying to make everything inherit from the same generic base at all costs.

Hugo looks for the following files in this specific order to get the base template of your blog posts:


Note that you can create a layouts/posts/baseof.html file instead of the default one (layouts/_default/baseof.html).

Source: Hugo doc - lookup

What the heck is "*.html.html"? ๐Ÿค”

You may have noticed that Hugo looks for files with weird extensions such as .html.html. Why is that so?

Hugo's lookup considers multiple output formats such as AMP (e.g., layouts/_default/single.amp.html), hence the need for .html.html vs. .amp.html.

/themes/ vs. /layouts/ ๐ŸŽจ

Instead of creating files in the /layouts/ folder, you can use open-source and commercial themes in the /themes/ folder.

The same lookup applies. The theme will typically have a /layouts/ subfolder that follows the same logic as the generic one.

There are tones of starters and ready-to-use templates on the official themes platform.

Conclusion ๐Ÿ’ซ

Every framework has its particularities, and the learning phase can be relatively challenging, but I find Hugo's logic pretty smart and intuitive. As Hugo is written in Go, and Go is inspired by C, you might be afraid, especially if you are a front-end developer.

However, Hugo is just an excellent executable file that uses libraries such as html/template and text/template to provide a convenient templating syntax, easy to use and quite flexible.

Hugo is not the only option for static websites, but it's a great choice. If you don't need a database and want to keep content and layouts organized, go for Hugo ^^.

Share this