From 6b50c8fb82d4dafcdfa83ae3c120abb274dd2092 Mon Sep 17 00:00:00 2001 From: mdhender Date: Sat, 4 Apr 2015 04:12:11 -0500 Subject: [PATCH] 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 --- docs/content/templates/functions.md | 265 +++++++++++++++------------- 1 file changed, 144 insertions(+), 121 deletions(-) diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md index c02841f4..6dbc58bf 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,77 +75,45 @@ e.g. {{ .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 }} - {{ end }} - -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 }} + -### 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 +### 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. - // Example with the optional "last" parameter - Tags: {{ delimit .Params.tags ", " " and " }} +e.g. `{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}` - // 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,35 +161,55 @@ e.g. // 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. - ## 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 -- 2.30.2