Before creating your templates, it’s important to know how Hugo looks for files within your project’s directory structure.
Hugo uses a prioritized list called the lookup order as it traverses your layouts folder in your Hugo project looking for the appropriate template to render your content.
The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn’t present or specified, Hugo will look for template C…and so on until it reaches the _default/ directory for your project or theme. In many ways, the lookup order is similar to the programming concept of a switch statement without fallthrough.
The power of the lookup order is that it enables you to craft specific layouts and keep your templating DRY.
The respective lookup order for each of Hugo’s templates has been defined throughout the Hugo docs:
The lookup order is best illustrated through examples. The following shows you the process Hugo uses for finding the appropriate template to render your single page templates, but the concept holds true for all templates in Hugo.
The project is using the theme mytheme (specified in the project’s configuration).
The layouts and content directories for the project are as follows:
Notice the term UNSPECIFIED rather than UNDEFINED. If you don’t tell Hugo the specific type and layout, it makes assumptions based on sane defaults. my-first-post.md does not specify a content type in its front matter. Therefore, Hugo assumes the content type and section (i.e. posts, which is defined by file location) are one in the same. (Read more on sections.)
my-first-post.md also does not specify a layout in its front matter. Therefore, Hugo assumes that my-first-post.md, which is of type page and a single piece of content, should default to the next occurrence of a single.html template in the lookup (#4).
title: My Second Post
description: This is my second post.
Here is the way Hugo traverses the single-page lookup order for my-second-post.md:
The front matter in my-second-post.md specifies the content type (i.e. review) as well as the layout (i.e. reviewarticle). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
title: My First
description: This is an upcoming event..
Here is the way Hugo traverses the single-page lookup order for my-first-event.md: