6.9 KiB
| aliases | date | linktitle | menu | next | prev | title | weight | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2013-07-01 | Functions |
|
/templates/variables | /templates/go-templates | Hugo Template Functions | 20 |
Hugo uses the excellent Go html/template library for its template engine. It is an extremely lightweight engine that provides a very small amount of logic. In our experience it is just the right amount of logic to be able to create a good static website.
Go templates are lightweight but extensible. Hugo has added the following functions to the basic template logic.
(Go itself supplies built-in functions, including comparison operators and other basic tools; these are listed in the Go template documentation.)
General
isset
Return true if the parameter is set. Takes either a slice, array or channel and an index or a map and a key as input.
e.g. {{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}
echoParam
If parameter is set, then echo it.
e.g. {{echoParam .Params "project_url" }}
eq
Return true if the parameters are equal.
e.g.
{{ if eq .Section "blog" }}current{{ end }}
first
Slices an array to only the first X elements.
Works on lists, taxonomies, terms, groups
e.g.
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
where
Filters an array to only elements containing a matching value for a given field.
Works on lists, taxonomies, terms, groups
e.g.
{{ range where .Data.Pages "Section" "post" }}
{{ .Content}}
{{ end }}
where and first can be stacked
e.g.
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content}}
{{ end }}
delimit
Loops through any array, slice or map and returns a string of all the values separated by the delimiter. There is an optional third parameter that lets you choose a different delimiter to go between the last two values. Maps will be sorted by the keys, and only a slice of the values will be returned, keeping a consistent output order.
Works on lists, taxonomies, terms, groups
e.g. // Front matter +++ tags: [ "tag1", "tag2", "tag3" ] +++
// Used anywhere in a template
Tags: {{ delimit .Params.tags ", " }}
// Outputs Tags: tag1, tag2, tag3
// Example with the optional "last" parameter
Tags: {{ delimit .Params.tags ", " " and " }}
// Outputs Tags: tag1, tag2 and tag3
sort
Sorts maps, arrays and slices, returning a sorted slice. A sorted array of map values will be returned, with the keys eliminated. There are two optional arguments, which are sortByField and sortAsc. If left blank, sort will sort by keys (for maps) in ascending order.
Works on lists, taxonomies, terms, groups
e.g. // Front matter +++ tags: [ "tag3", "tag1", "tag2" ] +++
// Site config
+++
[params.authors]
[params.authors.Derek]
"firstName" = "Derek"
"lastName" = "Perkins"
[params.authors.Joe]
"firstName" = "Joe"
"lastName" = "Bergevin"
[params.authors.Tanner]
"firstName" = "Tanner"
"lastName" = "Linsley"
+++
// Use default sort options - sort by key / ascending
Tags: {{ range sort .Params.tags }}{{ . }} {{ end }}
// Outputs Tags: tag1 tag2 tag3
// Sort by value / descending
Tags: {{ range sort .Params.tags "value" "desc" }}{{ . }} {{ end }}
// Outputs Tags: tag3 tag2 tag1
// Use default sort options - sort by value / descending
Authors: {{ range sort .Site.Params.authors }}{{ .firstName }} {{ end }}
// Outputs Authors: Derek Joe Tanner
// Use default sort options - sort by value / descending
Authors: {{ range sort .Site.Params.authors "lastName" "desc" }}{{ .lastName }} {{ end }}
// Outputs Authors: Perkins Linsley Bergevin
in
Checks if an element is in an array (or slice) and returns a boolean. The elements supported are strings, integers and floats (only float64 will match as expected). In addition, it can also check if a substring exists in a string.
e.g.
{{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }}
or
{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}
intersect
Given two arrays (or slices), this function will return the common elements in the arrays. The elements supported are strings, integers and floats (only float64).
A useful example of this functionality is a 'similar posts' block. Create a list of links to posts where any of the tags in the current post match any tags in other posts.
e.g.
<ul>
{{ $page_link := .Permalink }}
{{ $tags := .Params.tags }}
{{ range .Site.Recent }}
{{ $page := . }}
{{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }}
{{ if and $has_common_tags (ne $page_link $page.Permalink) }}
<li><a href="{{ $page.Permalink }}">{{ $page.Title }}</a></li>
{{ end }}
{{ end }}
</ul>
Math
add
Adds two integers.
e.g. {{add 1 2}} → 3
sub
Subtracts two integers.
e.g. {{sub 3 2}} → 1
div
Divides two integers.
e.g. {{div 6 3}} → 2
mul
Multiplies two integers.
e.g. {{mul 2 3}} → 6
mod
Modulus of two integers.
e.g. {{mod 15 3}} → 0
modBool
Boolean of modulus of two integers. true if modulus is 0.
e.g. {{modBool 15 3}} → true
Strings
urlize
Takes a string and sanitizes it for usage in URLs, converts spaces to "-".
e.g. <a href="/tags/{{ . | urlize }}">{{ . }}</a>
safeHtml
Declares the provided string as "safe" so Go templates will not filter it.
e.g. {{ .Params.CopyrightHTML | safeHtml }}
markdownify
This will run the string through the Markdown processesor. The result will be declared as "safe" so Go templates will not filter it.
e.g. {{ .Title | markdownify }}
lower
Convert all characters in string to lowercase.
e.g. {{lower "BatMan"}} → "batman"
upper
Convert all characters in string to uppercase.
e.g. {{upper "BatMan"}} → "BATMAN"
title
Convert all characters in string to titlecase.
e.g. {{title "BatMan"}} → "Batman"
highlight
Take a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the highlight shortcode.
ref, relref
Looks up a content page by relative path or logical name to return the permalink (ref) or relative permalink (relref). Requires a Node or Page object (usually satisfied with .). Used in the [ref and relref shortcodes]({{% ref "extras/crossreferences.md" %}}).
e.g. {{ ref . "about.md" }}