Template types

Create templates of different types to render your content, resources, and data.

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/
├── _default/
│   ├── _markup/
│   │   ├── render-image.html   <-- render hook
│   │   └── render-link.html    <-- render hook
│   ├── baseof.html
│   ├── home.html
│   ├── section.html
│   ├── single.html
│   ├── taxonomy.html
│   └── term.html
├── articles/
│   └── card.html               <-- content view
├── partials/
│   ├── footer.html
│   └── header.html
└── shortcodes/
    ├── audio.html
    └── video.html

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

The purpose of each template type is described below.

Base #

Base templates reduce duplicate code by wrapping other templates within a shell.

For example, the base template below calls the [partial] function to include partial templates for the head, header, and footer elements of each page, and it uses the [block] function to include home, single, section, taxonomy, and term templates within the main element of each page.

layouts/_default/baseof.html

<!DOCTYPE html>
<html lang="{{ or site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
  {{ partial "head.html" . }}
</head>
<body>
  <header>
    {{ partial "header.html" . }}
  </header>
  <main>
    {{ block "main" . }}{{ end }}
  </main>
  <footer>
    {{ partial "footer.html" . }}
  </footer>
</body>
</html>

Learn more about base templates.

Home #

A home page template is used to render your site’s home page, and is the only template required for a single-page website. For example, the home page template below inherits the site’s shell from the base template and renders the home page content, such as a list of other pages.

layouts/_default/home.html

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

Learn more about home page templates.

Single #

A single template renders a single page.

For example, the single template below inherits the site’s shell from the base template, and renders the title and content of each page.

layouts/_default/single.html

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

Learn more about single templates.

Section #

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

For example, the section template below inherits the site’s shell from the base template, and renders a list of pages in the current section.

layouts/_default/section.html

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

Learn more about section templates.

Taxonomy #

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

For example, the taxonomy template below inherits the site’s shell from the base template, and renders a list of terms in the current taxonomy.

layouts/_default/taxonomy.html

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

Learn more about taxonomy templates.

Term #

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

For example, the term template below inherits the site’s shell from the base template, and renders a list of pages associated with the current term.

layouts/_default/term.html

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

Learn more about term templates.

Partial #

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

For example, the partial template below renders copyright information.

Learn more about partial templates.

Content view #

A content view template is similar to a partial template, invoked by calling the [Render] method on a Page object. Unlike partial templates, content view templates:

Automatically inherit the context of the current page
Follow a lookup order allowing you to target a given content type or section

For example, the home template below inherits the site’s shell from the base template, and renders a card component for each page within the “articles” section of your site.

layouts/_default/home.html

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

layouts/articles/card.html

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

Learn more about content view templates.

Render hook #

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

For example, the render hook template below adds a rel attribute to external links.

layouts/_default/_markup/render-link.html

{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
  {{- if $u.IsAbs }} rel="external"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}

Learn more about render hook templates.

Shortcode #

A shortcode template is used to render a component of your site. Unlike partial templates, shortcode templates are called from content pages.

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

layouts/shortcodes/audio.html

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

Then call the shortcode from within markup:

content/example.md

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

Learn more about shortcode templates.

Other #

Use other specialized templates to create: