TEMPLATES FUNDAMENTALS

Hugo's Lookup Order

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.

Lookup Orders

The respective lookup order for each of Hugo’s templates has been defined throughout the Hugo docs:

Template Lookup Examples

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.

  1. The project is using the theme mytheme (specified in the project’s configuration).
  2. The layouts and content directories for the project are as follows:
.
├── content
│   ├── events
│   │   ├── _index.md
│   │   └── my-first-event.md
│   └── posts
│       ├── my-first-post.md
│       └── my-second-post.md
├── layouts
│   ├── _default
│   │   └── single.html
│   ├── posts
│   │   └── single.html
│   └── reviews
│       └── reviewarticle.html
└── themes
    └── mytheme
        └── layouts
            ├── _default
            │   ├── list.html
            │   └── single.html
            └── posts
                ├── list.html
                └── single.html

Now we can look at the front matter for the three content (i.e..md) files.

Example: my-first-post.md

content/posts/my-first-post.md

---
title: My First Post
date: 2017-02-19
description: This is my first post.
---

When building your site, Hugo will go through the lookup order until it finds what it needs for my-first-post.md:

  1. /layouts/UNSPECIFIED/UNSPECIFIED.html
  2. /layouts/posts/UNSPECIFIED.html
  3. /layouts/UNSPECIFIED/single.html
  4. /layouts/posts/single.html
    BREAK
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html
  7. /themes/<THEME>/layouts/posts/UNSPECIFIED.html
  8. /themes/<THEME>/layouts/UNSPECIFIED/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

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).

Example: my-second-post.md

content/posts/my-second-post.md

---
title: My Second Post
date: 2017-02-21
description: This is my second post.
type: review
layout: reviewarticle
---

Here is the way Hugo traverses the single-page lookup order for my-second-post.md:

  1. /layouts/review/reviewarticle.html
    BREAK
  2. /layouts/posts/reviewarticle.html
  3. /layouts/review/single.html
  4. /layouts/posts/single.html
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/review/reviewarticle.html
  7. /themes/<THEME>/layouts/posts/reviewarticle.html
  8. /themes/<THEME>/layouts/review/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

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.

Example: my-first-event.md

content/events/my-first-event.md

---
title: My First
date: 2017-02-21
description: This is an upcoming event..
---

Here is the way Hugo traverses the single-page lookup order for my-first-event.md:

  1. /layouts/UNSPECIFIED/UNSPECIFIED.html
  2. /layouts/events/UNSPECIFIED.html
  3. /layouts/UNSPECIFIED/single.html
  4. /layouts/events/single.html
  5. /layouts/_default/single.html
    BREAK
  6. /themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html
  7. /themes/<THEME>/layouts/events/UNSPECIFIED.html
  8. /themes/<THEME>/layouts/UNSPECIFIED/single.html
  9. /themes/<THEME>/layouts/events/single.html
  10. /themes/<THEME>/layouts/_default/single.html
“Hugo's Lookup Order” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page