Layouts / Templating

Layouts

• HTML Templates.

• Any folder in layouts  that does not start with _  represents the root of a Page path . In Hugo v0.146.0 , this can be nested as deeply as needed, and _shortcodes  and _markup  folders can be placed at any level in the tree.

• The layouts/shortcodes  folder is renamed to layouts/_shortcodes .

• The layouts/partials  folder is renamed to layouts/_partials .

• The _default  folder is removed.

  • Move all files in layouts/_default  up to the layouts/  root.

• The above also means that there’s no top-level layouts/taxonomy  or layouts/section  folders anymore, unless it represents a Page path .

  • Move them up to layouts/  with one of the Page kinds   section , taxonomy  or term  as the base name, or place the layouts into the taxonomy Page path .

• A template named taxonomy.html  used to be a candidate for both Page kind term  and taxonomy , now it’s only considered for taxonomy .

  • Create both taxonomy.html  and term.html  or create a more general layout, e.g. list.html .

• For base templates (e.g., baseof.html ), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword.

  • Move that identifier after the first “dot,” e.g., rename list-baseof.html  to baseof.list.html .

• We have added a new all  “catch-all” layout. This means that if you have, e.g., layouts/all.html  and that is the only template, that layout will be used for all HTML page rendering.

• We have removed the concept of _internal  Hugo templates. 1

  • Replace constructs similar to {{ template "_internal/opengraph.html" . }}  with {{ partial "opengraph.html" . }} .

• The identifiers that can be used in a template filename are one of the Page kinds  ( home , page , section , taxonomy , or term ), one of the standard layouts ( list , single , or all ), a custom layout (as defined in the layout  front matter field), a language (e.g., en ), an output format (e.g., html , rss ), and a suffix representing the media type. E.g., all.en.html  and home.rss.xml .

• The above means that there’s no such thing as an index.html  template for the home page anymore.

  • Rename index.html  to home.html .

Types

• Base :

  • A base  template serves as a foundational layout that other templates can build upon. It typically defines the common structural components of your HTML, such as the html , head , and body  elements. It also often includes recurring features like headers, footers, navigation, and script inclusions that appear across multiple pages of your site.

  • Hugo can apply a base  template to the following template types: home , page , section , taxonomy , term , single , list , and all . When Hugo parses any of these template types, it will apply a base  template only if the template being parsed meets these specific conditions:

    • It must include at least one define   action .

    • It can only contain define  actions, whitespace, and template comments . No other content is allowed.

  • If a template doesn’t meet all these criteria, Hugo executes it exactly as provided, without applying a base  template.

  • When Hugo applies a base  template, it replaces its block  actions with content from the corresponding define  actions found in the template to which the base template is applied.

  • For example, the base  template below calls the partial  function to include head , header , and footer  elements. The block  action acts as a placeholder, and its content will be replaced by a matching define  action from the template to which it is applied.

• Home :

  • A home  template renders your site’s home page.

  • For example, Hugo applies a base  template to the home  template, then renders the page content and a list of the site’s regular pages.

• Page :

  • A page  template renders a regular page.

  • For example, Hugo applies a base  template to the page  template, then renders the page title and page content.

• Section :

  • A section  template renders a list of pages within a section .

  • For example, Hugo applies a base  template to the section  template, then renders the page title, page content, and a list of pages in the current section.

• Taxonomy :

  • A taxonomy  template renders a list of terms in a taxonomy .

  • For example, Hugo applies a base  template to the taxonomy  template, then renders the page title, page content, and a list of terms  in the current taxonomy.

  • Within a taxonomy  template, the Data  object provides these taxonomy-specific methods:

    • Singular

    • Plural

    • Terms

  • The Terms  method returns a taxonomy object , allowing you to call any of its methods including Alphabetical  and ByCount . For example, use the ByCount  method to render a list of terms sorted by the number of pages associated with each term:

• Term :

  • A term  template renders a list of pages associated with a term .

  • For example, Hugo applies a base  template to the term  template, then renders the page title, page content, and a list of pages associated with the current term.

  • Within a term  template, the Data  object provides these term-specific methods:

    • Singular

    • Plural

    • Term

• Single :

  • A single  template is a fallback for a page  template. If a page  template does not exist, Hugo will look for a single  template instead.

  • For example, Hugo applies a base  template to the single  template, then renders the page title and page content.

• List :

  • A list  template is a fallback for home , section , taxonomy , and term  templates. If one of these template types does not exist, Hugo will look for a list  template instead.

  • For example, Hugo applies a base  template to the list  template, then renders the page title, page content, and a list of pages.

  • _index.md .

    • It allows you to add front matter and content to home , section , taxonomy , and term  pages.

    • Access the content and metadata within an _index.md  file by invoking the GetPage  method on a Site  or Page  object.

• All :

  • An all  template is a fallback for home , page , section , taxonomy , term , single , and list  templates. If one of these template types does not exist, Hugo will look for an all  template instead.

  • For example, Hugo applies a base  template to the all  template, then conditionally renders a page based on its page kind.

• Partial :

  • A partial  template is typically used to render a component of your site, though you may also create partial  templates that return values.

  • Partials vs Shortcodes :

    • You can Partials in Templates.

    • You can Shortcodes in files.

  (( partial "header" . ))
  

  • The .  represents the scope of what you want to access.

  • "header"  is the name of the partial template, located as layouts/partial/header.html .

Lookup Order

| Identifier                                         | Description                                                                                   |
|----------------------------------------------------|-----------------------------------------------------------------------------------------------|
| Layout custom                                      | The custom layout  set in front matter.                                                      |
| Page kinds  | One of home , section , taxonomy , term , page .                                         |
| Layouts standard 1                                 | list  or single .                                                                           |
| Output format                                      | The output format (e.g., html , rss ).                                                      |
| Layouts standard 2                                 | all .                                                                                        |
| Language                                           | The language (e.g., en ).                                                                    |
| Media type                                         | The media type (e.g., text/html ).                                                           |
| Page path   | The page path (e.g., /blog/mypost ).                                                         |
| Type                                               | type  set in front matter. 2  |

Shortcodes

• Predefined chunks of HTML code that you can insert into the markdown files.

• ((< shortcode-name param1 >))

• Hugo comes will some shortcodes predefined:

  • ((< youtube j11Nm4i4XbI >))

    • This is the id for the youtube video of oppenheimer ost.

Emojis

• Hugo Emojis .

Numbered List / Ordered List

• .