From 43c935a83da118442514f329feff5a12deb376e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Sun, 16 Jul 2017 18:19:30 +0200 Subject: [PATCH] Copy editing of the template func documentation --- content/functions/GetPage.md | 12 +++++-- content/functions/NumFmt.md | 2 +- content/functions/absurl.md | 2 +- content/functions/after.md | 4 +-- content/functions/apply.md | 6 ++-- content/functions/base64.md | 4 +-- content/functions/chomp.md | 2 +- content/functions/countrunes.md | 2 +- content/functions/countwords.md | 4 +-- content/functions/dict.md | 56 +++-------------------------- content/functions/echoparam.md | 2 -- content/functions/emojify.md | 8 ++--- content/functions/eq.md | 1 - content/functions/findRe.md | 25 +------------ content/functions/first.md | 3 +- content/functions/format.md | 4 +-- content/functions/getenv.md | 2 -- content/functions/hasPrefix.md | 2 -- content/functions/highlight.md | 2 -- content/functions/htmlEscape.md | 6 ++-- content/functions/htmlUnescape.md | 2 +- content/functions/humanize.md | 2 +- content/functions/i18n.md | 2 +- content/functions/imageConfig.md | 3 -- content/functions/in.md | 2 +- content/functions/index-function.md | 2 -- content/functions/int.md | 2 +- content/functions/intersect.md | 2 +- content/functions/ismenucurrent.md | 1 - content/functions/isset.md | 2 +- content/functions/jsonify.md | 2 -- content/functions/last.md | 3 +- content/functions/lower.md | 2 -- content/functions/markdownify.md | 1 - content/functions/math.md | 2 +- content/functions/md5.md | 2 +- content/functions/now.md | 4 +-- content/functions/plainify.md | 2 -- content/functions/pluralize.md | 2 -- content/functions/printf.md | 2 +- content/functions/readdir.md | 5 +-- content/functions/readfile.md | 7 ++-- content/functions/relLangURL.md | 3 +- content/functions/relurl.md | 3 +- content/functions/render.md | 2 +- content/functions/replace.md | 2 -- content/functions/replacere.md | 2 -- content/functions/safeCSS.md | 5 +-- content/functions/safeHTML.md | 4 +-- content/functions/safeHTMLAttr.md | 5 +-- content/functions/safeJS.md | 4 +-- content/functions/safeURL.md | 3 +- content/functions/seq.md | 2 +- content/functions/shuffle.md | 2 -- content/functions/singularize.md | 2 -- content/functions/slice.md | 4 +-- content/functions/slicestr.md | 2 -- content/functions/sort.md | 2 +- content/functions/split.md | 2 -- content/functions/string.md | 2 -- content/functions/substr.md | 2 -- content/functions/title.md | 2 -- content/functions/trim.md | 2 -- content/functions/truncate.md | 2 +- content/functions/uniq.md | 2 -- content/functions/unix.md | 36 ++++--------------- content/functions/upper.md | 2 +- content/functions/urlize.md | 2 -- 68 files changed, 72 insertions(+), 232 deletions(-) diff --git a/content/functions/GetPage.md b/content/functions/GetPage.md index c1966c784..05f454f83 100644 --- a/content/functions/GetPage.md +++ b/content/functions/GetPage.md @@ -1,6 +1,6 @@ --- title: .GetPage -description: Looks up the index page (`_index.md`) of a given `Kind` and `path`. +description: "Gets a `Page` of a given `Kind` and `path`." godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -20,7 +20,7 @@ aliases: [] Every `Page` has a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path. -`GetPage` looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages, such as the homepage or a section, from a template: +`GetPage` looks up a page of a given `Kind` and `path`. ``` {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }} @@ -28,7 +28,13 @@ Every `Page` has a `Kind` attribute that shows what kind of page it is. While th This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found. -The valid page kinds are: *home, section, taxonomy and taxonomyTerm.* +For a regular page: + +``` +{{ with .Site.GetPage "page" "blog" "my-post.md" }}{{ .Title }}{{ end }} +``` + +The valid page kinds are: *page, home, section, taxonomy and taxonomyTerm.* ## `.GetPage` Example diff --git a/content/functions/NumFmt.md b/content/functions/NumFmt.md index 4dfd2012b..6300c8e91 100644 --- a/content/functions/NumFmt.md +++ b/content/functions/NumFmt.md @@ -22,7 +22,7 @@ aliases: [] comments: --- -`lang.NumFmt` formats a number with a given precision using the requested `decimal`, `grouping`, and `negative` characters. The default options value is `- . ,`. +The default options value is `- . ,`. Numbers greater than or equal to 5 are rounded up. For example, if precision is set to `0`, `1.5` becomes `2`, and `1.4` becomes `1`. diff --git a/content/functions/absurl.md b/content/functions/absurl.md index 6b663fd9d..9c08ebf99 100644 --- a/content/functions/absurl.md +++ b/content/functions/absurl.md @@ -1,6 +1,6 @@ --- title: absURL -description: Given a string, prepends the full absolute URL according to position in file structure and the configured baseURL. +description: Creates an absolute URL based on the configured baseURL. godocref: date: 2017-02-01 publishdate: 2017-02-01 diff --git a/content/functions/after.md b/content/functions/after.md index 55041086e..13e7730f6 100644 --- a/content/functions/after.md +++ b/content/functions/after.md @@ -1,6 +1,6 @@ --- title: after -description: Slices an array to only the items after the Nth item. +description: "`after` slices an array to only the items after the Nth item." godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -18,7 +18,7 @@ deprecated: false aliases: [] --- -`after` slices an array to only the items after the Nth item. The following shows `after` being used in conjunction with the [`slice` function][slice]: +The following shows `after` being used in conjunction with the [`slice` function][slice]: ```html {{ $data := slice "one" "two" "three" "four" }} diff --git a/content/functions/apply.md b/content/functions/apply.md index c5a372e01..eb041f143 100644 --- a/content/functions/apply.md +++ b/content/functions/apply.md @@ -1,6 +1,6 @@ --- title: apply -description: Given a map, array, or slice, `description` returns a new slice with a function applied over it. +description: Given a map, array, or slice, `apply` returns a new slice with a function applied over it. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -19,9 +19,11 @@ draft: false aliases: [] --- +{{< todo >}} +{{< /todo >}} -Given a map, array, or slice, `apply` returns a new slice with a function applied over it. `apply` expects at least three parameters, depending on the function being applied. +`apply` expects at least three parameters, depending on the function being applied. 1. The first parameter is the sequence to operate on 2. The second parameter is the name of the function as a string, which must be the name of a valid [Hugo function][functions]. diff --git a/content/functions/base64.md b/content/functions/base64.md index 772f041c7..404366a4d 100644 --- a/content/functions/base64.md +++ b/content/functions/base64.md @@ -1,6 +1,6 @@ --- title: base64 -description: base64Encode and base64Decode let you easily decode content with a base64 encoding and vice versa through pipes. +description: "`base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes." godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -19,7 +19,7 @@ draft: false aliases: [] --- -`base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes. Let's take a look at an example: +An example: {{% code file="base64-input.html" %}} ```html diff --git a/content/functions/chomp.md b/content/functions/chomp.md index fdc6a5fd3..b8e6acee8 100644 --- a/content/functions/chomp.md +++ b/content/functions/chomp.md @@ -17,7 +17,7 @@ relatedfuncs: [truncate] deprecated: false --- -Removes any trailing newline characters. Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/markdownify/)). +Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/markdownify/)). ```golang {{chomp "

Blockhead

\n"}} → "

Blockhead

" diff --git a/content/functions/countrunes.md b/content/functions/countrunes.md index ae078cb40..f25dd3933 100644 --- a/content/functions/countrunes.md +++ b/content/functions/countrunes.md @@ -1,6 +1,6 @@ --- title: countrunes -description: Determines the number of runes in a string and excludes any whitespace. +description: Determines the number of runes in a string excluding any whitespace. godocref: date: 2017-02-01 publishdate: 2017-02-01 diff --git a/content/functions/countwords.md b/content/functions/countwords.md index b4ca1418a..ccca847ea 100644 --- a/content/functions/countwords.md +++ b/content/functions/countwords.md @@ -1,6 +1,6 @@ --- title: countwords -description: Counts the number of words in a string that has been passed to it. +description: Counts the number of words in a string. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -18,7 +18,7 @@ deprecated: false aliases: [/functions/countrunes/,/functions/countwords/] --- -`countwords` tries to convert the passed content to a string and counts each word in it. The template function works similar to the [.WordCount page variable][pagevars]. +The template function works similar to the [.WordCount page variable][pagevars]. ```html {{ "Hugo is a static site generator." | countwords }} diff --git a/content/functions/dict.md b/content/functions/dict.md index c04d9dc80..3c2086fea 100644 --- a/content/functions/dict.md +++ b/content/functions/dict.md @@ -1,6 +1,6 @@ --- title: dict -description: Creates a dictionary `(map[string, interface{})` that expects parameters added in a value:object fashion. +description: Creates a dictionary from a list of key and value pairs. godocref: workson: [] date: 2017-02-01 @@ -19,49 +19,12 @@ deprecated: false aliases: [] --- -`dict` creates a dictionary `(map[string, interface{})` that expects parameters added in a value:object fashion. +`dict` is especially useful for passing more than one value to a partial template. -Invalid combinations---e.g., keys that are not strings or an uneven number of parameters---will result in an exception being thrown. `dict` is especially useful for passing maps to partials being added to a template. - -For example, the following snippet passes a map with the keys "important, content" into "foo.html" - -{{% code file="dict-example.html" %}} -```html -{{$important := .Site.Params.SomethingImportant }} -{{range .Site.Params.Bar}} - {{partial "foo" (dict "content" . "important" $important)}} -{{end}} -``` -{{% /code %}} - -These keys can then be called in `foo.html` as follows: - -```golang -Important {{.important}} -{{.content}} -``` - -`dict` also allows you to create a map on the fly to pass into your [partial templates][partials]: - -{{% code file="dict-create-map.html" %}} -```golang -{{partial "foo" (dict "important" "Smiles" "content" "You should do more")}} -``` -{{% /code %}} ## Example: `dict` with Embedded SVGs -Let's suppose you want to pass values into embedded SVG icons on the fly in your template without having to change your CSS. The following is the XML for an "external link" SVG icon: - -{{% code file="layouts/partials/svgs/external-links.svg" copy="false" %}} -```xml - - - -``` -{{% /code %}} - -You can then call this [partial template][partials] using `{{ partial "svgs/external-links.svg" . }}`, but what if you want to pass specific values such as `fill` `height` and `width` into the icon? To allow for more flexibility, you can abstract these values into variables that you will later define when calling the partial template: +The partial below creates a SVG and expects `fill` `height` and `width` from the caller: {{% code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" %}} ```xml @@ -71,23 +34,14 @@ You can then call this [partial template][partials] using `{{ partial "svgs/exte ``` {{% /code %}} -You can then pass these values to customize the SVG by calling the partials with `dict`: +These values can be stored in one object with `dict` and passed to the partial: {{% code file="layouts/_default/list.html" %}} ```html -... -{{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" "10") }} -... +{{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" 10 "width" 20 ) }} ``` {{% /code %}} -The above partial will generate the following code when Hugo builds your site: - -```html - - - -``` [partials]: /templates/partials/ diff --git a/content/functions/echoparam.md b/content/functions/echoparam.md index 3c207097f..2c68280c6 100644 --- a/content/functions/echoparam.md +++ b/content/functions/echoparam.md @@ -20,8 +20,6 @@ aliases: [] --- -`echoParam` prints a parameter if it is set. - ``` {{ echoParam .Params "project_url" }} ``` diff --git a/content/functions/emojify.md b/content/functions/emojify.md index d43f21cb2..dd7af4ad7 100644 --- a/content/functions/emojify.md +++ b/content/functions/emojify.md @@ -17,15 +17,11 @@ relatedfuncs: [] deprecated: false --- -`emoji` runs a passed string through the Emoji emoticons processor. The result will be declared as "safe" to prevent Go templates from filtering it as unsafe HTML. +`emoji` runs a passed string through the Emoji emoticons processor. See the [Emoji cheat sheet][emojis] for available emoticons. -The `emojify` function can be called in your templates but not directly in your content files by default. To add emojis directly into content without further templating or shortcode considerations, set `enableEmoji` to `true` in your site's [configuration][config]. - -## Example - -When enabled, you can write emoji shorthand directly into your content files; e.g. I :heart: Hugo!: +The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration][config]. Then you can write emoji shorthand directly into your content files; e.g. I :heart: Hugo!: I :heart: Hugo! diff --git a/content/functions/eq.md b/content/functions/eq.md index ceadbe0a7..538e67fcd 100644 --- a/content/functions/eq.md +++ b/content/functions/eq.md @@ -19,7 +19,6 @@ deprecated: false aliases: [] --- -`eq` returns true if the parameters are equal. ``` {{ if eq .Section "blog" }}current{{ end }} diff --git a/content/functions/findRe.md b/content/functions/findRe.md index d5bc7ccd0..aa1b6d38d 100644 --- a/content/functions/findRe.md +++ b/content/functions/findRe.md @@ -19,7 +19,7 @@ aliases: [] --- -Returns a list of strings that match the regular expression. By default all matches will be included. The number of matches can be limitted with an optional third parameter. +By default all matches will be included. The number of matches can be limitted with an optional third parameter. The example below returns a list of all second level headers (`

`) in the content: @@ -40,29 +40,6 @@ Hugo uses Golang's [Regular Expression package](https://golang.org/pkg/regexp/), If you are just learning RegEx, or at least Golang's flavor, you can practice pattern matching in the browser at . {{% /note %}} - - [partials]: /templates/partials/ [`plainify`]: /functions/plainify/ diff --git a/content/functions/first.md b/content/functions/first.md index c365a6679..f6c2b63e1 100644 --- a/content/functions/first.md +++ b/content/functions/first.md @@ -1,7 +1,7 @@ --- title: first linktitle: first -description: Slices an array to only the first Nth elements. +description: "Slices an array to only the first _N_ elements." godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -19,7 +19,6 @@ deprecated: false aliases: [] --- -`first` slices an array to only the first _N_th elements. ```golang {{ range first 10 .Data.Pages }} diff --git a/content/functions/format.md b/content/functions/format.md index 5e5a86967..6e55dfa67 100644 --- a/content/functions/format.md +++ b/content/functions/format.md @@ -10,7 +10,7 @@ menu: docs: parent: "functions" #tags: [dates,time] -signature: ["Format FORMAT"] +signature: [".Format FORMAT"] workson: [times] hugoversion: relatedfuncs: [dateFormat,now,Unix,time] @@ -19,7 +19,7 @@ aliases: [] toc: true --- -`Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]: +`.Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]: * `.PublishDate` * `.Date` diff --git a/content/functions/getenv.md b/content/functions/getenv.md index 340e9b7c6..654bf0e06 100644 --- a/content/functions/getenv.md +++ b/content/functions/getenv.md @@ -18,8 +18,6 @@ deprecated: false aliases: [] --- -`getenv` returns the value of an environment variable. - Takes a string containing the name of the variable as input. Returns an empty string if the variable is not set, otherwise returns the value of the variable. diff --git a/content/functions/hasPrefix.md b/content/functions/hasPrefix.md index 79a3033ac..2e1514b49 100644 --- a/content/functions/hasPrefix.md +++ b/content/functions/hasPrefix.md @@ -19,6 +19,4 @@ deprecated: false aliases: [] --- -`hasPrefix` tests whether a string begins with prefix. - * `{{ hasPrefix "Hugo" "Hu" }}` → true diff --git a/content/functions/highlight.md b/content/functions/highlight.md index 12f0111a9..d6d8ba3e6 100644 --- a/content/functions/highlight.md +++ b/content/functions/highlight.md @@ -18,8 +18,6 @@ relatedfuncs: [] deprecated: false --- -`highlight` takes a string of code and a language and then uses Pygments to return the syntax highlighted code in HTML. - [`highlight` is used in Hugo's built-in `highlight` shortcode][highlight]. See [Installing Hugo][installpygments] for more information on Pygments or [Syntax Highlighting][syntax] for more options on how to add syntax highlighting to your code blocks with Hugo. diff --git a/content/functions/htmlEscape.md b/content/functions/htmlEscape.md index a3024194c..bbf31ce34 100644 --- a/content/functions/htmlEscape.md +++ b/content/functions/htmlEscape.md @@ -1,7 +1,7 @@ --- title: htmlEscape linktitle: -description: Returns the given string with the critical reserved HTML codes escaped. +description: Returns the given string with the reserved HTML codes escaped. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -19,9 +19,7 @@ deprecated: false aliases: [] --- -`htmlEscape` returns the given string with the critical reserved HTML codes escaped, such that `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. - -Bear in mind that, unless content is passed to `safeHTML`, output strings are escaped usually by the processor anyway. +In the result `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. ``` {{ htmlEscape "Hugo & Caddy > Wordpress & Apache" }} → "Hugo & Caddy > Wordpress & Apache" diff --git a/content/functions/htmlUnescape.md b/content/functions/htmlUnescape.md index b67ffa1c9..52f459129 100644 --- a/content/functions/htmlUnescape.md +++ b/content/functions/htmlUnescape.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`htmlUnescape` returns the given string with HTML escape codes un-escaped. This un-escapes more codes than `htmlEscape` escapes, including `#` codes and pre-UTF8 escapes for accented characters. It defers completely to the Go `html.UnescapeString` function, so functionality is consistent with that codebase. +`htmlUnescape` returns the given string with HTML escape codes un-escaped. Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal. diff --git a/content/functions/humanize.md b/content/functions/humanize.md index 8528a31c7..e59f532a7 100644 --- a/content/functions/humanize.md +++ b/content/functions/humanize.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`humanize` returns the humanized version of an argument with the first letter capitalized. If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended. +If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended. ``` diff --git a/content/functions/i18n.md b/content/functions/i18n.md index ac377ffd7..fb801db13 100644 --- a/content/functions/i18n.md +++ b/content/functions/i18n.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -This translates a piece of content based on your `i18n/en-US.yaml` (and friends) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository. +This translates a piece of content based on your `i18n/en-US.yaml` (and similar) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository. ```golang {{ i18n "translation_id" }} diff --git a/content/functions/imageConfig.md b/content/functions/imageConfig.md index 204c44b60..ebe55c5b8 100644 --- a/content/functions/imageConfig.md +++ b/content/functions/imageConfig.md @@ -1,5 +1,4 @@ --- -title: imageconfig linktitle: imageConfig description: Parses the image and returns the height, width, and color model. godocref: @@ -18,8 +17,6 @@ relatedfuncs: [] deprecated: false --- -`imageConfig` parses the image and returns the height, width, and color model. - ```golang {{ with (imageConfig "favicon.ico") }} favicon.ico: {{.Width}} x {{.Height}} diff --git a/content/functions/in.md b/content/functions/in.md index cde9567e9..4e6ac75b2 100644 --- a/content/functions/in.md +++ b/content/functions/in.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`in` checks if an element is in an array (or slice) and returns a corresponding boolean value. The elements supported are strings, integers and floats, although only float64 will match as expected. +The elements supported are strings, integers and floats, although only float64 will match as expected. In addition, `in` can also check if a substring exists in a string. diff --git a/content/functions/index-function.md b/content/functions/index-function.md index dcf45751d..e40fd2e0d 100644 --- a/content/functions/index-function.md +++ b/content/functions/index-function.md @@ -20,8 +20,6 @@ aliases: [/functions/index/] needsexample: true --- -`index` looks up the index(es) or key(s) of the data structure passed into it. - From the Godocs: > Returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array. diff --git a/content/functions/int.md b/content/functions/int.md index 049f7ea01..4ced74518 100644 --- a/content/functions/int.md +++ b/content/functions/int.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -Creates an integer (`int`) from the argument passed into the function. Useful for turning strings into numbers. +Useful for turning strings into numbers. ``` {{ int "123" }} → 123 diff --git a/content/functions/intersect.md b/content/functions/intersect.md index 8b21782a5..5c1ffce97 100644 --- a/content/functions/intersect.md +++ b/content/functions/intersect.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -Given two arrays (or slices), `intersect` returns the common elements. The elements supported are strings, integers, and floats (only float64). +The elements supported are strings, integers, and floats (only float64). A useful example of `intersect` functionality is a "related posts" block. `isset` allows us to create a list of links to other posts that have tags that intersect with the tags in the current post. diff --git a/content/functions/ismenucurrent.md b/content/functions/ismenucurrent.md index 9e546b07d..16061aa55 100644 --- a/content/functions/ismenucurrent.md +++ b/content/functions/ismenucurrent.md @@ -1,6 +1,5 @@ --- title: .IsMenuCurrent -linktitle: IsMenuCurrent description: godocref: date: 2017-02-01 diff --git a/content/functions/isset.md b/content/functions/isset.md index 275b6298d..340df49e2 100644 --- a/content/functions/isset.md +++ b/content/functions/isset.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`isset` returns true if the parameter is set. Takes either a slice, array, or channel and an index or a map and a key as input. +Takes either a slice, array, or channel and an index or a map and a key as input. ``` {{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }} diff --git a/content/functions/jsonify.md b/content/functions/jsonify.md index b33deffc5..34902b0c1 100644 --- a/content/functions/jsonify.md +++ b/content/functions/jsonify.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`jsonify` encodes a given object to JSON and converts it to HTML-safe content. - ``` {{ dict "title" .Title "content" .Plain | jsonify }} ``` diff --git a/content/functions/last.md b/content/functions/last.md index ff269db3f..7aae04200 100644 --- a/content/functions/last.md +++ b/content/functions/last.md @@ -1,7 +1,7 @@ --- title: last linktitle: last -description: Slices an array to only the last Nth elements. +description: "slices an array to only the last Nth elements." godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -21,7 +21,6 @@ draft: false aliases: [] --- -`last` slices an array to only the last Nth elements. ``` {{ range last 10 .Data.Pages }} diff --git a/content/functions/lower.md b/content/functions/lower.md index c7ec2f9cd..39bc214f3 100644 --- a/content/functions/lower.md +++ b/content/functions/lower.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`lower` converts all characters in the provided string to lowercase. - ``` {{lower "BatMan"}} → "batman" ``` diff --git a/content/functions/markdownify.md b/content/functions/markdownify.md index 324113fc0..f415cc1dc 100644 --- a/content/functions/markdownify.md +++ b/content/functions/markdownify.md @@ -19,7 +19,6 @@ deprecated: false aliases: [] --- -`markdownify` runs the provided string through the Markdown processor. The result will be declared as "safe" so Go/html templates do not filter it. ``` {{ .Title | markdownify }} diff --git a/content/functions/math.md b/content/functions/math.md index fb6484b01..38b36d42f 100644 --- a/content/functions/math.md +++ b/content/functions/math.md @@ -60,7 +60,7 @@ You can then concatenate the `image` value (string) with the path to your `image {{% /code %}} {{% note %}} -The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` is a more elegant and future-proofed approach to creating URLs than combining `.Site.BaseURL` with hard-coded strings—a templating style sometimes seen in older [Hugo themes](/themes). `absURL` works very well, for example, when creating `link` references to stylesheets and other metadata in your rendered site's ``. +The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` and its relative companion `relURL` is the recommended way to construct URLs in Hugo. {{% /note %}} [cards]: https://dev.twitter.com/cards/overview diff --git a/content/functions/md5.md b/content/functions/md5.md index 8d3c1bc60..4003436de 100644 --- a/content/functions/md5.md +++ b/content/functions/md5.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -The `md5` function hashes the given input and returns its MD5 checksum. + ```html {{ md5 "Hello world, gophers!" }} diff --git a/content/functions/now.md b/content/functions/now.md index d0e7edf00..ce2642dc4 100644 --- a/content/functions/now.md +++ b/content/functions/now.md @@ -1,7 +1,7 @@ --- title: now linktitle: now -description: Returns the current local time as a [`time.Time`] +description: Returns the current local time godocref: https://godoc.org/time#Time date: 2017-02-01 publishdate: 2017-02-01 @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`now` returns the current local time as a [`time.Time`](https://godoc.org/time#Time). +See [`time.Time`](https://godoc.org/time#Time). For example, building your site on June 24, 2017 with the following templating: diff --git a/content/functions/plainify.md b/content/functions/plainify.md index 2a0f84bff..1fd4b25a3 100644 --- a/content/functions/plainify.md +++ b/content/functions/plainify.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`plainify` strips any HTML and returns the plain text version of the provided string. - ``` {{ "BatMan" | plainify }} → "BatMan" ``` diff --git a/content/functions/pluralize.md b/content/functions/pluralize.md index 063f5666f..e6a18097d 100644 --- a/content/functions/pluralize.md +++ b/content/functions/pluralize.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`pluralize` will pluralize the given word according to a set of common English pluralization rules. - ``` {{ "cat" | pluralize }} → "cats" ``` diff --git a/content/functions/printf.md b/content/functions/printf.md index b9338d594..30cb6a15b 100644 --- a/content/functions/printf.md +++ b/content/functions/printf.md @@ -18,7 +18,7 @@ relatedfuncs: [] deprecated: false --- -`printf` formats a string using the standard `fmt.Sprintf` function. See [the go doc](https://golang.org/pkg/fmt/) for additional information. +See [the go doc](https://golang.org/pkg/fmt/) for additional information. ```golang {{ i18n ( printf "combined_%s" $var ) }} diff --git a/content/functions/readdir.md b/content/functions/readdir.md index b23831c37..5801e7aa1 100644 --- a/content/functions/readdir.md +++ b/content/functions/readdir.md @@ -1,6 +1,5 @@ --- -title: readdir -linktitle: readDir +title: readDir description: Gets a directory listing from a directory relative to the current working directory. godocref: date: 2017-02-01 @@ -19,8 +18,6 @@ deprecated: false aliases: [] --- -`readDir` gets a directory listing from a directory relative to the current project working directory. - If your current project working directory has a single file named `README.txt`: ``` diff --git a/content/functions/readfile.md b/content/functions/readfile.md index 727de13ea..9fb7ab251 100644 --- a/content/functions/readfile.md +++ b/content/functions/readfile.md @@ -1,7 +1,6 @@ --- -title: readfile -linktitle: readFile -description: Reads a file from disk relative to the current project working directory and converts it into a string. +title: readFile +description: Reads a file from disk relative to the current project working directory and returns a string. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -19,7 +18,7 @@ deprecated: false aliases: [] --- -`readFile` reads a file from disk and converts it into a string. Note that the filename must be relative to the current project working directory. +Note that the filename must be relative to the current project working directory. So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`: diff --git a/content/functions/relLangURL.md b/content/functions/relLangURL.md index 1d1b11fac..ef1cbae22 100644 --- a/content/functions/relLangURL.md +++ b/content/functions/relLangURL.md @@ -1,6 +1,5 @@ --- -title: rellangurl -# linktitle: relLangURL +title: relLangURL description: Adds the relative URL with correct language prefix according to site configuration for multilingual. godocref: date: 2017-02-01 diff --git a/content/functions/relurl.md b/content/functions/relurl.md index 6a7e60152..0d01a8ab5 100644 --- a/content/functions/relurl.md +++ b/content/functions/relurl.md @@ -1,6 +1,5 @@ --- -title: relurl -# linktitle: relURL +title: relURL description: Given a string, prepends the relative URL according to a page's position in the project directory structure. godocref: date: 2017-02-01 diff --git a/content/functions/render.md b/content/functions/render.md index df89aa641..dac1d4c40 100644 --- a/content/functions/render.md +++ b/content/functions/render.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`Render` takes a view to apply when rendering content. The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views). +The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views). This function is only available when applied to a single piece of content within a [list context][]. diff --git a/content/functions/replace.md b/content/functions/replace.md index 31243d725..a3f7369c3 100644 --- a/content/functions/replace.md +++ b/content/functions/replace.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`replace` replaces all occurrences of the search string with the replacement string: - ``` `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman" diff --git a/content/functions/replacere.md b/content/functions/replacere.md index 4e8f2c194..5ecf1680b 100644 --- a/content/functions/replacere.md +++ b/content/functions/replacere.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -Replaces all occurrences of a regular expression with the replacement pattern. - ```golang {{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io" {{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io" diff --git a/content/functions/safeCSS.md b/content/functions/safeCSS.md index 9b762ee30..345813937 100644 --- a/content/functions/safeCSS.md +++ b/content/functions/safeCSS.md @@ -1,6 +1,5 @@ --- -title: safecss -# linktitle: safeCSS +title: safeCSS description: Declares the provided string as a known "safe" CSS string. godocref: https://golang.org/src/html/template/content.go?s=919:929#L15 date: 2017-02-01 @@ -19,8 +18,6 @@ deprecated: false aliases: [] --- -`safeCSS` declares the provided string as a known "safe" CSS string so that Go html/templates will not filter it as unsafe. - In this context, *safe* means CSS content that matches any of the following: 1. The CSS3 stylesheet production, such as `p { color: purple }`. diff --git a/content/functions/safeHTML.md b/content/functions/safeHTML.md index 1c8205d7a..1dc4ce553 100644 --- a/content/functions/safeHTML.md +++ b/content/functions/safeHTML.md @@ -18,9 +18,7 @@ relatedfuncs: [] deprecated: false --- -`safeHTML` declares the provided string as a "safe" HTML document fragment -so Go html/template will not filter it. It should not be used -for HTML from a third-party, or HTML with unclosed tags or comments. +It should not be used for HTML from a third-party, or HTML with unclosed tags or comments. Given a site-wide [`config.toml`][config] with the following `copyright` value: diff --git a/content/functions/safeHTMLAttr.md b/content/functions/safeHTMLAttr.md index fb76c94e2..293efb1c7 100644 --- a/content/functions/safeHTMLAttr.md +++ b/content/functions/safeHTMLAttr.md @@ -1,7 +1,7 @@ --- title: safeHTMLAttr # linktitle: safeHTMLAttr -description: Declares the provided string as a "safe" HTML attribute. +description: Declares the provided string as a safe HTML attribute. godocref: https://golang.org/src/html/template/content.go?s=1661:1676#L33 date: 2017-02-01 publishdate: 2017-02-01 @@ -19,9 +19,6 @@ deprecated: false aliases: [] --- -`safeHTMLAttr` declares the provided string as a "safe" HTML attribute -from a trusted source (e.g., ` dir="ltr"`) to prevent Go html/template from filtering it as unsafe. - Example: Given a site-wide `config.toml` that contains this menu entry: ```toml diff --git a/content/functions/safeJS.md b/content/functions/safeJS.md index fe75ab004..4d4beb622 100644 --- a/content/functions/safeJS.md +++ b/content/functions/safeJS.md @@ -1,7 +1,7 @@ --- title: safeJS # linktitle: -description: Declares the provided string as a known "safe" JavaScript string. +description: Declares the provided string as a known safe JavaScript string. godocref: https://golang.org/src/html/template/content.go?s=2548:2557#L51 date: 2017-02-01 publishdate: 2017-02-01 @@ -20,8 +20,6 @@ draft: false aliases: [] --- -`safeJs` declares the provided string as a known "safe" Javascript string so that Go html/templates will not escape it as unsafe. - In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`). Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo:bar() }\n['foo']()`, which is both a valid expression and a valid program with a very different meaning. diff --git a/content/functions/safeURL.md b/content/functions/safeURL.md index bac073369..71fad028b 100644 --- a/content/functions/safeURL.md +++ b/content/functions/safeURL.md @@ -1,6 +1,5 @@ --- -title: safeurl -# linktitle: safeURL +title: safeURL description: Declares the provided string as a safe URL or URL substring. godocref: https://golang.org/pkg/html/template/#HTMLEscape date: 2017-02-01 diff --git a/content/functions/seq.md b/content/functions/seq.md index 83adb7ea2..f1085326a 100644 --- a/content/functions/seq.md +++ b/content/functions/seq.md @@ -20,7 +20,7 @@ draft: false aliases: [] --- -`seq` creates a sequence of integers. It's named and used in the model of [GNU's seq][]. +It's named and used in the model of [GNU's seq][]. ``` 3 → 1, 2, 3 diff --git a/content/functions/shuffle.md b/content/functions/shuffle.md index 6b032c3b1..b2ba14571 100644 --- a/content/functions/shuffle.md +++ b/content/functions/shuffle.md @@ -20,8 +20,6 @@ draft: false aliases: [] --- -`shuffle` returns a random permutation of a given array or slice: - {{% code file="shuffle-input.html" %}} ```html diff --git a/content/functions/singularize.md b/content/functions/singularize.md index 8bbd5e86c..6214cc914 100644 --- a/content/functions/singularize.md +++ b/content/functions/singularize.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`singularize` converts a word according to a set of common English singularization rules. - `{{ "cats" | singularize }}` → "cat" See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names. diff --git a/content/functions/slice.md b/content/functions/slice.md index ff9ff41eb..0d5182ba7 100644 --- a/content/functions/slice.md +++ b/content/functions/slice.md @@ -1,7 +1,7 @@ --- title: slice # linktitle: slice -description: Creates an array (`[]interface{}``) of all passed arguments. +description: Creates a alice (array) of all passed arguments. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -21,8 +21,6 @@ aliases: [] toc: false --- -`slice` allows you to create an array (`[]interface{}`) of all arguments that you pass to this function. - One use case is the concatenation of elements in combination with the [`delimit` function][]: {{% code file="slice.html" %}} diff --git a/content/functions/slicestr.md b/content/functions/slicestr.md index f8e1b4a1d..38f4ba086 100644 --- a/content/functions/slicestr.md +++ b/content/functions/slicestr.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -Slicing in `slicestr` is done by specifying a half-open range with two indices; i.e., a `start` and and `end`. - For example, 1 and 4 creates a slice including elements 1 through 3. The `end` index can be omitted; it defaults to the string's length. diff --git a/content/functions/sort.md b/content/functions/sort.md index 84acbbf59..42f5d1e3c 100644 --- a/content/functions/sort.md +++ b/content/functions/sort.md @@ -19,7 +19,7 @@ deprecated: false aliases: [] --- -`sort` sorts maps, arrays, and slices and returns a sorted slice. A sorted array of map values will be returned with the keys eliminated. There are two optional arguments: `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order as its default behavior. +A sorted array of map values will be returned with the keys eliminated. There are two optional arguments: `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order as its default behavior. ```toml +++ diff --git a/content/functions/split.md b/content/functions/split.md index af2cfd6c8..cc95aedd4 100644 --- a/content/functions/split.md +++ b/content/functions/split.md @@ -19,8 +19,6 @@ deprecated: false aliases: [] --- -`split` splits a string into substrings separated by a delimiter. - * `{{split "tag1,tag2,tag3" "," }}` → ["tag1" "tag2" "tag3"] diff --git a/content/functions/string.md b/content/functions/string.md index d3296e689..963647ae3 100644 --- a/content/functions/string.md +++ b/content/functions/string.md @@ -19,7 +19,5 @@ deprecated: false aliases: [] --- -`string` creates a string from the argument passed to the function. - * `{{string "BatMan"}}` → "BatMan" diff --git a/content/functions/substr.md b/content/functions/substr.md index fb4f15b93..089698bb0 100644 --- a/content/functions/substr.md +++ b/content/functions/substr.md @@ -19,8 +19,6 @@ relatedfuncs: [] deprecated: false --- -`substr` extracts parts of a string, beginning at the character at the specified position, and returns the specified number of characters. - It normally takes two parameters: `start` and `length`. It can also take one parameter: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. To extract characters from the end of the string, use a negative start number. diff --git a/content/functions/title.md b/content/functions/title.md index 4cb42fe6e..3ecf1ac34 100644 --- a/content/functions/title.md +++ b/content/functions/title.md @@ -20,8 +20,6 @@ aliases: [] --- -`title` converts all characters in the provided string to title case. - ``` {{title "BatMan"}}` → "Batman" ``` diff --git a/content/functions/trim.md b/content/functions/trim.md index 809594e36..448b5e23f 100644 --- a/content/functions/trim.md +++ b/content/functions/trim.md @@ -18,8 +18,6 @@ relatedfuncs: [] deprecated: false --- -`trim` returns a slice of the string with all leading and trailing characters contained in cutset removed. - ``` {{ trim "++Batman--" "+-" }} → "Batman" ``` diff --git a/content/functions/truncate.md b/content/functions/truncate.md index bdff81db4..911133fa1 100644 --- a/content/functions/truncate.md +++ b/content/functions/truncate.md @@ -18,7 +18,7 @@ relatedfuncs: [] deprecated: false --- -Truncate a text to a max length without cutting words or leaving unclosed HTML tags. Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings: +Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings: ``` {{ "Keep my HTML" | safeHTML | truncate 10 }}` → Keep my …` diff --git a/content/functions/uniq.md b/content/functions/uniq.md index 3a63976f9..467daeb18 100644 --- a/content/functions/uniq.md +++ b/content/functions/uniq.md @@ -20,8 +20,6 @@ aliases: [] needsexamples: false --- -The `uniq` function takes in a slice or array and returns a slice with subsequent duplicate elements removed: - ```html {{ uniq (slice 1 2 3 2) }} {{ slice 1 2 3 2 | uniq }} diff --git a/content/functions/unix.md b/content/functions/unix.md index faa45e443..2477d5437 100644 --- a/content/functions/unix.md +++ b/content/functions/unix.md @@ -1,7 +1,7 @@ --- title: .Unix draft: false -description: Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC. +description: .Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC. godocref: https://golang.org/search?q=Unix#Functions date: 2017-02-01 publishdate: 2017-02-01 @@ -11,7 +11,7 @@ categories: [functions] menu: docs: parent: "functions" -signature: ["Unix"] +signature: [".Unix"] workson: [times] hugoversion: relatedfuncs: [Format,dateFormat,now,time] @@ -19,44 +19,20 @@ deprecated: false aliases: [] --- -`Unix` returns t as a Unix time; i.e., the number of seconds elapsed since January 1, 1970 UTC. +## Example: Time Passed Since Last Modification -## `Unix` Example 1: Show Only Upcoming Events - -The following assumes you have a content section called `events` (i.e., `content/events/*.md`). The following [partial template][] allows you to only list events that haven't occurred yet. - -{{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}} -```html -

Upcoming Events

-
    -{{ range where .Data.Pages.ByDate "Section" "events" }} - {{ if ge .Date.Unix .Now.Unix }} -
  • {{ .Type | title }} — - {{ .Title }} - on - {{ .Date.Format "2 January at 3:04pm" }} - at {{ .Params.place }} -
    • - {{ end }} -{{ end }} -
-``` -{{% /code %}} - -## `Unix` Example 2: Time Passed Since Last Modification - -This very simple one-liner uses `Unix` with `Now` to calculate the amount of time that has passed between the `.LastMod` for the current page and the last build of the current page. +This very simple one-liner uses `now.Unix` to calculate the amount of time that has passed between the `.LastMod` for the current page and the last build of the current page. {{% code file="time-passed.html" %}} ```golang -{{ div (sub .Now.Unix .Lastmod.Unix) 86400 }} +{{ div (sub now.Unix .Lastmod.Unix) 86400 }} ``` {{% /code %}} Since both values are integers, they can be subtracted and then divided by the number of seconds in a day (i.e., `60 * 60 * 24 == 86400`). {{% note %}} -Hugo's output is *static*. In example 2, a month-old page published on a Hugo site that only publishes monthly could easily misrepresented the last update as *yesterday* rather than 30 days ago. +Hugo's output is *static*. For the example above to be realistic, the site needs to be built every day. {{% /note %}} diff --git a/content/functions/upper.md b/content/functions/upper.md index cef0dc386..f12044663 100644 --- a/content/functions/upper.md +++ b/content/functions/upper.md @@ -21,7 +21,7 @@ draft: false aliases: [] --- -`upper` converts all characters in string to uppercase. Note that `upper` can be applied in your templates in more than one way: +Note that `upper` can be applied in your templates in more than one way: ``` {{ upper "BatMan" }} → "BATMAN" diff --git a/content/functions/urlize.md b/content/functions/urlize.md index 7acce49c0..3f57b0211 100644 --- a/content/functions/urlize.md +++ b/content/functions/urlize.md @@ -18,8 +18,6 @@ workson: [] relatedfuncs: [] --- -`urlize` takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens ("`-`"). - The following examples pull from a content file with the following front matter: {{% code file="content/blog/greatest-city.md" copy="false"%}}