Template types

Structure

Create templates in the layouts directory in the root of your project.

Although your site may not require each of these templates, the example below is typical for a site of medium complexity.

layouts/
├── _markup/
│   ├── render-image.html   <-- render hook
│   └── render-link.html    <-- render hook
├── _partials/
│   ├── footer.html
│   └── header.html
├── _shortcodes/
│   ├── audio.html
│   └── video.html
├── books/
│   ├── page.html
│   └── section.html
├── films/
│   ├── _views/
│   │   └── card.html       <-- view template
│   ├── page.html
│   └── section.html
├── baseof.html
├── home.html
├── page.html
├── section.html
├── taxonomy.html
└── term.html

Hugo’s template lookup order determines the template path, allowing you to create unique templates for any page.

The sections below describe the purpose of each template type.

Base

A base template is a layout that other templates build upon. It typically defines the common structure of your HTML, such as the html, head, and body elements. It often includes features that appear on many pages of your site, such as headers, footers, navigation, and scripts. Defining these once in a base template avoids repetition, keeps pages consistent, and makes your site easier to maintain.

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 applies a base template only if the template being parsed meets these conditions:

• It must include at least one define action.
• It can only contain define actions, whitespace, and template comments. No other content is allowed.

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 partials.Include function to include head, header, and footer elements. The block action acts as a placeholder, and Hugo replaces its content with a matching define action from the template to which it is applied.

<!DOCTYPE html>
<html lang="{{ site.Language.Locale }}" dir="{{ or site.Language.Direction `ltr` }}">
<head>
  {{ partial "head.html" . }}
</head>
<body>
  <header>
    {{ partial "header.html" . }}
  </header>
  <main>
    {{ block "main" . }}
      This will be replaced with content from the
      corresponding "define" action found in the template
      to which this _base_ template is applied.
    {{ end }}
  </main>
  <footer>
    {{ partial "footer.html" . }}
  </footer>
</body>
</html>

{{ define "main" }}
  This will replace the content of the "block" action
  found in the _base_ template.
{{ end }}

Home

A home template renders your site’s home page.

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

{{ define "main" }}
  {{ .Content }}
  {{ range .Site.RegularPages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

Page

A page template renders a regular page.

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

Section

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

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

Taxonomy

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

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

Within a taxonomy template, the Data object provides the taxonomy-specific methods Singular, Plural, and 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:

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.ByCount }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
  {{ end }}
{{ end }}

Term

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

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

Within a term template, the Data object provides the term-specific methods Singular, Plural, and Term.

Single

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

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

List

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

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

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

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 looks for an all template instead.

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

{{ define "main" }}
  {{ if eq .Kind "home" }}
    {{ .Content }}
    {{ range .Site.RegularPages }}
      <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
    {{ end }}
  {{ else if eq .Kind "page" }}
    <h1>{{ .Title }}</h1>
    {{ .Content }}
  {{ else if in (slice "section" "taxonomy" "term") .Kind }}
    <h1>{{ .Title }}</h1>
    {{ .Content }}
    {{ range .Pages }}
      <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
    {{ end }}
  {{ else }}
    {{ errorf "Unsupported page kind: %s" .Kind }}
  {{ end }}
{{ end }}

Partial

Use a partial template to render a component of your site, or to return a value.

For example, the partial template below renders copyright information:

<p>Copyright {{ now.Year }}. All rights reserved.</p>

Execute the partial template by calling the partials.Include or partials.IncludeCached function, optionally passing context as the second argument:

{{ partial "footer.html" . }}

Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching partial template. However, it applies the same name matching logic it uses for other template types. It tries to find the most specific match first, then looks for more general matches.

For example, consider this call:

{{ partial "footer.section.de.html" . }}

Hugo uses this lookup order to find a matching template:

1. layouts/_partials/footer.section.de.html
2. layouts/_partials/footer.section.html
3. layouts/_partials/footer.de.html
4. layouts/_partials/footer.html

Inline partial

You can also define a partial template inline within another template. Hugo registers inline partial templates globally, so you can call one from any template. Give each inline partial template a unique name to prevent conflicts.

Value: {{ partial "my-inline-partial.html" . }}

{{ define "_partials/my-inline-partial.html" }}
  {{ $value := 32 }}
  {{ return $value }}
{{ end }}

View

A view template is similar to a partial template. Execute it by calling the Render method on a Page object. The table below compares the two.

For example, Hugo applies a base template to the home template below, then renders the page content and a card component for each page within the films section of your site.

{{ define "main" }}
  {{ .Content }}
  <ul>
    {{ range where site.RegularPages "Section" "films" }}
      {{ .Render "_views/card" }}
    {{ end }}
  </ul>
{{ end }}

<div class="card">
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ .Summary }}
</div>

See the Render method documentation for guidance on naming and organizing view templates.

Render hook

A render hook template overrides the conversion of Markdown to HTML.

For example, the render hook template below adds an anchor link to the right of each heading.

<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
  {{ .Text }}
  <a href="#{{ .Anchor }}">#</a>
</h{{ .Level }}>

Learn more about render hook templates.

Shortcode

Use a shortcode template to render a component of your site. Unlike partial or view templates, you call shortcode templates from content pages.

For example, the shortcode template below renders an audio element from a global resource.

{{ with resources.Get (.Get "src") }}
  <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}

Then call the shortcode from a content page:

{{< audio src=/audio/test.mp3 >}}

Learn more about shortcode templates.

Other

Use other specialized templates to create these files:

• Sitemaps
• RSS feeds
• 404 error pages
• robots.txt files