VoteIT

  • News
  • Documentation
  • Themes
  • Showcase
  • Community
  • GitHub
Star

What's on this Page

  • Hugo Layouts Lookup Rules
  • Hugo Layouts Lookup Rules With Theme
  • Examples: Layout Lookup for Regular Pages
  • Examples: Layout Lookup for Home Page
  • Examples: Layout Lookup for Section Pages
  • Examples: Layout Lookup for Taxonomy List Pages
  • Examples: Layout Lookup for Taxonomy Terms Pages
TEMPLATES FUNDAMENTALS

Hugo's Lookup Order

Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.

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

Tip: The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates:

├── _default
│   ├── baseof.html
│   ├── list.html
│   └── single.html
└── index.html

Hugo Layouts Lookup Rules With Theme

In Hugo, layouts can live in either the project's or the themes’ layout folders, and the most specific layout will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.

Examples: Layout Lookup for Regular Pages

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]
Single page in "posts" section with layout set 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]
AMP single page AMP html [layouts/posts/single.amp.html layouts/posts/single.html layouts/_default/single.amp.html layouts/_default/single.html]
AMP single page, 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]

Examples: Layout Lookup for Home Page

Example OutputFormat Suffix Template Lookup Order
Home page HTML html [layouts/index.html.html layouts/home.html.html layouts/list.html.html layouts/index.html layouts/home.html layouts/list.html layouts/_default/index.html.html layouts/_default/home.html.html layouts/_default/list.html.html layouts/_default/index.html layouts/_default/home.html layouts/_default/list.html]
Home page with type set HTML html [layouts/demotype/index.html.html layouts/demotype/home.html.html layouts/demotype/list.html.html layouts/demotype/index.html layouts/demotype/home.html layouts/demotype/list.html layouts/index.html.html layouts/home.html.html layouts/list.html.html layouts/index.html layouts/home.html layouts/list.html layouts/_default/index.html.html layouts/_default/home.html.html layouts/_default/list.html.html layouts/_default/index.html layouts/_default/home.html layouts/_default/list.html]
Home page with layout set HTML html [layouts/demolayout.html.html layouts/index.html.html layouts/home.html.html layouts/list.html.html layouts/demolayout.html layouts/index.html layouts/home.html layouts/list.html layouts/_default/demolayout.html.html layouts/_default/index.html.html layouts/_default/home.html.html layouts/_default/list.html.html layouts/_default/demolayout.html layouts/_default/index.html layouts/_default/home.html layouts/_default/list.html]
AMP home, French language" AMP html [layouts/index.fr.amp.html layouts/home.fr.amp.html layouts/list.fr.amp.html layouts/index.amp.html layouts/home.amp.html layouts/list.amp.html layouts/index.fr.html layouts/home.fr.html layouts/list.fr.html layouts/index.html layouts/home.html layouts/list.html layouts/_default/index.fr.amp.html layouts/_default/home.fr.amp.html layouts/_default/list.fr.amp.html layouts/_default/index.amp.html layouts/_default/home.amp.html layouts/_default/list.amp.html layouts/_default/index.fr.html layouts/_default/home.fr.html layouts/_default/list.fr.html layouts/_default/index.html layouts/_default/home.html layouts/_default/list.html]
JSON home JSON json [layouts/index.json.json layouts/home.json.json layouts/list.json.json layouts/index.json layouts/home.json layouts/list.json layouts/_default/index.json.json layouts/_default/home.json.json layouts/_default/list.json.json layouts/_default/index.json layouts/_default/home.json layouts/_default/list.json]
RSS home RSS xml [layouts/index.rss.xml layouts/home.rss.xml layouts/rss.xml layouts/list.rss.xml layouts/index.xml layouts/home.xml layouts/list.xml layouts/_default/index.rss.xml layouts/_default/home.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/index.xml layouts/_default/home.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml]

Examples: Layout Lookup for Section Pages

Example OutputFormat Suffix Template Lookup Order
RSS section 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]
Section list for "posts" section 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" section 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" section 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]

Examples: Layout Lookup for Taxonomy List Pages

Example OutputFormat Suffix Template Lookup Order
Taxonomy list in categories RSS xml [layouts/categories/category.rss.xml layouts/categories/taxonomy.rss.xml layouts/categories/rss.xml layouts/categories/list.rss.xml layouts/categories/category.xml layouts/categories/taxonomy.xml layouts/categories/list.xml layouts/taxonomy/category.rss.xml layouts/taxonomy/taxonomy.rss.xml layouts/taxonomy/rss.xml layouts/taxonomy/list.rss.xml layouts/taxonomy/category.xml layouts/taxonomy/taxonomy.xml layouts/taxonomy/list.xml layouts/category/category.rss.xml layouts/category/taxonomy.rss.xml layouts/category/rss.xml layouts/category/list.rss.xml layouts/category/category.xml layouts/category/taxonomy.xml layouts/category/list.xml layouts/_default/category.rss.xml layouts/_default/taxonomy.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/category.xml layouts/_default/taxonomy.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml]
Taxonomy list in categories HTML html [layouts/categories/category.html.html layouts/categories/taxonomy.html.html layouts/categories/list.html.html layouts/categories/category.html layouts/categories/taxonomy.html layouts/categories/list.html layouts/taxonomy/category.html.html layouts/taxonomy/taxonomy.html.html layouts/taxonomy/list.html.html layouts/taxonomy/category.html layouts/taxonomy/taxonomy.html layouts/taxonomy/list.html layouts/category/category.html.html layouts/category/taxonomy.html.html layouts/category/list.html.html layouts/category/category.html layouts/category/taxonomy.html layouts/category/list.html layouts/_default/category.html.html layouts/_default/taxonomy.html.html layouts/_default/list.html.html layouts/_default/category.html layouts/_default/taxonomy.html layouts/_default/list.html]

Examples: Layout Lookup for Taxonomy Terms Pages

Example OutputFormat Suffix Template Lookup Order
Taxonomy terms in categories RSS xml [layouts/categories/category.terms.rss.xml layouts/categories/terms.rss.xml layouts/categories/rss.xml layouts/categories/list.rss.xml layouts/categories/category.terms.xml layouts/categories/terms.xml layouts/categories/list.xml layouts/taxonomy/category.terms.rss.xml layouts/taxonomy/terms.rss.xml layouts/taxonomy/rss.xml layouts/taxonomy/list.rss.xml layouts/taxonomy/category.terms.xml layouts/taxonomy/terms.xml layouts/taxonomy/list.xml layouts/category/category.terms.rss.xml layouts/category/terms.rss.xml layouts/category/rss.xml layouts/category/list.rss.xml layouts/category/category.terms.xml layouts/category/terms.xml layouts/category/list.xml layouts/_default/category.terms.rss.xml layouts/_default/terms.rss.xml layouts/_default/rss.xml layouts/_default/list.rss.xml layouts/_default/category.terms.xml layouts/_default/terms.xml layouts/_default/list.xml layouts/_internal/_default/rss.xml]
Taxonomy term in categories HTML html [layouts/categories/category.terms.html.html layouts/categories/terms.html.html layouts/categories/list.html.html layouts/categories/category.terms.html layouts/categories/terms.html layouts/categories/list.html layouts/taxonomy/category.terms.html.html layouts/taxonomy/terms.html.html layouts/taxonomy/list.html.html layouts/taxonomy/category.terms.html layouts/taxonomy/terms.html layouts/taxonomy/list.html layouts/category/category.terms.html.html layouts/category/terms.html.html layouts/category/list.html.html layouts/category/category.terms.html layouts/category/terms.html layouts/category/list.html layouts/_default/category.terms.html.html layouts/_default/terms.html.html layouts/_default/list.html.html layouts/_default/category.terms.html layouts/_default/terms.html layouts/_default/list.html]

See Also

  • Create Your Own Shortcodes
  • RSS Templates
  • Section Page Templates
  • Single Page Templates
  • Sitemap Template
  • About VoteIT
    • Overview
    • Hugo and GDPR
    • What is Hugo
    • Hugo Features
    • The Benefits of Static
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • VoteIT Modules
  • Content Management
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute
“Hugo's Lookup Order” was last updated: October 24, 2019: remake. (28623dd)
Improve this page
By the VoteIT Authors
VoteIT Logo
  • File an Issue
  • @VoteIT
  • @robin_betahaus
  • @andershultman
 
 

VoteIT Sponsors

Logo for VoteIT
Logo for Betahaus
Logo for Datatrion AB
 

The VoteIT logos are copyright © VoteIT 2011–2019.

  • News
  • Documentation
  • Themes
  • Showcase
  • Community
  • GitHub
  • About VoteIT
  • Getting Started
  • VoteIT Modules
  • Content Management
  • Templates
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute