mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
---
|
|
title: Hugo's Lookup Order
|
|
linktitle: Template Lookup Order
|
|
description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
|
|
godocref:
|
|
date: 2017-02-01
|
|
publishdate: 2017-02-01
|
|
lastmod: 2017-05-25
|
|
categories: [templates,fundamentals]
|
|
keywords: [templates]
|
|
menu:
|
|
docs:
|
|
parent: "templates"
|
|
weight: 15
|
|
quicklinks:
|
|
weight: 15
|
|
sections_weight: 15
|
|
draft: false
|
|
aliases: [/templates/lookup/]
|
|
toc: true
|
|
---
|
|
|
|
## Hugo Layouts Lookup Rules
|
|
|
|
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.
|
|
|
|
|
|
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"). It will always have a value, so if not set, the value is "page".
|
|
|
|
Section
|
|
: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types.
|
|
|
|
{{% note %}}
|
|
**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
|
|
```
|
|
{{% /note %}}
|
|
|
|
|
|
## Hugo Layouts Lookup Rules With Theme
|
|
|
|
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.
|
|
|
|
## Examples: Layout Lookup for Regular Pages
|
|
|
|
{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
|
|
|
## Examples: Layout Lookup for Home Page
|
|
|
|
{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
|
|
|
## Examples: Layout Lookup for Section Pages
|
|
|
|
{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
|
|
|
## Examples: Layout Lookup for Taxonomy List Pages
|
|
|
|
{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
|
|
|
## Examples: Layout Lookup for Taxonomy Terms Pages
|
|
|
|
{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
|
|
|
|
|
|
|
|
|