Template Lookup: A Guide

tips & tricks
1

Hugo’s Templates Lookup

Docs ref

Demo / Source

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:

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)
    a. derived from .Type
    - From the docs[^note3]
    - So in the case of the homepage, the value will be either what is set on the frontmatter, or "page".

    b. "": For the homepage, the layout file can be located just below layouts/, ie no [directory].
    c. "_default": default

  3. filename: its value can be (with highest priority on top)
    a. derived from layout set in the frontmatter.
    b. "index"
    c. derived from the value of .Kind: "home"
    d. "list": default

  4. [lang]
    a. language code, eg "en", "fr", etc.

  5. [outputformat]
    a. the output format name (eg "amp") [^note1]

  6. suffix
    a. the output format suffix (eg "html") [^note1]

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
    a. derived from .Type[^note3]
    b. derived from .Kind: "section"
    c. "_default": default

  2. filename: its value can be
    a. derived from layout set in the frontmatter.
    b. 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.
    c. derived from .Kind: "section". Not to be confused with 3.b, this is the actual string "section".
    d. "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
    a. derived from .Type[^note3]
    b. "_default": default

  2. filename: its value can be
    a. derived from layout set in the frontmatter.
    b. "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
    a. derived from .Type[^note3]
    b. "taxonomy": the actual string "taxonomy"
    c. derived from its singular form (eg "tag" for above configuration)
    d. "_default": default

  2. filename: its value can be
    a. derived from layout set in the frontmatter.
    b. derived from <singular> . terms (eg "tag.terms" for above config)
    c. "terms": the string "terms"
    d. "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
    a. derived from .Type[^note3]
    b. "taxonomy": the actual string "taxonomy"
    c. derived from the singular form of its term (eg "tag" for above configuration)
    d. "_default": default

  2. filename: its value can be
    a. derived from layout set in the frontmatter.
    b. derived from <singular> term (eg "tag" for above config)
    c. "taxonomy": the string "taxonomy"
    d. "list": default

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

Some examples

Head over here for some basic examples. [GitHub]

Minimum example

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

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

Demo / Source

Multilingual example

Demo / Source

Extra examples

Demo / Source

  • Section lorem/_index.md has customtype.

    • What layout will children pages / sections use?

      • child pages lorem/ipsum.md will have .Type = lorem [^note2]
      • child section lorem/ipsum/_index.md will have .Type = lorem [^note2]

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

  • Section lorem/_index.md has customlayout

    • child pages lorem/ipsum.md will not use customlayout [^note2]
    • 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.

Notes:

[^note1]: See docs

[^note2]: unless cascaded from parent or otherwise configured.

[^note3]: 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”.

Suggestions / corrections welcome!

8 Likes
2

This is really cool :+1: :+1: :+1:
now i dont need to make dummy repo to test this kind of thing.

Just a suggestion, i think it’s better if the sidebar always open. Because when i exploring each pages, the thing i want to check is “What variables available for this page”.

Cheers :tada:

3

if this is absolutely correct, can we fold this explanation into the docs @kaushalmodi ? it would bee good to have both the example-based definition and this more “formal” definition

1 Like
4

@pamubay Thanks! I originally had the sidebar always open, but I found that it took too much space.

@HenrySkup I’m not sure that’s necessarily a good idea, which is why I haven’t worked on making this a PR to the docs.

It feels (for me) like it would clutter the docs to have too many examples. Plenty of people have been able to create sites with Hugo just with the docs as it stands now, so I would assume that it is sufficient (and sufficiently effective) for most of Hugo’s audience.

As an alternative, however: perhaps a link to either this discussion or the demo itself. I could spin this into its own project (currently it’s bundled with my other tips n tricks post).