hugo/docs/content/templates/lookup-order.md

title	linktitle	description	godocref	date	publishdate	lastmod	categories	menu	weight	sections_weight	draft	aliases	toc
Hugo's Lookup Order	Template Lookup Order	The lookup order is a prioritized list used by Hugo as it traverses your files looking for the appropriate corresponding file to render your content.		2017-02-01	2017-02-01	2017-05-25	templates fundamentals	docs quicklinks parent weight templates 15	15	15	false	/templates/lookup/	true

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.

{{% note %}} Most Hugo websites will only need the default template files at the end of the lookup order (i.e. _default/*.html). {{% /note %}}

Lookup Orders

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

• Homepage Template
• Base Templates
• Section Page Templates
• Taxonomy List Templates
• Taxonomy Terms Templates
• Single Page Templates
• RSS Templates
• Shortcode Templates

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.

{{% note %}} Only three of the four markdown files in the above project are subject to the single page lookup order. _index.md is a specific kind in Hugo. Whereas my-first-post.md, my-second-post.md, and my-first-event.md are all of kind page, all _index.md files in a Hugo project are used to add content and front matter to list pages. In this example, events/_index.md will render according to its section template and respective lookup order. {{% /note %}}

Example: my-first-post.md

{{< code file="content/posts/my-first-post.md" copy="false" >}}

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

{{< /code >}}

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

{{< code file="content/posts/my-second-post.md" copy="false" >}}

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

{{< /code >}}

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.

{{% note "Type and not Types" %}} Notice that the directory for the template for my-second-post.md is review and not reviews. This is because type is always singular when defined in front matter. {{% /note%}}

Example: my-first-event.md

{{< code file="content/events/my-first-event.md" copy="false" >}}

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

{{< /code >}}

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

{{% note %}} my-first-event.md is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory and the mytheme themes directory have a file at _default/single.html. Understanding this order allows you to customize Hugo themes by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream. {{% /note %}}