ref: 6b50c8fb82d4dafcdfa83ae3c120abb274dd2092
parent: 9de78aab3ff8208b0d92ea530e6ab1d49d51ee91
author: mdhender <[email protected]>
date: Sat Apr 4 00:12:11 EDT 2015
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
--- a/docs/content/templates/functions.md
+++ b/docs/content/templates/functions.md
@@ -26,17 +26,36 @@
## 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.
-e.g. `{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}`+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
+
+
### 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 @@
{{ if eq .Section "blog" }}current{{ end }}+
### first
Slices an array to only the first X elements.
@@ -55,78 +75,46 @@
{{ .Render "summary" }} {{ end }}-### where
-Filters an array to only elements containing a matching value for a given field.
-Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+### 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.
- {{ range where .Data.Pages "Section" "post" }}- {{ .Content }}- {{ end }}+ {{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }}-It can be used with dot chaining second argument to refer a nested element of a value.
+or
-e.g.
+ {{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}- // Front matter on some pages
- +++
- series: golang
- +++
- {{ range where .Site.Recent "Params.series" "golang" }}- {{ .Content }}- {{ 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).
-It can also be used with an operator like `!=`, `>=`, `in` etc. Without an operator (like above), `where` compares a given field with a matching value in a way like `=` is specified.
+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.
- {{ range where .Data.Pages "Section" "!=" "post" }}- {{ .Content }}+ <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>
-Following operators are now available
-- `=`, `==`, `eq`: True if a given field value equals a matching value
-- `!=`, `<>`, `ne`: True if a given field value doesn't equal a matching value
-- `>=`, `ge`: True if a given field value is greater than or equal to a matching value
-- `>`, `gt`: True if a given field value is greater than a matching value
-- `<=`, `le`: True if a given field value is lesser than or equal to a matching value
-- `<`, `lt`: True if a given field value is lesser than a matching value
-- `in`: True if a given field value is included in a matching value. A matching value must be an array or a slice
-- `not in`: True if a given field value isn't included in a matching value. A matching value must be an array or a slice
+### 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.
-*`where` and `first` can be stacked, e.g.:*
+e.g. `{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}`- {{ 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](/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.
@@ -173,37 +161,57 @@
// 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.
+### where
+Filters an array to only elements containing a matching value for a given field.
+
+Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+
e.g.
- {{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }}+ {{ range where .Data.Pages "Section" "post" }}+ {{ .Content }}+ {{ end }}-or
+It can be used with dot chaining second argument to refer a nested element of a value.
- {{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}+e.g.
-### 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).
+ // Front matter on some pages
+ +++
+ series: golang
+ +++
-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.
+ {{ range where .Site.Recent "Params.series" "golang" }}+ {{ .Content }}+ {{ end }}+It can also be used with an operator like `!=`, `>=`, `in` etc. Without an operator (like above), `where` compares a given field with a matching value in a way like `=` is specified.
+
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 }}+ {{ range where .Data.Pages "Section" "!=" "post" }}+ {{ .Content }} {{ end }}- </ul>
+Following operators are now available
+- `=`, `==`, `eq`: True if a given field value equals a matching value
+- `!=`, `<>`, `ne`: True if a given field value doesn't equal a matching value
+- `>=`, `ge`: True if a given field value is greater than or equal to a matching value
+- `>`, `gt`: True if a given field value is greater than a matching value
+- `<=`, `le`: True if a given field value is lesser than or equal to a matching value
+- `<`, `lt`: True if a given field value is lesser than a matching value
+- `in`: True if a given field value is included in a matching value. A matching value must be an array or a slice
+- `not in`: True if a given field value isn't included in a matching value. A matching value must be an array or a slice
+
+*`where` and `first` can be stacked, e.g.:*
+
+ {{ range first 5 (where .Data.Pages "Section" "post") }}+ {{ .Content }}+ {{ end }}+
+
## Math
<table class="table table-bordered">
@@ -223,18 +231,6 @@
</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>
<td><code>{{div 6 3}}</code> → 2</td>@@ -251,6 +247,19 @@
<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>
@@ -257,11 +266,47 @@
## 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. `<a href="/tags/{{ . | urlize }}">{{ . }}</a>`+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"+
+
### safeHTML
Declares the provided string as a "safe" HTML document fragment
so Go html/template will not filter it. It should not be used
@@ -299,6 +344,7 @@
* `<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 @@
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 @@
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