Hugo uses the rules below to select a template for a given page, starting from the most specific.
Lookup rules Hugo takes the parameters listed below into consideration when choosing a template for a given page. The templates are ordered by specificity. 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). Layout Can be set in front matter. Output Format See
Custom 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. Note that if the output format’s Media Type has more than one suffix defined, only the first is considered.
Language We will consider a language tag in the template name. If the site language is fr
, index.fr.amp.html
will win over index.amp.html
, but index.amp.html
will be chosen before index.fr.html
. 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 term
types.
Templates can live in either the project’s or the themes’ layout
directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
Target a template You cannot change the lookup order to target a content page, but you can change a content page to target a template. Specify type
, layout
, or both in front matter.
Consider this content structure:
content/
├── about.md
└── contact.md
Files in the root of the content
directory have a
content type of page
. To render these pages with a unique template, create a matching subdirectory:
layouts/
└── page/
└── single.html
But the contact page probably has a form and requires a different template. In the front matter specify layout
:
content/contact.md.
yaml
toml
json layout : contact
title : Contact
layout = 'contact'
title = 'Contact'
{
"layout" : "contact" ,
"title" : "Contact"
}
Then create the template for the contact page:
layouts/
└── page/
└── contact.html <-- renders contact.md
└── single.html <-- renders about.md
As a content type, the word page
is vague. Perhaps miscellaneous
would be better. Add type
to the front matter of each page:
content/about.md.
yaml
toml
json title : About
type : miscellaneous
title = 'About'
type = 'miscellaneous'
{
"title" : "About" ,
"type" : "miscellaneous"
}
content/contact.md.
yaml
toml
json layout : contact
title : Contact
type : miscellaneous
layout = 'contact'
title = 'Contact'
type = 'miscellaneous'
{
"layout" : "contact" ,
"title" : "Contact" ,
"type" : "miscellaneous"
}
Now place the layouts in the corresponding directory:
layouts/
└── miscellaneous/
└── contact.html <-- renders contact.md
└── single.html <-- renders about.md
Home templates These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
Single templates These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
Example OutputFormat Suffix Template Lookup Order Single page in "posts" section html html layouts/posts/single.html.html layouts/posts/single.html layouts/_default/single.html.html layouts/_default/single.html Base template for single page in "posts" section html html layouts/posts/single-baseof.html.html layouts/posts/baseof.html.html layouts/posts/single-baseof.html layouts/posts/baseof.html layouts/_default/single-baseof.html.html layouts/_default/baseof.html.html layouts/_default/single-baseof.html layouts/_default/baseof.html Single page in "posts" section with layout set to "demolayout" html html layouts/posts/demolayout.html.html layouts/posts/single.html.html layouts/posts/demolayout.html layouts/posts/single.html layouts/_default/demolayout.html.html layouts/_default/single.html.html layouts/_default/demolayout.html layouts/_default/single.html Base template for single page in "posts" section with layout set to "demolayout" html html layouts/posts/demolayout-baseof.html.html layouts/posts/single-baseof.html.html layouts/posts/baseof.html.html layouts/posts/demolayout-baseof.html layouts/posts/single-baseof.html layouts/posts/baseof.html layouts/_default/demolayout-baseof.html.html layouts/_default/single-baseof.html.html layouts/_default/baseof.html.html layouts/_default/demolayout-baseof.html layouts/_default/single-baseof.html layouts/_default/baseof.html AMP single page in "posts" section amp html layouts/posts/single.amp.html layouts/posts/single.html layouts/_default/single.amp.html layouts/_default/single.html AMP single page in "posts" section, French language amp html layouts/posts/single.fr.amp.html layouts/posts/single.amp.html layouts/posts/single.fr.html layouts/posts/single.html layouts/_default/single.fr.amp.html layouts/_default/single.amp.html layouts/_default/single.fr.html layouts/_default/single.html
Section templates These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
Example OutputFormat Suffix Template Lookup Order Section list for "posts" html html layouts/posts/posts.html.html layouts/posts/section.html.html layouts/posts/list.html.html layouts/posts/posts.html layouts/posts/section.html layouts/posts/list.html layouts/section/posts.html.html layouts/section/section.html.html layouts/section/list.html.html layouts/section/posts.html layouts/section/section.html layouts/section/list.html layouts/_default/posts.html.html layouts/_default/section.html.html layouts/_default/list.html.html layouts/_default/posts.html layouts/_default/section.html layouts/_default/list.html Section list for "posts" with type set to "blog" html html layouts/blog/posts.html.html layouts/blog/section.html.html layouts/blog/list.html.html layouts/blog/posts.html layouts/blog/section.html layouts/blog/list.html layouts/posts/posts.html.html layouts/posts/section.html.html layouts/posts/list.html.html layouts/posts/posts.html layouts/posts/section.html layouts/posts/list.html layouts/section/posts.html.html layouts/section/section.html.html layouts/section/list.html.html layouts/section/posts.html layouts/section/section.html layouts/section/list.html layouts/_default/posts.html.html layouts/_default/section.html.html layouts/_default/list.html.html layouts/_default/posts.html layouts/_default/section.html layouts/_default/list.html Section list for "posts" with layout set to "demolayout" html html layouts/posts/demolayout.html.html layouts/posts/posts.html.html layouts/posts/section.html.html layouts/posts/list.html.html layouts/posts/demolayout.html layouts/posts/posts.html layouts/posts/section.html layouts/posts/list.html layouts/section/demolayout.html.html layouts/section/posts.html.html layouts/section/section.html.html layouts/section/list.html.html layouts/section/demolayout.html layouts/section/posts.html layouts/section/section.html layouts/section/list.html layouts/_default/demolayout.html.html layouts/_default/posts.html.html layouts/_default/section.html.html layouts/_default/list.html.html layouts/_default/demolayout.html layouts/_default/posts.html layouts/_default/section.html layouts/_default/list.html Section list for "posts" rss xml layouts/posts/section.rss.xml layouts/posts/rss.xml layouts/posts/list.rss.xml layouts/posts/section.xml layouts/posts/list.xml layouts/section/section.rss.xml layouts/section/rss.xml layouts/section/list.rss.xml layouts/section/section.xml layouts/section/list.xml layouts/_default/section.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/section.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml
Taxonomy templates These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
hugo.
yaml
toml
json taxonomies :
category : categories
[ taxonomies ]
category = 'categories'
{
"taxonomies" : {
"category" : "categories"
}
}
Example OutputFormat Suffix Template Lookup Order Taxonomy list for "categories" html html layouts/categories/category.terms.html.html layouts/categories/terms.html.html layouts/categories/taxonomy.html.html layouts/categories/list.html.html layouts/categories/category.terms.html layouts/categories/terms.html layouts/categories/taxonomy.html layouts/categories/list.html layouts/category/category.terms.html.html layouts/category/terms.html.html layouts/category/taxonomy.html.html layouts/category/list.html.html layouts/category/category.terms.html layouts/category/terms.html layouts/category/taxonomy.html layouts/category/list.html layouts/taxonomy/category.terms.html.html layouts/taxonomy/terms.html.html layouts/taxonomy/taxonomy.html.html layouts/taxonomy/list.html.html layouts/taxonomy/category.terms.html layouts/taxonomy/terms.html layouts/taxonomy/taxonomy.html layouts/taxonomy/list.html layouts/_default/category.terms.html.html layouts/_default/terms.html.html layouts/_default/taxonomy.html.html layouts/_default/list.html.html layouts/_default/category.terms.html layouts/_default/terms.html layouts/_default/taxonomy.html layouts/_default/list.html Taxonomy list for "categories" rss xml layouts/categories/category.terms.rss.xml layouts/categories/terms.rss.xml layouts/categories/taxonomy.rss.xml layouts/categories/rss.xml layouts/categories/list.rss.xml layouts/categories/category.terms.xml layouts/categories/terms.xml layouts/categories/taxonomy.xml layouts/categories/list.xml layouts/category/category.terms.rss.xml layouts/category/terms.rss.xml layouts/category/taxonomy.rss.xml layouts/category/rss.xml layouts/category/list.rss.xml layouts/category/category.terms.xml layouts/category/terms.xml layouts/category/taxonomy.xml layouts/category/list.xml layouts/taxonomy/category.terms.rss.xml layouts/taxonomy/terms.rss.xml layouts/taxonomy/taxonomy.rss.xml layouts/taxonomy/rss.xml layouts/taxonomy/list.rss.xml layouts/taxonomy/category.terms.xml layouts/taxonomy/terms.xml layouts/taxonomy/taxonomy.xml layouts/taxonomy/list.xml layouts/_default/category.terms.rss.xml layouts/_default/terms.rss.xml layouts/_default/taxonomy.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/category.terms.xml layouts/_default/terms.xml layouts/_default/taxonomy.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml
Term templates These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
hugo.
yaml
toml
json taxonomies :
category : categories
[ taxonomies ]
category = 'categories'
{
"taxonomies" : {
"category" : "categories"
}
}
Example OutputFormat Suffix Template Lookup Order Term list for "categories" html html layouts/categories/term.html.html layouts/categories/category.html.html layouts/categories/taxonomy.html.html layouts/categories/list.html.html layouts/categories/term.html layouts/categories/category.html layouts/categories/taxonomy.html layouts/categories/list.html layouts/term/term.html.html layouts/term/category.html.html layouts/term/taxonomy.html.html layouts/term/list.html.html layouts/term/term.html layouts/term/category.html layouts/term/taxonomy.html layouts/term/list.html layouts/taxonomy/term.html.html layouts/taxonomy/category.html.html layouts/taxonomy/taxonomy.html.html layouts/taxonomy/list.html.html layouts/taxonomy/term.html layouts/taxonomy/category.html layouts/taxonomy/taxonomy.html layouts/taxonomy/list.html layouts/category/term.html.html layouts/category/category.html.html layouts/category/taxonomy.html.html layouts/category/list.html.html layouts/category/term.html layouts/category/category.html layouts/category/taxonomy.html layouts/category/list.html layouts/_default/term.html.html layouts/_default/category.html.html layouts/_default/taxonomy.html.html layouts/_default/list.html.html layouts/_default/term.html layouts/_default/category.html layouts/_default/taxonomy.html layouts/_default/list.html Term list for "categories" rss xml layouts/categories/term.rss.xml layouts/categories/category.rss.xml layouts/categories/taxonomy.rss.xml layouts/categories/rss.xml layouts/categories/list.rss.xml layouts/categories/term.xml layouts/categories/category.xml layouts/categories/taxonomy.xml layouts/categories/list.xml layouts/term/term.rss.xml layouts/term/category.rss.xml layouts/term/taxonomy.rss.xml layouts/term/rss.xml layouts/term/list.rss.xml layouts/term/term.xml layouts/term/category.xml layouts/term/taxonomy.xml layouts/term/list.xml layouts/taxonomy/term.rss.xml layouts/taxonomy/category.rss.xml layouts/taxonomy/taxonomy.rss.xml layouts/taxonomy/rss.xml layouts/taxonomy/list.rss.xml layouts/taxonomy/term.xml layouts/taxonomy/category.xml layouts/taxonomy/taxonomy.xml layouts/taxonomy/list.xml layouts/category/term.rss.xml layouts/category/category.rss.xml layouts/category/taxonomy.rss.xml layouts/category/rss.xml layouts/category/list.rss.xml layouts/category/term.xml layouts/category/category.xml layouts/category/taxonomy.xml layouts/category/list.xml layouts/_default/term.rss.xml layouts/_default/category.rss.xml layouts/_default/taxonomy.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/term.xml layouts/_default/category.xml layouts/_default/taxonomy.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml
These template paths are sorted by specificity in descending order. The least specific path is at the bottom of each list.
The examples below assume the following site configuration:
hugo.
yaml
toml
json taxonomies :
category : categories
[ taxonomies ]
category = 'categories'
{
"taxonomies" : {
"category" : "categories"
}
}