description: 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.
description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
## Hugo Layouts Lookup Rules
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.
Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
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][switch].
The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][].
Kind
: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML).
Output Format
: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. 'rss', 'amp', 'html') and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates.
Language
: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but we will `index.amp.html` will be chosen before `index.fr.html`.
Layout
: Can be set in page front matter.
Type
: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). If will always have a value, so if not set, the value is "page".
Section
: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types.
{{% 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][home]
* [Base Templates][base]
* [Section Page Templates][sectionlookup]
* [Taxonomy List Templates][taxonomylookup]
* [Taxonomy Terms Templates][termslookup]
* [Single Page Templates][singlelookup]
* [RSS Templates][rsslookup]
* [Shortcode Templates][sclookup]
## 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][config]).
2. The layouts and content directories for the project are as follows:
**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates:
```bash
├── _default
│ ├── baseof.html
│ ├── list.html
│ └── single.html
└── index.html
```
.
├── 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](/templates/lists/). In this example, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
In Hugo, layouts can live in either the project's or theme's layout folder, and the most specific layout will be chosen. Hugo will interleave the lookups:
1. layouts/page/index.html
2. demoTheme/layouts/page/index.html
3. layouts/...
This way it is possible to override specific templates from the theme.
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][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).
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*.
`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](/themes/customizing/) 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.
You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]).
Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.
{{ $list := where $list $filter1 $filter2 $filter3 }}
<tableclass="table table-bordered">
<tr>
{{ range $fields }}
<th>{{ . }}</th>
{{ end }}
</tr>
{{ range $list }}
<tr>
{{ range $k, $v := . }}
{{ $.Scratch.Set $k $v }}
{{ end }}
{{ range $fields }}
<td>{{ $.Scratch.Get . }}</td>
{{ end }}
</tr>
{{ end }}
</table>
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Bjørn Erik Pedersen