Layout Lookup Order

Docs ref

On this page:

Looking at the extensive list of examples in the docs might be a bit overwhelming to new Hugo users, but it is not that complicated once we break it down.

Layout files are generally in the pattern:

    1            2           3         4           5             6
layoutDir / [directory] / filename . [lang] . [outputformat] . suffix

Let’s look at each page .Kind to see how the values of these parts are affected:

Template Lookup by .Kind

home

content/_index.md   =>  example.com/index.html

  1. layoutDir: By default, the value is layouts. You can configure this value, but for the examples we will assume this default value is used.

  2. [directory]: its value can be (with highest priority on top)

    1. derived from .Type

      • From the docs1
      • So in the case of the homepage, the value will be either what is set on the frontmatter, or "page".

    2. -: For the homepage, the layout file can be located just below layouts/.

    3. "_default": default

  3. filename: its value can be (with highest priority on top)

    1. derived from layout set in the frontmatter.
    2. "index"
    3. derived from the value of .Kind: "home"
    4. "list": default

  4. [lang]

    1. language code, eg "en", "fr", etc.

  5. [outputformat]

    1. the output format name (eg "amp") 2

  6. suffix

    1. the output format suffix (eg "html") 2

Items #1, #4, #5, #6 are the same for .Kinds below.

section

content/posts/_index.md       =>  example.com/posts/

  1. [directory]: its value can be

    1. derived from .Type1
    2. derived from .Kind: "section"
    3. "_default": default

  2. filename: its value can be

    1. derived from layout set in the frontmatter.
    2. derived from its .Section, eg "posts". Not to be confused with 2.b or 3.c, which is the actual string "section", this is the value of the top-level directory under content. See docs for details.
    3. derived from .Kind: "section". Not to be confused with 3.b, this is the actual string "section".
    4. "list": default

See above for #1, #4, #5, #6

page

content/posts/post-one.md           =>  example.com/posts/post-one/
content/posts/post-one/index.md     =>  example.com/posts/post-one/
content/about.md                    =>  example.com/about/
content/about/index.md              =>  example.com/about/

  1. [directory]: its value can be

    1. derived from .Type1
    2. "_default": default

  2. filename: its value can be

    1. derived from layout set in the frontmatter.
    2. "single": default

See above for #1, #4, #5, #6

taxonomyTerm

content/tags/_index.md      =>  example.com/tags/

[taxonomies]
tag = "tags"

  1. [directory]: its value can be

    1. derived from .Type1
    2. "taxonomy": the actual string "taxonomy"
    3. derived from its singular form (eg "tag" for above configuration)
    4. "_default": default

  2. filename: its value can be

    1. derived from layout set in the frontmatter.
    2. derived from <singular> . terms (eg "tag.terms" for above config)
    3. "terms": the string "terms"
    4. "list": default

See above for #1, #4, #5, #6

taxonomy

content/tags/foo/_index.md      =>  example.com/tags/foo/

[taxonomies]
tag = "tags"

  1. [directory]: its value can be

    1. derived from .Type1
    2. "taxonomy": the actual string "taxonomy"
    3. derived from the singular form of its term (eg "tag" for above configuration)
    4. "_default": default

  2. filename: its value can be

    1. derived from layout set in the frontmatter.
    2. derived from <singular> term (eg "tag" for above config)
    3. "taxonomy": the string "taxonomy"
    4. "list": default

See above for #1, #4, #5, #6

Some examples

Below are some examples of the effects of values of the above criteria on the layout template used.

Click « on the right to expand the info panel to see these values.

Minimum example

Hugo can generate your entire site with just two template files:

  • _default/list.html
  • _default/single.html

You can see this in action by running Hugo with the included minconfig.toml configuration:

hugo server --config minconfig

Multilingual example

This site is configured multilingual by content directory , with English being the default language and Latin a second one. Latin content files are under the /lorem/ content directory.

/metals/ and /la/metals/ both have layout: customlayout in their frontmatter.

  • /metals/ uses layouts/metals/customlayout.html (<type> / <customlayout> . <suffix>)
  • /la/metals/ uses layouts/metals/customlayout.la.html (<type> / <customlayout> . <lang> . <suffix>)

Extra examples

  • Section lorem/_index.md has customtype.

    • What layout will children pages / sections use?
    • How do I make children pages / sections also have customtype type?

      • Use cascade in the frontmatter to make the child pages inherit the same value. Alternatively, set the type of each content you want customtype to apply to.

        Try the cascade option by renaming the frontmatter of content/fruit/_index.md from x_cascade: to cascade:.

  • Section lorem/_index.md has customlayout

    • child pages lorem/ipsum.md will not use customlayout 3

      See examples:

    • Similar to the above, you can cascade the layout frontmatter so the child pages inherit the same value. Otherwise, you can set the value to each content individually.

      Try the cascade option by renaming the frontmatter of content/fruit/_index.md from x_cascade: to cascade:.

Notes:

  1. From the docs : Is value of type if set in front matter, else it the name of the root section (e.g. “blog”). It will always have a value, so if not set, the value is “page”. ↩︎

  2. See docs ↩︎

  3. unless cascaded from parent or otherwise configured. ↩︎

Some Page Vars

DOT (.) Page(/layout-lookup.md)
.File layout-lookup.md
.Kind page
.Type page
.Section
.Sections
.Parent Page(/_index.md)
.IsPage true
.IsNode false
.Pages
.Resources false

Content Structure

Homepage _index.md
  1. Circle circle/index.md
  2. Clouds clouds/_index.md
    1. Cirrus clouds/cirrus.md
    2. Nimbus clouds/nimbus.md
  3. Colors colors/_index.md
    1. Blue Title colors/blue/index.md
    2. Green Title colors/green.md
    3. Orange Title colors/orange/index.md
    4. Red Title colors/red.md
    5. Yellow Title colors/yellow/index.md
  4. Crescent crescent/index.md
  5. Ellipse ellipse/index.md
  6. Fruit fruit/_index.md
    1. Banana fruit/banana.md
    2. Berries fruit/berries/_index.md
      1. Blackberries fruit/berries/blackberries/index.md
      2. Blueberries fruit/berries/blueberries/index.md
      3. Raspberries fruit/berries/raspberries.md
      4. Strawberries fruit/berries/strawberries/index.md
    3. Citrus fruit/citrus/_index.md
      1. Lemons fruit/citrus/lemons.md
      2. Limes fruit/citrus/limes.md
      3. Oranges fruit/citrus/oranges.md
    4. Stonefruit fruit/stonefruit/_index.md
      1. Apricots fruit/stonefruit/apricots.md
      2. Nectarines fruit/stonefruit/nectarines.md
      3. Plums fruit/stonefruit/plums.md
  7. Layout Lookup Order layout-lookup.md
  8. Letters letters/_index.md
    1. A letters/a.md
    2. B letters/b.md
  9. Metals metals/_index.md
    1. Gold metals/gold.md
    2. Silver metals/silver.md
  10. Oval oval/index.md
  11. Page Resources page-resources.md
  12. Rectangle rectangle.md
  13. Rhombus rhombus.md
  14. Single vs List single-vs-list.md
  15. Square square.md
  16. Trapezoid trapezoid.md
  17. Trees trees/_index.md
    1. Acacia trees/acacia.md
    2. Fig trees/fig.md
    3. Mahogany trees/mahogany.md
    4. Pine trees/pine.md

Sibling Sections (.Parent.Sections)

PageTitleFile
Page(/clouds/_index.md) Clouds clouds/_index.md
Page(/colors/_index.md) Colors colors/_index.md
Page(/fruit/_index.md) Fruit fruit/_index.md
Page(/letters/_index.md) Letters letters/_index.md
Page(/metals/_index.md) Metals metals/_index.md
Page(/trees/_index.md) Trees trees/_index.md

No Children Sections (.Sections)

No Children Pages (.Pages)

No Page Resources