diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md index c02841f4b..6dbc58bf7 100644 --- a/docs/content/templates/functions.md +++ b/docs/content/templates/functions.md @@ -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. + + + + +### 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. - - - ## Math @@ -222,18 +230,6 @@ e.g. {{add 1 2}} → 3 - -sub -Subtracts two integers. -{{sub 3 2}} → 1 - - - -mul -Multiplies two integers. -{{mul 2 3}} → 6 - - div Divides two integers. @@ -251,16 +247,65 @@ e.g. Boolean of modulus of two integers. true if modulus is 0. {{modBool 15 3}} → true + + +mul +Multiplies two integers. +{{mul 2 3}} → 6 + + + +sub +Subtracts two integers. +{{sub 3 2}} → 1 + + ## 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 "

Blockhead

\n"` → `"

Blockhead

"` + + +### 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. `{{ . }}` ### 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: * `` ⇒ `` (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 `
  • IRC: #golang at freenode
    • ` 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 "

    Blockhead

    \n"` → `"

    Blockhead

    "` ### 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. `{{ . }}` -e.g. {{ ref . "about.md" }} ## Advanced