Hugo Templating

Variables

Page Variables

Official Documentation

Below page collections can be accessed from any scope in the templates:

• .Site.Pages - all pages of the site: regular pages, sections, taxonomies, etc.
• .Site.RegularPages - only regular pages.

Below variables return pages from the scope of the current list page:

• .Pages - regular pages and first-level section pages under the current list page.
• .RegularPages - only regular pages under the current list page, excluding regular pages in nested sections/list pages.
• .RegularPagesRecursive - all regular pages under a list page, including regular pages in nested sections/list pages

File Variables

Official Hugo Documentation

The .File object contains the following fields:

Site Variables

Official Documentation

Section Variables

Official Documentation

Also see Sections

• .Sections - all sections below the content
• .Section - the section that the content belongs to
• .Parent - A section’s parent section or a page’s section.
• .CurrentSection - The page’s current section. The value can be the page itself if it is a section or the homepage.
• .FirstSection- The page’s first section below root, e.g. /docs, /blog etc.
• .NextInSection - Next regular page in the same section
• .InSection $page - Whether the given page is in the current section.
• .IsAncestor $page - Whether the current page is an ancestor of the given page.
• .IsDescendant $page - Whether the current page is a descendant of the given page.

^(\.(\w+))+\n(.*)

Content Lists

Hugo provides example partials for list templates.

List all site menus

List site menus as defined in menus.yaml

{{ range .Site.Menus.main }}
<a href="{{ .URL }}" class="...">{{ .Name }}</a>
{{ end }}

List all pages

{{ range .Site.Sections }}
<a href="{{ .RelPermalink }}" class="...">{{ .Title }}</a>
{{ end }}

Pages without param

Iterates over all regular pages and excludes pages with either:

1. hidden set to true, or
2. pages with no hidden param.

{{ $hidden_pages := where .Site.RegularPages "Params.hidden" true }} {{ $pages := .Site.RegularPages | complement
$hidden_pages }}

List all site tags

<ul>
  {{ range .Site.Taxonomies.tags }}
  <li>
    <a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a>
    {{ .Count }}
  </li>
  {{ end }}
</ul>

List pages in a series

<!-- using .Site.Taxonomies  -->
<ul>
  {{ range .Site.Taxonomies.series.hugo }}
  <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
  {{ end }}
</ul>

<!-- using filter -->
{{ range where .Site.Pages "Params.series" "hugo" }} {{ .Content }} {{ end }}

List pages with summary

<h1>{{ .Title }}</h1>
<!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
{{ range .Pages }} {{ .Render "summary"}} {{ end }}

List page categories

{{ if .Params.categories }} {{- range $index, $value := (.GetTerms "categories") -}} {{- if gt $index 0 }}, {{ end -}}
<a href="{{ .RelPermalink }}">{{- humanize .LinkTitle -}}</a>
{{- end -}} {{ end }}

List subsections of a section

{{ range (where .Site.Pages "Section" "docs") }}
<ul>
  {{ range .Sections }}
  <li><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li>
  {{end}}
</ul>
{{ end }}

List pages in a section if there is at least one page

{{ $pages := where .Site.RegularPages "Section" "docs" }} {{ $count := len $pages }} {{ if gt $count 0 }} ... {{ end }}

source

List pages in a section with a given param

<!--Pages in the "docs" section with a "summary" param -->
{{ $docs := where .Site.RegularPages "Section" "docs" }} {{ $pages := where $docs "Params.type" "summary" }}

<!-- Pages in the "docs" section where "drafts" = false -->
{{$pages := where (where .Site.RegularPages "Section" "docs") ".Params.draft" false }}

List pages in a section with options

{{ range ((where .Pages ".Params.draft" false).ByParam "order").Reverse }}

Functions

See Functions Quick Reference in the official Hugo docs

Logic Checks

<!-- syntax: -->
{{
<operator>
  <val1><val2>}}</val2></val1>
</operator>

<!-- if... else -->
{{ if }} ... {{ else }} ... {{ end }}

<!-- arg1 == arg2 -->
{{ if eq arg1 arg2 }}

<!-- arg1 != arg2 -->
{{ if ne arg1 arg2 }}

<!-- arg1 < arg2 -->
{{ if lt arg1 arg2 }}

<!-- arg1 > arg2 -->
{{ if gt arg1 arg2 }}

<!-- arg0 < arg1 < arg2 -->
{{ if and (lt arg1 arg2) (gt arg1 arg0) }}

source

Strings

Replace character in string

{{ replace $tag "_" " "}}

Conditionals

source: Hugo docs

if, else, with, or, and and provide the framework for handling conditional logic in Go Templates. Like range, each statement is closed with an {{ end }}.

Go Templates treat the following values as false:

• false (boolean)
• 0 (integer)
• any zero-length array, slice, map, or string

Partial Templates

Hugo’s partial templates are HTML template snippets that can be reused throughout the site’s layout templates. Partial templates should be placed within layouts/partials/.

Shortcodes

Shortcodes enable access to HTML templates snippets from within markdown files. Hugo ships with built-in shortcodes and has support for custom shortcodes . Custom shortcodes should be placed within layouts/shortcodes.

Get parameter by name

{{ .Get "parameter" }}

Get parameter by position

{{ .Get 0 }}

Output based on parameter

{{ with .Get "class" }} class="{{ . }}"{{ end }}

Paired shortcodes

Use {{ .Inner }} to access content sandwiched in paired shortcodes.

{{< alert note >}}
This is a note.
{{< /alert >}}

Escape shortcodes

source: liatas.com

{{</* myshortcode */>}}

Assets and Styles

Importing Google fonts

@import url('https://fonts.googleapis.com/css2?family=Cousine&family=Lato&family=Lora&display=swap');

Template Lookup Order

Official Documentation

Layout Lookup for Section Pages

1. layouts/posts/posts.html
2. layouts/posts/section.html
3. layouts/posts/list.html
4. layouts/section/posts.html
5. layouts/section/section.html
6. layouts/section/list.html
7. layouts/_default/posts.html
8. layouts/_default/section.html
9. layouts/_default/list.html

Layout Lookup for Term Pages

1. layouts/categories/term.html
2. layouts/categories/category.html
3. layouts/categories/taxonomy.html
4. layouts/categories/list.html
5. layouts/term/term.html
6. layouts/term/category.html
7. layouts/term/taxonomy.html
8. layouts/term/list.html
9. layouts/taxonomy/term.html
10. layouts/taxonomy/category.html
11. layouts/taxonomy/taxonomy.html
12. layouts/taxonomy/list.html
13. layouts/category/term.html
14. layouts/category/category.html
15. layouts/category/taxonomy.html
16. layouts/category/list.html
17. layouts/layouts/layouts/layouts/layouts/_default/term.html
18. layouts/_default/category.html
19. layouts/_default/taxonomy.html
20. layouts/_default/list.html