mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Sort function names in templates documentation
The documentation on the functions is long. It is easier to find a function name when they are sorted within the sections. Fixes #981
This commit is contained in:
mdhender
bep
parent
9de78aab3f
commit
6b50c8fb82
1 changed files with 171 additions and 148 deletions
|
|
@ -26,17 +26,36 @@ and other basic tools; these are listed in the
|
|||
|
||||
## 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.
|
||||
### 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](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -44,6 +63,7 @@ e.g.
|
|||
|
||||
{{ if eq .Section "blog" }}current{{ end }}
|
||||
|
||||
|
||||
### first
|
||||
Slices an array to only the first X elements.
|
||||
|
||||
|
|
@ -55,6 +75,93 @@ e.g.
|
|||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
|
||||
|
||||
### 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>
|
||||
|
||||
|
||||
### 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 }}`
|
||||
|
||||
|
||||
### 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](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
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
|
||||
|
||||
|
||||
### where
|
||||
Filters an array to only elements containing a matching value for a given field.
|
||||
|
||||
|
|
@ -104,105 +211,6 @@ Following operators are now available
|
|||
{{ .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](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
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](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -222,18 +230,6 @@ e.g.
|
|||
<td><code>{{add 1 2}}</code> → 3</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>sub</code></td>
|
||||
<td>Subtracts two integers.</td>
|
||||
<td><code>{{sub 3 2}}</code> → 1</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>mul</code></td>
|
||||
<td>Multiplies two integers.</td>
|
||||
<td><code>{{mul 2 3}}</code> → 6</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>div</code></td>
|
||||
<td>Divides two integers.</td>
|
||||
|
|
@ -251,16 +247,65 @@ e.g.
|
|||
<td>Boolean of modulus of two integers. <code>true</code> if modulus is 0.</td>
|
||||
<td><code>{{modBool 15 3}}</code> → true</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>mul</code></td>
|
||||
<td>Multiplies two integers.</td>
|
||||
<td><code>{{mul 2 3}}</code> → 6</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>sub</code></td>
|
||||
<td>Subtracts two integers.</td>
|
||||
<td><code>{{sub 3 2}}</code> → 1</td>
|
||||
</tr>
|
||||
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## Strings
|
||||
|
||||
### urlize
|
||||
Takes a string and sanitizes it for usage in URLs, converts spaces to "-".
|
||||
### chomp
|
||||
Removes any trailing newline characters. Useful in a pipeline to remove newlines added by other processing (including `markdownify`).
|
||||
|
||||
e.g., `{{chomp "<p>Blockhead</p>\n"` → `"<p>Blockhead</p>"`
|
||||
|
||||
|
||||
### dateFormat
|
||||
Converts the textual representation of the datetime into the other form or returns it of Go `time.Time` type value. These are formatted with the layout string.
|
||||
|
||||
e.g. `{{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}` →"Wednesday, Jan 21, 2015"
|
||||
|
||||
|
||||
### highlight
|
||||
Take a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting/).
|
||||
|
||||
|
||||
### lower
|
||||
Convert all characters in string to lowercase.
|
||||
|
||||
e.g. `{{lower "BatMan"}}` → "batman"
|
||||
|
||||
|
||||
### 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 }}`
|
||||
|
||||
|
||||
### 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" }}
|
||||
|
||||
|
||||
### replace
|
||||
Replace all occurences of the search string with the replacement string.
|
||||
|
||||
e.g. `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman"
|
||||
|
||||
e.g. `<a href="/tags/{{ . | urlize }}">{{ . }}</a>`
|
||||
|
||||
### safeHTML
|
||||
Declares the provided string as a "safe" HTML document fragment
|
||||
|
|
@ -299,6 +344,7 @@ Example: Given a site-wide `config.toml` that contains this menu entry:
|
|||
* `<a {{ printf "href=%q" .URL | safeHTMLAttr }}>` ⇒ `<a href="irc://irc.freenode.net/#golang">` (Good!)
|
||||
-->
|
||||
|
||||
|
||||
### safeCSS
|
||||
Declares the provided string as a known "safe" CSS string
|
||||
so Go html/templates will not filter it.
|
||||
|
|
@ -317,6 +363,7 @@ Example: Given `style = "color: red;"` defined in the front matter of your `.md`
|
|||
Note: "ZgotmplZ" is a special value that indicates that unsafe content reached a
|
||||
CSS or URL context.
|
||||
|
||||
|
||||
### safeURL
|
||||
Declares the provided string as a "safe" URL or URL substring (see [RFC 3986][]).
|
||||
A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted
|
||||
|
|
@ -355,54 +402,30 @@ To fix this, add ` | safeURL` after `.URL` on the 3rd line, like this:
|
|||
With this change, we finally get `<li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>`
|
||||
as intended.
|
||||
|
||||
### 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"
|
||||
|
||||
### chomp
|
||||
Removes any trailing newline characters. Useful in a pipeline to remove newlines added by other processing (including `markdownify`).
|
||||
|
||||
e.g., `{{chomp "<p>Blockhead</p>\n"` → `"<p>Blockhead</p>"`
|
||||
|
||||
### trim
|
||||
Trim returns a slice of the string with all leading and trailing characters contained in cutset removed.
|
||||
|
||||
e.g. `{{ trim "++Batman--" "+-" }}` → "Batman"
|
||||
|
||||
### replace
|
||||
Replace all occurences of the search string with the replacement string.
|
||||
|
||||
e.g. `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman"
|
||||
### upper
|
||||
Convert all characters in string to uppercase.
|
||||
|
||||
### dateFormat
|
||||
Converts the textual representation of the datetime into the other form or returns it of Go `time.Time` type value. These are formatted with the layout string.
|
||||
e.g. `{{upper "BatMan"}}` → "BATMAN"
|
||||
|
||||
e.g. `{{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}` →"Wednesday, Jan 21, 2015"
|
||||
|
||||
### highlight
|
||||
Take a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting/).
|
||||
### urlize
|
||||
Takes a string and sanitizes it for usage in URLs, converts spaces to "-".
|
||||
|
||||
### 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. `<a href="/tags/{{ . | urlize }}">{{ . }}</a>`
|
||||
|
||||
e.g. {{ ref . "about.md" }}
|
||||
|
||||
## Advanced
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue