diff --git a/content/en/functions/GetPage.md b/content/en/functions/GetPage.md index 17d2bd972..43e2717ee 100644 --- a/content/en/functions/GetPage.md +++ b/content/en/functions/GetPage.md @@ -1,13 +1,15 @@ --- title: .GetPage -description: "Gets a `Page` of a given `path`." +description: Gets a `Page` of a given `path`. categories: [functions] menu: docs: parent: functions -keywords: [sections,lists,indexes] -signature: [".GetPage PATH"] -relatedfuncs: [] +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .GetPage PATH --- `.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page. diff --git a/content/en/functions/RenderString.md b/content/en/functions/RenderString.md index 47c914ca4..60edc5673 100644 --- a/content/en/functions/RenderString.md +++ b/content/en/functions/RenderString.md @@ -1,12 +1,15 @@ --- title: .RenderString -description: "Renders markup to HTML." +description: sRenders markup to HTML. categories: [functions] menu: docs: parent: functions -keywords: [markdown,goldmark,render] -signature: [".RenderString MARKUP"] +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .RenderString MARKUP [OPTIONS] --- `.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options). diff --git a/content/en/functions/abslangurl.md b/content/en/functions/abslangurl.md index 2e1996f7e..bc60050b0 100644 --- a/content/en/functions/abslangurl.md +++ b/content/en/functions/abslangurl.md @@ -5,8 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls, multilingual,i18n] -signature: ["absLangURL INPUT"] +keywords: [] +namespace: urls +relatedFuncs: + - urls.AbsLangURL + - urls.AbsURL + - urls.RelLangURL + - urls.RelURL +signature: [absLangURL INPUT] --- Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: diff --git a/content/en/functions/absurl.md b/content/en/functions/absurl.md index efea2df75..089dd5c2f 100644 --- a/content/en/functions/absurl.md +++ b/content/en/functions/absurl.md @@ -5,8 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls] -signature: ["absURL INPUT"] +keywords: [] +namespace: urls +relatedFuncs: + - urls.AbsLangURL + - urls.AbsURL + - urls.RelLangURL + - urls.RelURL +signature: [absURL INPUT] --- With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on: @@ -34,7 +40,7 @@ With `baseURL = https://example.org/docs/` {{ absURL "style.css" }} → https://example.org/docs/style.css ``` -### Input begins with a slash +#### Input begins with a slash If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`. diff --git a/content/en/functions/adddate.md b/content/en/functions/adddate.md index cae270fb8..95ecc69a7 100644 --- a/content/en/functions/adddate.md +++ b/content/en/functions/adddate.md @@ -5,9 +5,10 @@ categories: [functions] menu: docs: parent: functions -keywords: [dates,time] -signature: [".AddDate YEARS MONTHS DAYS"] -relatedfuncs: [now] +keywords: [] +namespace: +relatedFuncs: [] +signature: [.AddDate YEARS MONTHS DAYS] --- ```go-html-template diff --git a/content/en/functions/after.md b/content/en/functions/after.md index 85aa6104d..3bf293a03 100644 --- a/content/en/functions/after.md +++ b/content/en/functions/after.md @@ -1,13 +1,17 @@ --- title: after -description: "`after` slices an array to only the items after the Nth item." +description: Slices an array to the items after the Nth item. categories: [functions] menu: docs: parent: functions -keywords: [iteration] -signature: ["after INDEX COLLECTION"] -relatedfuncs: [last,first,seq] +keywords: [] +namespace: collections +relatedFuncs: + - collections.After + - collections.First + - collections.Last +signature: [after INDEX COLLECTION] --- The following shows `after` being used in conjunction with the [`slice` function][slice]: diff --git a/content/en/functions/anchorize.md b/content/en/functions/anchorize.md index 91d6b4fe7..1248c0b25 100644 --- a/content/en/functions/anchorize.md +++ b/content/en/functions/anchorize.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [markdown,strings] -signature: ["anchorize INPUT"] -relatedfuncs: [humanize] +keywords: [] +namespace: urls +relatedFuncs: + - urls.Anchorize + - urls.URLize +signature: + - urls.Anchorize INPUT + - anchorize INPUT --- If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark). diff --git a/content/en/functions/append.md b/content/en/functions/append.md index e734eac2b..6bbd9a6f6 100644 --- a/content/en/functions/append.md +++ b/content/en/functions/append.md @@ -5,9 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections] -signature: ["COLLECTION | append ELEMENT [ELEMENT]...", "COLLECTION | append COLLECTION"] -relatedfuncs: [last,first,where,slice] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Append + - collections.Merge +signature: + - COLLECTION | collections.Append ELEMENT [ELEMENT]... + - COLLECTION | collections.Append COLLECTION + - COLLECTION | append ELEMENT [ELEMENT]... + - COLLECTION | append COLLECTION --- This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below. diff --git a/content/en/functions/apply.md b/content/en/functions/apply.md index c507a35bf..95d8b6231 100644 --- a/content/en/functions/apply.md +++ b/content/en/functions/apply.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [advanced] -signature: ["apply COLLECTION FUNCTION [PARAM...]"] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice +signature: + - collections.Apply COLLECTION FUNCTION [PARAM...] + - apply COLLECTION FUNCTION [PARAM...] --- `apply` expects at least three arguments, depending on the function being applied. diff --git a/content/en/functions/base64.md b/content/en/functions/base64.md deleted file mode 100644 index a6de64bd9..000000000 --- a/content/en/functions/base64.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: base64 -description: "`base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes." -categories: [functions] -menu: - docs: - parent: functions -keywords: [] -relatedfuncs: [] -signature: ["base64Decode INPUT", "base64Encode INPUT"] ---- - -```go-html-template -{{ "Hugo" | base64Encode }} → "SHVnbw==" -{{ "SHVnbw==" | base64Decode }} → "Hugo" -``` - -## `base64` with APIs - -Using base64 to decode and encode becomes really powerful if we have to handle -responses from APIs. - -```go-html-template -{{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }} -{{ $resp.content | base64Decode | markdownify }} -``` - -The response of the GitHub API contains the base64-encoded version of the [README.md](https://github.com/gohugoio/hugo/blob/master/README.md) in the Hugo repository. Now we can decode it and parse the Markdown. The final output will look similar to the rendered version on GitHub. diff --git a/content/en/functions/base64Decode.md b/content/en/functions/base64Decode.md new file mode 100644 index 000000000..05e950e1e --- /dev/null +++ b/content/en/functions/base64Decode.md @@ -0,0 +1,43 @@ +--- +title: base64Decode +description: Returns the base64 decoding of the given content. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: encoding +relatedFuncs: + - encoding.Base64Decode + - encoding.Base64Encode +signature: + - encoding.Base64Decode INPUT + - base64Decode INPUT +--- + +```go-html-template +{{ "SHVnbw==" | base64Decode }} → "Hugo" +``` + +Use the `base64Decode` function to decode responses from APIs. For example, the result of this call to GitHub's API contains the base64-encoded representation of the repository's README file: + +```text +https://api.github.com/repos/gohugoio/hugo/readme +``` + +To retrieve and render the content: + +```go-html-template +{{ $u := "https://api.github.com/repos/gohugoio/hugo/readme" }} +{{ with resources.GetRemote $u }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ with . | transform.Unmarshal }} + {{ .content | base64Decode | markdownify }} + {{ end }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $u }} +{{ end }} +``` diff --git a/content/en/functions/base64Encode.md b/content/en/functions/base64Encode.md new file mode 100644 index 000000000..3a0cbecff --- /dev/null +++ b/content/en/functions/base64Encode.md @@ -0,0 +1,21 @@ +--- +title: base64Encode +description: Returns the base64 decoding of the given content. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: encoding +relatedFuncs: + - encoding.Base64Decode + - encoding.Base64Encode +signature: + - encoding.Base64Encode INPUT + - base64Encode INPUT +aliases: ['/functions/base64'] +--- + +```go-html-template +{{ "Hugo" | base64Encode }} → "SHVnbw==" +``` diff --git a/content/en/functions/chomp.md b/content/en/functions/chomp.md index 861e7ecc4..012c58b6d 100644 --- a/content/en/functions/chomp.md +++ b/content/en/functions/chomp.md @@ -6,11 +6,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [trim] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix signature: - - "chomp INPUT" - - "strings.Chomp INPUT" -relatedfuncs: [truncate] + - chomp STRING + - strings.Chomp STRING --- Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/markdownify/)). diff --git a/content/en/functions/collections.Reverse.md b/content/en/functions/collections.Reverse.md new file mode 100644 index 000000000..5ca7e6bf8 --- /dev/null +++ b/content/en/functions/collections.Reverse.md @@ -0,0 +1,24 @@ +--- +title: collections.Reverse +description: Reverses the order of a collection. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: collections +relatedFuncs: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice +signature: + - collections.Reverse COLLECTION +--- + + +```go-html-template +{{ slice 1 3 2 1 | uniq }} → [1 3 2] +``` diff --git a/content/en/functions/complement.md b/content/en/functions/complement.md index e4cf01e77..2c93b68a6 100644 --- a/content/en/functions/complement.md +++ b/content/en/functions/complement.md @@ -5,11 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections] +namespace: collections +relatedFuncs: + - collections.Complement + - collections.Intersect + - collections.SymDiff + - collections.Union signature: -- "complement COLLECTION [COLLECTION]..." -- "collections.Complement COLLECTION [COLLECTION]..." -relatedfuncs: [intersect,symdiff,union] + - collections.Complement COLLECTION [COLLECTION]... + - complement COLLECTION [COLLECTION]... --- To find the elements within `$c3` that do not exist in `$c1` or `$c2`: diff --git a/content/en/functions/cond.md b/content/en/functions/cond.md index 9bd0a0e2b..62f2cfdb9 100644 --- a/content/en/functions/cond.md +++ b/content/en/functions/cond.md @@ -2,12 +2,17 @@ title: cond description: Returns one of two arguments depending on the value of the control argument. categories: [functions] -keywords: [conditional, ternary] menu: docs: parent: functions -signature: [cond CONTROL ARG1 ARG2] -relatedfuncs: [default] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Conditional + - compare.Default +signature: + - compare.Conditional CONTROL ARG1 ARG2 + - cond CONTROL ARG1 ARG2 --- The CONTROL argument is a boolean value that indicates whether the function should return ARG1 or ARG2. If CONTROL is `true`, the function returns ARG1. Otherwise, the function returns ARG2. diff --git a/content/en/functions/countrunes.md b/content/en/functions/countrunes.md index 0d89af857..fc2545604 100644 --- a/content/en/functions/countrunes.md +++ b/content/en/functions/countrunes.md @@ -5,11 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [counting, word count] +keywords: [] +namespace: strings +relatedFuncs: + - len + - strings.Count + - strings.CountRunes + - strings.CountWords + - strings.RuneCount signature: - - "countrunes INPUT" - - "strings.CountRunes INPUT" -relatedfuncs: [] + - strings.CountRunes INPUT + - countrunes INPUT --- In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages. diff --git a/content/en/functions/countwords.md b/content/en/functions/countwords.md index 33dcbcaef..a7b06debe 100644 --- a/content/en/functions/countwords.md +++ b/content/en/functions/countwords.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [counting, word count] -signature: ["countwords INPUT"] -relatedfuncs: [countrunes] +keywords: [] +namespace: strings +relatedFuncs: + - len + - strings.Count + - strings.CountRunes + - strings.CountWords + - strings.RuneCount +signature: + - strings.CountWords INPUT + - countwords INPUT --- The template function works similar to the [.WordCount page variable][pagevars]. diff --git a/content/en/functions/crypto.FNV32a.md b/content/en/functions/crypto.FNV32a.md index 9bcfff26f..41d663e17 100644 --- a/content/en/functions/crypto.FNV32a.md +++ b/content/en/functions/crypto.FNV32a.md @@ -5,10 +5,20 @@ categories: [functions] menu: docs: parent: functions -keywords: [crypto hash FNV32 Fowler-Noll-Vo] -signature: ["crypto.FNV32a STRING"] +keywords: [] +namespace: crypto +relatedFuncs: + - crypto.FNV32a + - crypto.HMAC + - crypto.MD5 + - crypto.SHA1 + - crypto.SHA256 +signature: + - crypto.FNV32a STRING --- This function calculates the 32 bit [FNV1a hash](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash) of a given string according to the [specification](https://datatracker.ietf.org/doc/html/draft-eastlake-fnv-12): - {{ crypto.FNV32a "Hello world" }} → 1498229191 +```go-html-template +{{ crypto.FNV32a "Hello world" }} → 1498229191 +``` diff --git a/content/en/functions/dateformat.md b/content/en/functions/dateformat.md index ddfb61296..226c903a7 100644 --- a/content/en/functions/dateformat.md +++ b/content/en/functions/dateformat.md @@ -5,11 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [dates,time,strings] +keywords: [] +namespace: time +relatedFuncs: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration signature: - - "time.Format LAYOUT INPUT" - - "dateFormat LAYOUT INPUT" -relatedfuncs: [Format,now,Unix,time] + - time.Format LAYOUT INPUT + - dateFormat LAYOUT INPUT --- `time.Format` (alias `dateFormat`) converts either a `time.Time` object (e.g. `.Date`) or a timestamp string `INPUT` into the format specified by the `LAYOUT` string. diff --git a/content/en/functions/default.md b/content/en/functions/default.md index b0e517366..98cf55fbf 100644 --- a/content/en/functions/default.md +++ b/content/en/functions/default.md @@ -1,15 +1,18 @@ --- title: default description: Allows setting a default value that can be returned if a first value is not set. -qref: "Returns a default value if a value is not set when checked." -keywords: [defaults] categories: [functions] menu: docs: parent: functions -toc: -signature: ["default DEFAULT INPUT"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Conditional + - compare.Default +signature: + - compare.Default DEFAULT INPUT + - default DEFAULT INPUT --- `default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on the data type: diff --git a/content/en/functions/delimit.md b/content/en/functions/delimit.md index cc0293526..5d6cb42df 100644 --- a/content/en/functions/delimit.md +++ b/content/en/functions/delimit.md @@ -5,9 +5,19 @@ categories: [functions] menu: docs: parent: functions -keywords: [iteration] -signature: ["delimit COLLECTION DELIMITER [LAST]"] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice + - strings.Split +signature: + - collections.Delimit COLLECTION DELIMITER [LAST] + - delimit COLLECTION DELIMITER [LAST] --- Delimit a slice: diff --git a/content/en/functions/dict.md b/content/en/functions/dict.md index 0fc2c530b..50584caaf 100644 --- a/content/en/functions/dict.md +++ b/content/en/functions/dict.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections] -signature: ["dict KEY VALUE [KEY VALUE]..."] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Dictionary + - collections.Group + - collections.Index + - collections.IsSet + - collections.Where +signature: + - collections.Dictionary KEY VALUE [KEY VALUE]... + - dict KEY VALUE [KEY VALUE]... --- `dict` is especially useful for passing more than one value to a partial template. diff --git a/content/en/functions/duration.md b/content/en/functions/duration.md index 4dc365ae5..985c6c83f 100644 --- a/content/en/functions/duration.md +++ b/content/en/functions/duration.md @@ -5,8 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [time duration] -signature: ["duration TIME_UNIT DURATION_NUMBER"] +keywords: [] +namespace: time +relatedFuncs: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration +signature: + - time.Duration TIME_UNIT DURATION_NUMBER + - duration TIME_UNIT DURATION_NUMBER --- `time.Duration` converts a given number into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. E.g. you can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value: diff --git a/content/en/functions/echoparam.md b/content/en/functions/echoparam.md index 7b80e1439..853aadc8b 100644 --- a/content/en/functions/echoparam.md +++ b/content/en/functions/echoparam.md @@ -6,11 +6,33 @@ menu: docs: parent: functions keywords: [] -signature: ["echoParam MAP KEY"] -relatedfuncs: [] +namespace: collections +relatedFuncs: [] +signature: + - collections.EchoParam COLLECTION KEY + - echoParam COLLECTION KEY --- +For example, consider this site configuration: + +{{< code-toggle file=hugo copy=false >}} +[params.footer] +poweredBy = 'Hugo' +{{< /code-toggle >}} + +To print the value of `poweredBy`: ```go-html-template -{{ echoParam .Params "project_url" }} +{{ echoParam site.Params.footer "poweredby" }} → Hugo +``` + +{{% note %}} +When using the `echoParam` function you must reference the key using lower case. See the previous example. + +The `echoParam` function may be deprecated in a future release. Instead, use either of the constructs below. +{{% /note %}} + +```go-html-template +{{ site.Params.footer.poweredBy }} → Hugo +{{ index site.Params.footer "poweredBy" }} → Hugo ``` diff --git a/content/en/functions/emojify.md b/content/en/functions/emojify.md index beded710a..e1753cb20 100644 --- a/content/en/functions/emojify.md +++ b/content/en/functions/emojify.md @@ -5,9 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings,emojis] -signature: ["emojify INPUT"] -relatedfuncs: [] +keywords: [] +namespace: transform +relatedFuncs: [] +signature: + - transform.Emojify INPUT + - emojify INPUT --- `emojify` runs a passed string through the Emoji emoticons processor. diff --git a/content/en/functions/eq.md b/content/en/functions/eq.md index d10539e49..02691d0a3 100644 --- a/content/en/functions/eq.md +++ b/content/en/functions/eq.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["eq ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Eq ARG1 ARG2 [ARG...] + - eq ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/errorf.md b/content/en/functions/errorf.md index 8caaf0554..5cb60554b 100644 --- a/content/en/functions/errorf.md +++ b/content/en/functions/errorf.md @@ -1,45 +1,31 @@ --- -title: errorf and warnf -description: Log ERROR or WARNING from the templates. +title: errorf +description: Log an ERROR from a template. categories: [functions] menu: docs: parent: functions -keywords: [strings, log, error] -signature: ["errorf FORMAT INPUT"] -relatedfuncs: [printf] +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Errorf + - fmt.Erroridf + - fmt.Warnf +signature: + - fmt.Errorf FORMAT [INPUT] + - errorf FORMAT [INPUT] --- -`errorf` or `warnf` will evaluate a format string, then output the result to the ERROR or WARNING log (and only once per error message to avoid flooding the log). +The documentation for [Go's fmt package] describes the structure and content of the format string. -Any ERROR will also cause the build to fail (the `hugo` command will `exit -1`). - -Both functions return an empty string, so the messages are only printed to the console. +Like the [`printf`] function, the `errorf` function evaluates the format string. It then prints the result to the ERROR log and fails the build. Hugo prints each unique message once to avoid flooding the log with duplicate errors. ```go-html-template -{{ errorf "Failed to handle page %q" .Path }} +{{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }} ``` -```go-html-template -{{ warnf "You should update the shortcodes in %q" .Path }} -``` +Use the [`erroridf`] function to allow optional supression of specific errors. -Note that `errorf`, `erroridf`, and `warnf` support all the formatting verbs of the [fmt](https://pkg.go.dev/fmt) package. - -## Suppress errors - -Sometimes it may make sense to let the user suppress an ERROR and make the build succeed. - -You can do this by using the `erroridf` function. This functions takes an error ID as the first argument. - -```go-html-template -{{ erroridf "my-custom-error" "You should consider fixing this." }} -``` - -This will produce: - -``` -ERROR 2021/06/07 17:47:38 You should consider fixing this. -If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site configuration: -ignoreErrors = ["my-custom-error"] -``` +[`erroridf`]: /functions/erroridf/ +[`printf`]: /functions/printf/ +[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/content/en/functions/erroridf.md b/content/en/functions/erroridf.md new file mode 100644 index 000000000..fd6118694 --- /dev/null +++ b/content/en/functions/erroridf.md @@ -0,0 +1,46 @@ +--- +title: erroridf +description: Log a suppressable ERROR from a template. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Errorf + - fmt.Erroridf + - fmt.Warnf +signature: + - fmt.Erroridf ID FORMAT [INPUT] + - erroridf ID FORMAT [INPUT] +--- + +The documentation for [Go's fmt package] describes the structure and content of the format string. + +Like the [`errorf`] function, the `erroridf` function evaluates the format string, prints the result to the ERROR log, then fails the build. Hugo prints each unique message once to avoid flooding the log with duplicate errors. + +Unlike the `errorf` function, you may surpress errors logged by the `erroridf` function by adding the messsage ID to the `ignoreErrors` array in your site configuration. + +This template code: + +```go-html-template +{{ erroridf "error-42" "You should consider fixing this." }} +``` + +Produces this console log: + +```text +ERROR You should consider fixing this. +If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config: +ignoreErrors = ["error-42"] +``` + +To suppress this message: + +{{< code-toggle file=hugo copy=false >}} +ignoreErrors = ["error-42"] +{{< /code-toggle >}} + +[`errorf`]: /functions/errorf/ +[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/content/en/functions/fileExists.md b/content/en/functions/fileExists.md index f7b5c37e0..2f658a83d 100644 --- a/content/en/functions/fileExists.md +++ b/content/en/functions/fileExists.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -signature: ["os.FileExists PATH","fileExists PATH"] -relatedfuncs: ['os.ReadDir','os.ReadFile','os.Stat'] +namespace: os +relatedFuncs: + - os.FileExists + - os.Getenv + - os.ReadDir + - os.ReadFile + - os.Stat +signature: + - os.FileExists PATH + - fileExists PATH --- + The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. With this directory structure: diff --git a/content/en/functions/findRe.md b/content/en/functions/findRe.md index 104db0f27..c5d26c3a4 100644 --- a/content/en/functions/findRe.md +++ b/content/en/functions/findRe.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [regex] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FindRE + - strings.FindRESubmatch + - strings.Replace + - strings.ReplaceRE signature: - - "findRE PATTERN INPUT [LIMIT]" - - "strings.FindRE PATTERN INPUT [LIMIT]" -relatedfuncs: [findRESubmatch, replaceRE] + - strings.FindRE PATTERN INPUT [LIMIT] + - findRE PATTERN INPUT [LIMIT] --- By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. diff --git a/content/en/functions/findresubmatch.md b/content/en/functions/findresubmatch.md index f51ccdb97..9a374ea4e 100644 --- a/content/en/functions/findresubmatch.md +++ b/content/en/functions/findresubmatch.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [regex] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FindRE + - strings.FindRESubmatch + - strings.Replace + - strings.ReplaceRE signature: - - "findRESubmatch PATTERN INPUT [LIMIT]" - - "strings.FindRESubmatch PATTERN INPUT [LIMIT]" -relatedfuncs: [findRE, replaceRE] + - strings.FindRESubmatch PATTERN INPUT [LIMIT + - findRESubmatch PATTERN INPUT [LIMIT] --- By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match. diff --git a/content/en/functions/first.md b/content/en/functions/first.md index 118c9c504..8ab08dafa 100644 --- a/content/en/functions/first.md +++ b/content/en/functions/first.md @@ -1,13 +1,17 @@ --- title: first -description: "Slices an array to only the first _N_ elements." +description: Slices an array to the first N elements. categories: [functions] menu: docs: parent: functions -keywords: [iteration] -signature: ["first LIMIT COLLECTION"] -relatedfuncs: [after,last] +keywords: [] +namespace: collections +relatedFuncs: + - collections.After + - collections.First + - collections.Last +signature: [first LIMIT COLLECTION] --- `first` works in a similar manner to the [`limit` keyword in diff --git a/content/en/functions/float.md b/content/en/functions/float.md index e95b3ae5f..f5a409839 100644 --- a/content/en/functions/float.md +++ b/content/en/functions/float.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [cast,strings,floats] -signature: ["float INPUT"] -relatedfuncs: [] +keywords: [] +namespace: cast +relatedFuncs: + - cast.ToFloat + - cast.ToInt + - cast.ToString +signature: + - cast.ToFloat INPUT + - float INPUT --- With a decimal (base 10) input: diff --git a/content/en/functions/format.md b/content/en/functions/format.md index d30f0bdf2..14410e8dc 100644 --- a/content/en/functions/format.md +++ b/content/en/functions/format.md @@ -5,9 +5,11 @@ categories: [functions] menu: docs: parent: functions -keywords: [dates,time] -signature: [".Format FORMAT"] -relatedfuncs: [dateFormat,now,Unix,time] +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .Format FORMAT toc: true --- diff --git a/content/en/functions/ge.md b/content/en/functions/ge.md index e59b0f9c9..adb7ea785 100644 --- a/content/en/functions/ge.md +++ b/content/en/functions/ge.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["ge ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Ge ARG1 ARG2 [ARG...] + - ge ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/get.md b/content/en/functions/get.md index 561a794c7..20bd3ba5a 100644 --- a/content/en/functions/get.md +++ b/content/en/functions/get.md @@ -5,9 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [shortcodes] -signature: [".Get INDEX", ".Get KEY"] -relatedfuncs: [] +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .Get INDEX + - .Get KEY --- `.Get` is specifically used when creating your own [shortcode template][sc], to access the [positional and named](/templates/shortcode-templates/#positional-vs-named-parameters) parameters passed to it. When used with a numeric INDEX, it queries positional parameters (starting with 0). With a string KEY, it queries named parameters. diff --git a/content/en/functions/getenv.md b/content/en/functions/getenv.md index daeeb6532..b3422dc72 100644 --- a/content/en/functions/getenv.md +++ b/content/en/functions/getenv.md @@ -6,9 +6,18 @@ menu: docs: parent: functions keywords: [] -signature: ["os.Getenv VARIABLE", "getenv VARIABLE"] -relatedfuncs: [] +namespace: os +relatedFuncs: + - os.FileExists + - os.Getenv + - os.ReadDir + - os.ReadFile + - os.Stat +signature: + - os.Getenv VARIABLE + - getenv VARIABLE --- + Examples: ```go-html-template diff --git a/content/en/functions/group.md b/content/en/functions/group.md index 617dcbb34..bd7f71091 100644 --- a/content/en/functions/group.md +++ b/content/en/functions/group.md @@ -5,8 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections] -signature: ["PAGES | group KEY"] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Dictionary + - collections.Group + - collections.Index + - collections.IsSet + - collections.Where +signature: + - PAGES | collections.Group KEY + - PAGES | group KEY --- {{< code file="layouts/partials/groups.html" >}} @@ -14,16 +23,16 @@ signature: ["PAGES | group KEY"] {{ $old := .Site.RegularPages | last 10 | group "Old" }} {{ $groups := slice $new $old }} {{ range $groups }} -

{{ .Key }}{{/* Prints "New", "Old" */}}

- {{ end }} {{< /code >}} -The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can even be [paginated](/templates/pagination/#list-paginator-pages). +The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages). diff --git a/content/en/functions/gt.md b/content/en/functions/gt.md index dac1986fe..e147efcd9 100644 --- a/content/en/functions/gt.md +++ b/content/en/functions/gt.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["gt ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Gt ARG1 ARG2 [ARG...] + - gt ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/hasmenucurrent.md b/content/en/functions/hasmenucurrent.md index 8605cf34e..822a3d2ee 100644 --- a/content/en/functions/hasmenucurrent.md +++ b/content/en/functions/hasmenucurrent.md @@ -5,9 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [menus] -signature: ["PAGE.HasMenuCurrent MENU MENUENTRY"] -relatedfuncs: ["IsMenuCurrent"] +keywords: [] +namespace: +relatedFuncs: + - .HasMenuCurrent + - .IsMenuCurrent +signature: + - PAGE.HasMenuCurrent MENU MENUENTRY --- `.HasMenuCurrent` is a method in `Page` object returning a _boolean_ value. It diff --git a/content/en/functions/highlight.md b/content/en/functions/highlight.md index f91c1f562..0d0fbd98a 100644 --- a/content/en/functions/highlight.md +++ b/content/en/functions/highlight.md @@ -5,11 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [highlighting,code blocks,syntax] -signature: ["transform.Highlight INPUT LANG [OPTIONS]","highlight INPUT LANG [OPTIONS]"] -relatedfuncs: [] +keywords: [] +namespace: transform +relatedFuncs: [] +signature: + - transform.Highlight INPUT LANG [OPTIONS] + - highlight INPUT LANG [OPTIONS] toc: true --- + The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles. ## Arguments diff --git a/content/en/functions/hmac.md b/content/en/functions/hmac.md index 3b9675a0b..4abd9f7b8 100644 --- a/content/en/functions/hmac.md +++ b/content/en/functions/hmac.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [hmac,checksum] -signature: ["crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]","hmac HASH_TYPE KEY MESSAGE [ENCODING]" ] -relatedfuncs: [hmac] +keywords: [] +namespace: crypto +relatedFuncs: + - crypto.FNV32a + - crypto.HMAC + - crypto.MD5 + - crypto.SHA1 + - crypto.SHA256 +signature: + - crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING] + - hmac HASH_TYPE KEY MESSAGE [ENCODING] --- Set the `HASH_TYPE` argument to `md5`, `sha1`, `sha256`, or `sha512`. diff --git a/content/en/functions/htmlEscape.md b/content/en/functions/htmlEscape.md index 0ee8fa4d2..cc7648068 100644 --- a/content/en/functions/htmlEscape.md +++ b/content/en/functions/htmlEscape.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings, html] -signature: ["htmlEscape INPUT"] -relatedfuncs: [htmlUnescape] +keywords: [] +namespace: transform +relatedFuncs: + - transform.HTMLEscape + - transform.HTMLUnescape +signature: + - transform.HTMLEscape INPUT + - htmlEscape INPUT --- In the result `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. diff --git a/content/en/functions/htmlUnescape.md b/content/en/functions/htmlUnescape.md index e4646b680..c59248444 100644 --- a/content/en/functions/htmlUnescape.md +++ b/content/en/functions/htmlUnescape.md @@ -6,8 +6,13 @@ menu: docs: parent: functions keywords: [] -signature: ["htmlUnescape INPUT"] -relatedfuncs: [htmlEscape] +namespace: transform +relatedFuncs: + - transform.HTMLEscape + - transform.HTMLUnescape +signature: + - transform.HTMLUnescape INPUT + - htmlUnescape INPUT --- `htmlUnescape` returns the given string with HTML escape codes un-escaped. diff --git a/content/en/functions/hugo.md b/content/en/functions/hugo.md index 78d658c66..a60a016f7 100644 --- a/content/en/functions/hugo.md +++ b/content/en/functions/hugo.md @@ -6,9 +6,10 @@ categories: [functions] menu: docs: parent: functions -toc: -signature: ["hugo"] -relatedfuncs: [] +keywords: [] +namespace: global +relatedFuncs: [] +signature: [hugo] --- `hugo` returns an instance that contains the following functions: diff --git a/content/en/functions/humanize.md b/content/en/functions/humanize.md index 6cbd85837..7611a6715 100644 --- a/content/en/functions/humanize.md +++ b/content/en/functions/humanize.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings,casing] -signature: ["humanize INPUT"] -relatedfuncs: [anchorize] +keywords: [] +namespace: inflect +relatedFuncs: + - inflect.Humanize + - inflect.Pluralize + - inflect.Singularize +signature: + - inflect.Humanize INPUT + - humanize INPUT --- 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/en/functions/i18n.md b/content/en/functions/i18n.md index 13f3a6f8f..bdea419a5 100644 --- a/content/en/functions/i18n.md +++ b/content/en/functions/i18n.md @@ -1,49 +1,125 @@ --- title: i18n -description: Translates a piece of content based on your i18n configuration files. +description: Translates a string using the translation tables in the i18n directory. categories: [functions] menu: docs: parent: functions -keywords: [internationalization,i18n,multilingual] +keywords: [] +namespace: lang +relatedFuncs: [] signature: - - "i18n KEY" - - "T KEY" - - "lang.Translate KEY" -relatedfuncs: [] + - lang.Translate KEY [CONTEXT] + - i18n KEY [CONTEXT] + - T KEY [CONTEXT] --- -This translates a piece of content based on your `i18n/en-US.toml` 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. +Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory. -```go-html-template -{{ i18n "translation_id" }} +``` +i18n/ +├── en.toml +└── pl.toml ``` -{{% note %}} -`T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`. -{{% /note %}} +The translation tables can contain both: -### Query a flexible translation with variables +- Simple translations +- Translations with pluralization -Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`: +The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language. -```go-html-template -{{ i18n "wordCount" . }} -``` +[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html -The function will pass the `.` context to the `"wordCount"` id: +The English translation table: -{{< code-toggle file="i18n/en-US" >}} -[wordCount] -other = "This article has {{ .WordCount }} words." +{{< code-toggle file=i18n/en copy=false >}} +# simple translations +privacy = 'privacy' +security = 'security' + +# translations with pluralization +[day] +one = 'day' +other = 'days' + +[day_with_count] +one = '{{ . }} day' +other = '{{ . }} days' {{< /code-toggle >}} -Assume `.WordCount` in the context has value is 101. The result will be: +The Polish translation table: -``` -This article has 101 words. +{{< code-toggle file=i18n/pl copy=false >}} +# simple translations +privacy = 'prywatność' +security = 'bezpieczeństwo' + +# translations with pluralization +[day] +one = 'miesiąc' +few = 'miesiące' +many = 'miesięcy' +other = 'miesiąca' + +[day_with_count] +one = '{{ . }} miesiąc' +few = '{{ . }} miesiące' +many = '{{ . }} miesięcy' +other = '{{ . }} miesiąca' +{{< /code-toggle >}} + +{{% note %}} +The examples below use the `T` alias for brevity. +{{% /note %}} + +When viewing the English language site: + +```go-html-template +{{ T "privacy" }} --> privacy +{{ T "security" }} --> security + +{{ T "day" 0 }} --> days +{{ T "day" 1 }} --> day +{{ T "day" 2 }} --> days +{{ T "day" 5 }} --> days + +{{ T "day_with_count" 0 }} --> 0 days +{{ T "day_with_count" 1 }} --> 1 day +{{ T "day_with_count" 2 }} --> 2 days +{{ T "day_with_count" 5 }} --> 5 days +```` + +When viewing the Polish language site: + +```go-html-template +{{ T "privacy" }} --> prywatność +{{ T "security" }} --> bezpieczeństwo + +{{ T "day" 0 }} --> miesięcy +{{ T "day" 1 }} --> miesiąc +{{ T "day" 2 }} --> miesiące +{{ T "day" 5 }} --> miesięcy + +{{ T "day_with_count" 0 }} --> 0 miesięcy +{{ T "day_with_count" 1 }} --> 1 miesiąc +{{ T "day_with_count" 2 }} --> 2 miesiące +{{ T "day_with_count" 5 }} --> 5 miesięcy ``` -For more information about string translations, see [Translation of Strings in Multilingual Mode][multistrings]. +In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, creating a `count` key to control pluralization. -[multistrings]: /content-management/multilingual/#translation-of-strings +Translation table: + +{{< code-toggle file=i18n/en copy=false >}} +[age] +one = '{{ .name }} is {{ .count }} year old.' +other = '{{ .name }} is {{ .count }} years old.' +{{< /code-toggle >}} + +Template: + +```go-html-template +{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old. +{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old. +``` diff --git a/content/en/functions/in.md b/content/en/functions/in.md index 1baf7ce90..6fdabc07f 100644 --- a/content/en/functions/in.md +++ b/content/en/functions/in.md @@ -1,13 +1,21 @@ --- title: in -description: Checks if an element is in an array or slice--or a substring in a string---and returns a boolean. +description: Checks if an element is in an array or slice---or a substring in a string---and returns a boolean. categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["in SET ITEM"] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix +signature: + - collections.In SET ITEM + - in SET ITEM --- The elements supported are strings, integers and floats, although only float64 will match as expected. diff --git a/content/en/functions/index-function.md b/content/en/functions/index-function.md index b2193c9c5..1a9fd9dba 100644 --- a/content/en/functions/index-function.md +++ b/content/en/functions/index-function.md @@ -6,8 +6,19 @@ menu: docs: parent: functions keywords: [] -signature: ["index COLLECTION INDEXES", "index COLLECTION KEYS"] -relatedfuncs: [] +namespace: collections +relatedFuncs: + - collections.Dictionary + - collections.EchoParam + - collections.Group + - collections.Index + - collections.IsSet + - collections.Where +signature: + - collections.Index COLLECTION INDEXES + - collections.Index COLLECTION KEYS + - index COLLECTION INDEXES + - index COLLECTION KEYS aliases: [/functions/index/] --- diff --git a/content/en/functions/int.md b/content/en/functions/int.md index 1d91c9fdd..feab3da09 100644 --- a/content/en/functions/int.md +++ b/content/en/functions/int.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [cast,strings,integers] -signature: ["int INPUT"] -relatedfuncs: [] +keywords: [] +namespace: cast +relatedFuncs: + - cast.ToFloat + - cast.ToInt + - cast.ToString +signature: + - cast.ToInt INPUT + - int INPUT --- With a decimal (base 10) input: diff --git a/content/en/functions/intersect.md b/content/en/functions/intersect.md index 9c3ed6292..0816fd1b6 100644 --- a/content/en/functions/intersect.md +++ b/content/en/functions/intersect.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections,intersect,union,complement,symdiff] -signature: ["intersect SET1 SET2"] -relatedfuncs: [] +namespace: collections +relatedFuncs: + - collections.Complement + - collections.Intersect + - collections.SymDiff + - collections.Union +signature: + - collections.Intersect SET1 SET2 + - intersect SET1 SET2 --- A useful example is to use it as `AND` filters when combined with where: diff --git a/content/en/functions/ismenucurrent.md b/content/en/functions/ismenucurrent.md index a27a174b6..4ec3daca7 100644 --- a/content/en/functions/ismenucurrent.md +++ b/content/en/functions/ismenucurrent.md @@ -5,9 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [menus] -signature: ["PAGE.IsMenuCurrent MENU MENUENTRY"] -relatedfuncs: ["HasMenuCurrent"] +keywords: [] +namespace: +relatedFuncs: + - .HasMenuCurrent + - .IsMenuCurrent +signature: + - PAGE.IsMenuCurrent MENU MENUENTRY --- `.IsMenuCurrent` is a method in `Page` object returning a _boolean_ value. It diff --git a/content/en/functions/isset.md b/content/en/functions/isset.md index 0a8de7367..469ce9b02 100644 --- a/content/en/functions/isset.md +++ b/content/en/functions/isset.md @@ -1,22 +1,50 @@ --- title: isset -description: Returns true if the parameter is set. +description: Returns true if the key exists within the collection. categories: [functions] menu: docs: parent: functions keywords: [] -signature: ["isset COLLECTION INDEX", "isset COLLECTION KEY"] -relatedfuncs: [] +namespace: collections +relatedFuncs: + - collections.Dictionary + - collections.Group + - collections.Index + - collections.IsSet + - collections.Where +signature: + - collections.IsSet COLLECTION KEY + - isset COLLECTION KEY --- -Takes either a slice, array, or channel and an index or a map and a key as input. +For example, consider this site configuration: + +{{< code-toggle file=hugo copy=false >}} +[params] +showHeroImage = false +{{< /code-toggle >}} + +It the value of `showHeroImage` is `true`, we can detect that it exists using either `if` or `with`: ```go-html-template -{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }} +{{ if site.Params.showHeroImage }} + {{ site.Params.showHeroImage }} → true +{{ end }} + +{{ with site.Params.showHeroImage }} + {{ . }} → true +{{ end }} +``` + +But if the value of `showHeroImage` is `false`, we can't use either `if` or `with` to detect its existence. In this case, you must use the `isset` function: + +```go-html-template +{{ if isset site.Params "showheroimage" }} +

The showHeroImage parameter is set to {{ site.Params.showHeroImage }}.

+{{ end }} ``` {{% note %}} -All site-level configuration keys are stored as lower case. Therefore, a `myParam` key-value set in your [site configuration file](/getting-started/configuration/) needs to be accessed with `{{ if isset .Site.Params "myparam" }}` and *not* with `{{ if isset .Site.Params "myParam" }}`. Note that you can still access the same configuration key with `.Site.Params.myParam` *or* `.Site.Params.myparam`, for example, when using [`with`](/functions/with). -This restriction also applies when accessing page-level front matter keys from within [shortcodes](/content-management/shortcodes/). +When using the `isset` function you must reference the key using lower case. See the previous example. {{% /note %}} diff --git a/content/en/functions/jsonify.md b/content/en/functions/jsonify.md index e94fb7cd4..6ce4556ec 100644 --- a/content/en/functions/jsonify.md +++ b/content/en/functions/jsonify.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings,json] -signature: ["jsonify INPUT", "jsonify OPTIONS INPUT"] -relatedfuncs: [plainify] +keywords: [] +namespace: encoding +relatedFuncs: + - encoding.Jsonify + - transform.Remarshal + - transform.Unmarshal +signature: + - encoding.Jsonify INPUT + - encoding.Jsonify OPTIONS INPUT + - jsonify INPUT + - jsonify OPTIONS INPUT --- To customize the printing of the JSON, pass a map of options as the first diff --git a/content/en/functions/lang.Merge.md b/content/en/functions/lang.Merge.md index ab3e61940..ebd771c65 100644 --- a/content/en/functions/lang.Merge.md +++ b/content/en/functions/lang.Merge.md @@ -1,14 +1,15 @@ --- title: lang.Merge -description: "Merge missing translations from other languages." +description: Merge missing translations from other languages. categories: [functions] -keywords: [multilingual] menu: docs: parent: functions -signature: ["lang.Merge FROM TO"] -relatedfuncs: [] -comments: +keywords: [] +namespace: lang +relatedFuncs: [] +signature: + - lang.Merge FROM TO --- As an example: diff --git a/content/en/functions/lang.md b/content/en/functions/lang.md index af55c92bf..d114d8558 100644 --- a/content/en/functions/lang.md +++ b/content/en/functions/lang.md @@ -1,13 +1,14 @@ --- title: lang package: lang -description: "TODO.." +description: "Functions in the language namespace." categories: [functions] -keywords: [numbers] menu: docs: parent: functions -signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS [DELIMITER]]"] +keywords: [] +relatedFuncs: [] +signature: [] aliases: ['/functions/numfmt/'] type: 'template-func' --- diff --git a/content/en/functions/last.md b/content/en/functions/last.md index 72e6a4c0d..c646c32c2 100644 --- a/content/en/functions/last.md +++ b/content/en/functions/last.md @@ -1,14 +1,17 @@ --- title: last -description: "slices an array to only the last Nth elements." -keywords: [] +description: Slices an array to the last N elements. categories: [functions] menu: docs: parent: functions -toc: -signature: ["last INDEX COLLECTION"] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.After + - collections.First + - collections.Last +signature: [last INDEX COLLECTION] --- ```go-html-template diff --git a/content/en/functions/le.md b/content/en/functions/le.md index 1953bfae0..ec09e0111 100644 --- a/content/en/functions/le.md +++ b/content/en/functions/le.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["le ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Le ARG1 ARG2 [ARG...] + - le ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/len.md b/content/en/functions/len.md index cdf3cf405..6be348104 100644 --- a/content/en/functions/len.md +++ b/content/en/functions/len.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [length] +keywords: [] +namespace: text/template +relatedFuncs: + - len + - strings.Count + - strings.CountRunes + - strings.CountWords + - strings.RuneCount signature: ["len INPUT"] -relatedfuncs: [] --- With a string: diff --git a/content/en/functions/lower.md b/content/en/functions/lower.md index 9accf999e..04d60b334 100644 --- a/content/en/functions/lower.md +++ b/content/en/functions/lower.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings,casing] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FirstUpper + - strings.Title + - strings.ToLower + - strings.ToUpper signature: - - "lower INPUT" - - "strings.ToLower INPUT" -relatedfuncs: [] + - strings.ToLower INPUT + - lower INPUT --- diff --git a/content/en/functions/lt.md b/content/en/functions/lt.md index 9a8651574..b083e75da 100644 --- a/content/en/functions/lt.md +++ b/content/en/functions/lt.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["lt ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +keywords: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Lt ARG1 ARG2 [ARG...] + - lt ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/markdownify.md b/content/en/functions/markdownify.md index 9f1f3329e..103d1703f 100644 --- a/content/en/functions/markdownify.md +++ b/content/en/functions/markdownify.md @@ -1,13 +1,16 @@ --- title: markdownify description: Renders markdown to HTML. -keywords: [markdown,content] categories: [functions] menu: docs: parent: functions -signature: ["markdownify INPUT"] -relatedfuncs: [] +keywords: [] +namespace: transform +relatedFuncs: [] +signature: + - transform.Markdownify INPUT + - markdownify INPUT --- ```go-html-template diff --git a/content/en/functions/math.md b/content/en/functions/math.md index 708921f68..b9d7bbeab 100644 --- a/content/en/functions/math.md +++ b/content/en/functions/math.md @@ -1,14 +1,13 @@ --- -title: Math +title: math description: Hugo provides mathematical operators in templates. -keywords: [math, operators] categories: [functions] menu: docs: parent: functions -toc: +keywords: [] +relatedFuncs: [] signature: [] -relatedfuncs: [] --- | Function | Description | Example | diff --git a/content/en/functions/md5.md b/content/en/functions/md5.md index cc5fd31ea..5b5aba574 100644 --- a/content/en/functions/md5.md +++ b/content/en/functions/md5.md @@ -6,13 +6,22 @@ menu: docs: parent: functions keywords: [] -signature: ["md5 INPUT"] -relatedfuncs: [sha] +namespace: crypto +relatedFuncs: + - crypto.FNV32a + - crypto.HMAC + - crypto.MD5 + - crypto.SHA1 + - crypto.SHA256 +signature: + - crypto.MD5 INPUT + - md5 INPUT + --- ```go-html-template -{{ md5 "Hello world, gophers!" }} - +{{ md5 "Hello world" }} → 3e25960a79dbc69b674cd4ec67a72c62 + ``` This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar: diff --git a/content/en/functions/merge.md b/content/en/functions/merge.md index 5fef26153..13801c05d 100644 --- a/content/en/functions/merge.md +++ b/content/en/functions/merge.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections] -signature: ["collections.Merge MAP MAP...", "merge MAP MAP..."] -relatedfuncs: [dict, append, reflect.IsMap, reflect.IsSlice] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Append + - collections.Merge +signature: + - collections.Merge MAP MAP... + - merge MAP MAP... --- Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key. diff --git a/content/en/functions/ne.md b/content/en/functions/ne.md index 49c69fbaa..9bcddd71b 100644 --- a/content/en/functions/ne.md +++ b/content/en/functions/ne.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [comparison,operators,logic] -signature: ["ne ARG1 ARG2 [ARG...]"] -relatedfuncs: [] +namespace: compare +relatedFuncs: + - compare.Eq + - compare.Ge + - compare.Gt + - compare.Le + - compare.Lt + - compare.Ne +signature: + - compare.Ne ARG1 ARG2 [ARG...] + - ne ARG1 ARG2 [ARG...] --- ```go-html-template diff --git a/content/en/functions/now.md b/content/en/functions/now.md index 68d628f11..74cadafd5 100644 --- a/content/en/functions/now.md +++ b/content/en/functions/now.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [dates,time] -signature: ["now"] -relatedfuncs: [Unix,dateFormat] +keywords: [] +namespace: time +relatedFuncs: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration +signature: + - time.Now + - now + --- See [`time.Time`](https://godoc.org/time#Time). diff --git a/content/en/functions/os.Stat.md b/content/en/functions/os.Stat.md index 51d35ae2f..c612f9f19 100644 --- a/content/en/functions/os.Stat.md +++ b/content/en/functions/os.Stat.md @@ -5,10 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [files] -signature: ["os.Stat PATH"] -relatedfuncs: ['os.FileExists','os.ReadDir','os.ReadFile'] +keywords: [] +namespace: os +relatedFuncs: + - os.FileExists + - os.Getenv + - os.ReadDir + - os.ReadFile + - os.Stat +signature: + - os.Stat PATH --- + The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. ```go-html-template diff --git a/content/en/functions/page.md b/content/en/functions/page.md new file mode 100644 index 000000000..c2eb35758 --- /dev/null +++ b/content/en/functions/page.md @@ -0,0 +1,105 @@ +--- +title: page +description: Provides global access to the .Page object. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: global +relatedFuncs: + - page + - site +signature: [page] +--- + +At the top level of a template that receives the `Page` object in context, these are equivalent: + +```go-html-template +{{ .Params.foo }} +{{ .Page.Params.foo }} +{{ page.Params.foo }} +``` + +When the `Page` object is not in context, you can use the global `page` function: + +```go-html-template +{{ page.Params.foo }} +``` + +{{% note %}} +Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. +{{% /note %}} + +## Explanation + +Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` variable in the template. + +But when you are deeply nested inside of a [content view], [partial], or [render hook], it isn't always practical or possible to access the `Page` object. + +Use the global `page` function to access the `Page` object from anywhere in any template. + +## Warnings + +### Be aware of top-level context + +The global `page` function accesses the `Page` object passed into the top-level template. + +With this content structure: + +```text +content/ +├── posts/ +│ ├── post-1.md +│ ├── post-2.md +│ └── post-3.md +└── _index.md <-- title is "My Home Page" +``` + +And this code in the home page template: + +```go-html-template +{{ range site.Sections }} + {{ range .Pages }} + {{ page.Title }} + {{ end }} +{{ end }} +``` + +The rendered output will be: + +```text +My Home Page +My Home Page +My Home Page +``` + +In the example above, the global `page` function accesses the `Page` object passed into the home page template; it does not access the `Page` object of the iterated pages. + +### Be aware of caching + +Do not use the global `page` function in: + +- Shortcodes +- Partials called by shortcodes +- Partials cached by the `partialCached` function + +Hugo caches rendered shortcodes. If you use the `global` page function within a shortcode, and the page content is rendered in two or more templates, the cached shortcodes may be incorrect. + +Consider this section template: + +```go-html-template +{{ range .Pages }} +

{{ .LinkTitle }}

+ {{ .Summary }} +{{ end }} +``` + +When you call the `.Summary` method, Hugo renders the page `.Content` including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page. + +If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency. + +[content view]: /getting-started/glossary/#content-view +[partial]: /getting-started/glossary/#partial +[render hook]: /getting-started/glossary/#render-hook +[shortcode]: getting-started/glossary/#shortcode diff --git a/content/en/functions/param.md b/content/en/functions/param.md index 45ef4434c..b7d91544a 100644 --- a/content/en/functions/param.md +++ b/content/en/functions/param.md @@ -1,12 +1,16 @@ --- title: .Param description: Returns a page parameter, falling back to a site parameter if present. -signature: ['.Param KEY'] categories: [functions] -keywords: ['front matter', 'params'] menu: docs: parent: functions +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .Param KEY + --- The `.Param` method on `.Page` looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `.Param` method returns `nil`. diff --git a/content/en/functions/partial.md b/content/en/functions/partial.md new file mode 100644 index 000000000..447f6d623 --- /dev/null +++ b/content/en/functions/partial.md @@ -0,0 +1,65 @@ +--- +title: partial +description: Executes the named partial template. If the partial contains a return statement, returns that value, else returns the rendered output. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: partials +relatedFuncs: + - partials.Include + - partials.IncludeCached +signature: + - partials.Include LAYOUT [CONTEXT] + - partial LAYOUT [CONTEXT] +--- + +In this example we have three partial templates: + +```text +layouts/ +└── partials/ + ├── average.html + ├── breadcrumbs.html + └── footer.html +``` + +The "average" partial returns the average of one or more numbers. We pass the numbers in context: + +```go-html-template +{{ $numbers := slice 1 6 7 42 }} +{{ $average := partial "average.html" $numbers }} +``` + +The "breadcrumbs" partial renders [breadcrumb navigation], and needs to receive the current page in context: + +```go-html-template +{{ partial "breadcrumbs.html" . }} +``` + +The "footer" partial renders the site footer. In this contrived example, the footer does not need access to the current page, so we can omit context: + +```go-html-template +{{ partial "breadcrumbs.html" }} +``` + +You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. For example: + +```go-html-template +{{ $student := dict + "name" "John Doe" + "major" "Finance" + "gpa" 4.0 +}} +{{ partial "render-student-info.html" $student }} +``` + +Then, within the partial template: + +```go-html-template +

{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.

+``` + + +[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants diff --git a/content/en/functions/partialCached.md b/content/en/functions/partialCached.md index 7eed566f6..5084fc44d 100644 --- a/content/en/functions/partialCached.md +++ b/content/en/functions/partialCached.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [performance] -signature: ["partialCached LAYOUT INPUT [VARIANT...]"] -relatedfuncs: [] +keywords: [] +namespace: partials +relatedFuncs: + - partials.Include + - partials.IncludeCached +signature: + - partials.IncludeCached LAYOUT CONTEXT [VARIANT...] + - partialCached LAYOUT CONTEXT [VARIANT...] --- The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. diff --git a/content/en/functions/path.Base.md b/content/en/functions/path.Base.md index 5ea0564fa..785f5347e 100644 --- a/content/en/functions/path.Base.md +++ b/content/en/functions/path.Base.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, base] -signature: ["path.Base PATH"] -relatedfuncs: [path.BaseName, path.Clean, path.Dir, path.Ext, path.Join, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.Base PATH --- `path.Base` returns the last element of `PATH`. diff --git a/content/en/functions/path.BaseName.md b/content/en/functions/path.BaseName.md index 95a521a1a..54aa8bde7 100644 --- a/content/en/functions/path.BaseName.md +++ b/content/en/functions/path.BaseName.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, base] -signature: ["path.BaseName PATH"] -relatedfuncs: [path.Base, path.Clean, path.Dir, path.Ext, path.Join, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.BaseName PATH --- If `PATH` is empty, `.` is returned. diff --git a/content/en/functions/path.Clean.md b/content/en/functions/path.Clean.md index ce53cc9ff..866f17b76 100644 --- a/content/en/functions/path.Clean.md +++ b/content/en/functions/path.Clean.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, clean] -signature: ["path.Clean PATH"] -relatedfuncs: [path.Base, path.BaseName, path.Dir, path.Ext, path.Join, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.Clean PATH --- `path.Clean` replaces path separators with slashes (`/`) and removes extraneous separators, including trailing separators. diff --git a/content/en/functions/path.Dir.md b/content/en/functions/path.Dir.md index 0083a1efa..809128a12 100644 --- a/content/en/functions/path.Dir.md +++ b/content/en/functions/path.Dir.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, dir] -signature: ["path.Dir PATH"] -relatedfuncs: [path.Base, path.BaseName, path.Clean, path.Ext, path.Join, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.Dir PATH --- `path.Dir` returns all but the last element of `PATH`, typically `PATH`'s directory. diff --git a/content/en/functions/path.Ext.md b/content/en/functions/path.Ext.md index 2e1946608..4e157dc3c 100644 --- a/content/en/functions/path.Ext.md +++ b/content/en/functions/path.Ext.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, ext, extension] -signature: ["path.Ext PATH"] -relatedfuncs: [path.Base, path.BaseName, path.Clean, path.Dir, path.Join, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.Ext PATH --- `path.Ext` returns the file name extension `PATH`. diff --git a/content/en/functions/path.Join.md b/content/en/functions/path.Join.md index 5ac5ac469..103a15302 100644 --- a/content/en/functions/path.Join.md +++ b/content/en/functions/path.Join.md @@ -5,9 +5,19 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, join] -signature: ["path.Join ELEMENT..."] -relatedfuncs: [path.Base, path.BaseName, path.Clean, path.Dir, path.Ext, path.Split] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split + - urls.JoinPath +signature: + - path.Join ELEMENT... --- `path.Join` joins path elements into a single path, adding a separating slash if necessary. diff --git a/content/en/functions/path.Split.md b/content/en/functions/path.Split.md index aa915788e..2b36faefb 100644 --- a/content/en/functions/path.Split.md +++ b/content/en/functions/path.Split.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [path, split] -signature: ["path.Split PATH"] -relatedfuncs: [path.Base, path.BaseName, path.Clean, path.Dir, path.Ext, path.Join] +keywords: [] +namespace: path +relatedFuncs: + - path.Base + - path.BaseName + - path.Clean + - path.Dir + - path.Ext + - path.Join + - path.Split +signature: + - path.Split PATH --- `path.Split` splits `PATH` immediately following the final slash, separating it into a directory and a base component. diff --git a/content/en/functions/plainify.md b/content/en/functions/plainify.md index 8767a460e..17f67b692 100644 --- a/content/en/functions/plainify.md +++ b/content/en/functions/plainify.md @@ -5,9 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["plainify INPUT"] -relatedfuncs: [jsonify] +keywords: [] +namespace: transform +relatedFuncs: [] +signature: + - transform.Plainify + - plainify INPUT --- ```go-html-template diff --git a/content/en/functions/pluralize.md b/content/en/functions/pluralize.md index bd0860802..928a6683f 100644 --- a/content/en/functions/pluralize.md +++ b/content/en/functions/pluralize.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["pluralize INPUT"] -relatedfuncs: [] +keywords: [] +namespace: inflect +relatedFuncs: + - inflect.Humanize + - inflect.Pluralize + - inflect.Singularize +signature: + - inflect.Pluralize INPUT + - pluralize INPUT --- ```go-html-template diff --git a/content/en/functions/print.md b/content/en/functions/print.md index 4af0b6b96..19098057b 100644 --- a/content/en/functions/print.md +++ b/content/en/functions/print.md @@ -5,13 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["print INPUT"] -relatedfuncs: [] +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Print + - fmt.Printf + - fmt.Println +signature: + - fmt.Print INPUT + - print INPUT --- -See [the go doc](https://golang.org/pkg/fmt/) for additional information. - ```go-html-template {{ print "foo" }} → "foo" {{ print "foo" "bar" }} → "foobar" diff --git a/content/en/functions/printf.md b/content/en/functions/printf.md index 66f85e159..1286acb1c 100644 --- a/content/en/functions/printf.md +++ b/content/en/functions/printf.md @@ -5,17 +5,40 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["printf FORMAT INPUT"] -relatedfuncs: [] +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Print + - fmt.Printf + - fmt.Println +signature: + - fmt.Printf FORMAT [INPUT] + - printf FORMAT [INPUT] --- -See [the go doc](https://golang.org/pkg/fmt/) for additional information. +The documentation for [Go's fmt package] describes the structure and content of the format string. + +[Go's fmt package]: https://pkg.go.dev/fmt ```go-html-template -{{ i18n ( printf "combined_%s" $var ) }} +{{ $var := "world" }} +{{ printf "Hello %s." $var }} → Hello world. ``` ```go-html-template -{{ printf "formatted %.2f" 3.1416 }} +{{ $pi := 3.14159265 }} +{{ printf "Pi is approximately %.2f." $pi }} → 3.14 +``` + +Use the `printf` function with the `safeHTMLAttr` function: + +```go-html-template +{{ $desc := "Eat at Joe's" }} + +``` + +Hugo renders this to: + +```html + ``` diff --git a/content/en/functions/println.md b/content/en/functions/println.md index 6ad57f402..5eca89a8c 100644 --- a/content/en/functions/println.md +++ b/content/en/functions/println.md @@ -5,13 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["println INPUT"] -relatedfuncs: [] +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Print + - fmt.Printf + - fmt.Println +signature: + - fmt.Println INPUT + - println INPUT --- -See [the go doc](https://golang.org/pkg/fmt/) for additional information. `\n` denotes the linebreak but isn't printed in the templates as seen below: - ```go-html-template {{ println "foo" }} → "foo\n" ``` diff --git a/content/en/functions/querify.md b/content/en/functions/querify.md index b21b3a0b2..59177f14f 100644 --- a/content/en/functions/querify.md +++ b/content/en/functions/querify.md @@ -5,9 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls] -signature: ["querify KEY VALUE [KEY VALUE]...", "querify COLLECTION"] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Querify + - urlquery +signature: + - collections.Querify KEY VALUE [KEY VALUE]... + - collections.Querify COLLECTION + - querify KEY VALUE [KEY VALUE]... + - querify COLLECTION --- `querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL. diff --git a/content/en/functions/range.md b/content/en/functions/range.md index da0a4d7ef..7b8d7bc75 100644 --- a/content/en/functions/range.md +++ b/content/en/functions/range.md @@ -5,9 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [iteration] -signature: ["range COLLECTION"] -relatedfuncs: [] +keywords: [] +namespace: text/template +relatedFuncs: + - with + - range +signature: + - range COLLECTION --- Just like in the Go programming language, Go and Hugo templates make heavy use of `range` to iterate over a map, array or slice. Other templating languages use a foreach for the equivalent functionality. diff --git a/content/en/functions/readdir.md b/content/en/functions/readdir.md index a76e3c5f6..9de88bf67 100644 --- a/content/en/functions/readdir.md +++ b/content/en/functions/readdir.md @@ -5,10 +5,19 @@ categories: [functions] menu: docs: parent: functions -keywords: [files] -signature: ["os.ReadDir PATH", "readDir PATH"] -relatedfuncs: ['os.FileExists','os.ReadFile','os.Stat'] +keywords: [] +namespace: os +relatedFuncs: + - os.FileExists + - os.Getenv + - os.ReadDir + - os.ReadFile + - os.Stat +signature: + - os.ReadDir PATH + - readDir PATH --- + The `os.ReadDir` function resolves the path relative to the root of your project directory. A leading path separator (`/`) is optional. With this directory structure: diff --git a/content/en/functions/readfile.md b/content/en/functions/readfile.md index c700d7aa0..79b45a370 100644 --- a/content/en/functions/readfile.md +++ b/content/en/functions/readfile.md @@ -5,10 +5,19 @@ categories: [functions] menu: docs: parent: functions -keywords: [files] -signature: ["os.ReadFile PATH", "readFile PATH"] -relatedfuncs: ['os.FileExists','os.ReadDir','os.Stat'] +keywords: [] +namespace: os +relatedFuncs: + - os.FileExists + - os.Getenv + - os.ReadDir + - os.ReadFile + - os.Stat +signature: + - os.ReadFile PATH + - readFile PATH --- + The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. With a file named README.md in the root of your project directory: diff --git a/content/en/functions/ref.md b/content/en/functions/ref.md index 2d05ca427..b9e8c202e 100644 --- a/content/en/functions/ref.md +++ b/content/en/functions/ref.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [cross references, anchors] -signature: ["ref . PAGE"] -relatedfuncs: [relref] +keywords: [] +namespace: urls +relatedFuncs: + - urls.Ref + - urls.RelRef +signature: + - urls.Ref . PAGE + - ref . PAGE --- This function takes two arguments: diff --git a/content/en/functions/reflect.IsMap.md b/content/en/functions/reflect.IsMap.md index aa8da7d53..fa846f3b8 100644 --- a/content/en/functions/reflect.IsMap.md +++ b/content/en/functions/reflect.IsMap.md @@ -5,9 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [reflect, reflection, kind] -signature: ["reflect.IsMap INPUT"] -relatedfuncs: [reflect.IsSlice] +keywords: [] +namespace: reflect +relatedFuncs: + - reflect.IsMap + - reflect.IsSlice +signature: + - reflect.IsMap INPUT --- `reflect.IsMap` reports if `VALUE` is a map. Returns a boolean. diff --git a/content/en/functions/reflect.IsSlice.md b/content/en/functions/reflect.IsSlice.md index 0a29d8f3e..4eaf40c6b 100644 --- a/content/en/functions/reflect.IsSlice.md +++ b/content/en/functions/reflect.IsSlice.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [reflect, reflection, kind] -signature: ["reflect.IsSlice INPUT"] -relatedfuncs: [reflect.IsMap] +keywords: [] +namespace: reflect +relatedFuncs: + - reflect.IsMap + - reflect.IsSlice +signature: + - reflect.IsSlice INPUT + --- `reflect.IsSlice` reports if `VALUE` is a slice. Returns a boolean. diff --git a/content/en/functions/relLangURL.md b/content/en/functions/relLangURL.md index 78b823c23..8eaf47dd4 100644 --- a/content/en/functions/relLangURL.md +++ b/content/en/functions/relLangURL.md @@ -5,8 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls, multilingual,i18n] -signature: ["relLangURL INPUT"] +keywords: [] +namespace: urls +relatedFuncs: + - urls.AbsLangURL + - urls.AbsURL + - urls.RelLangURL + - urls.RelURL +signature: [relLangURL INPUT] --- Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: @@ -37,7 +43,7 @@ With `baseURL = https://example.org/docs/` {{ relLangURL "style.css" }} → /docs/en/style.css ``` -### Input begins with a slash +#### Input begins with a slash If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`. diff --git a/content/en/functions/relref.md b/content/en/functions/relref.md index 98ad724f7..1d91c1444 100644 --- a/content/en/functions/relref.md +++ b/content/en/functions/relref.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [cross references, anchors] -signature: ["relref . PAGE"] -relatedfuncs: [ref] +keywords: [] +namespace: urls +relatedFuncs: + - urls.Ref + - urls.RelRef +signature: + - urls.RelRef . PAGE + - relref . PAGE --- This function takes two arguments: diff --git a/content/en/functions/relurl.md b/content/en/functions/relurl.md index c8278c9df..d39c685bb 100644 --- a/content/en/functions/relurl.md +++ b/content/en/functions/relurl.md @@ -5,8 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls] -signature: ["relURL INPUT"] +keywords: [] +namespace: urls +relatedFuncs: + - urls.AbsLangURL + - urls.AbsURL + - urls.RelLangURL + - urls.RelURL +signature: [relURL INPUT] --- With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on: @@ -34,7 +40,7 @@ With `baseURL = https://example.org/docs/` {{ relURL "style.css" }} → /docs/style.css ``` -### Input begins with a slash +#### Input begins with a slash If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`. diff --git a/content/en/functions/render.md b/content/en/functions/render.md index 4e4648652..1d5228c71 100644 --- a/content/en/functions/render.md +++ b/content/en/functions/render.md @@ -5,9 +5,11 @@ categories: [functions] menu: docs: parent: functions -keywords: [views] -signature: [".Render LAYOUT"] -relatedfuncs: [] +keywords: [] +namespace: +relatedFuncs: [] +signature: + - .Render LAYOUT --- 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). diff --git a/content/en/functions/replace.md b/content/en/functions/replace.md index 4c150bfef..da58f9cb2 100644 --- a/content/en/functions/replace.md +++ b/content/en/functions/replace.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [replace] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FindRE + - strings.FindRESubmatch + - strings.Replace + - strings.ReplaceRE signature: - - "replace INPUT OLD NEW [LIMIT]" - - "strings.Replace INPUT OLD NEW [LIMIT]" -relatedfuncs: [replaceRE] + - strings.Replace INPUT OLD NEW [LIMIT] + - replace INPUT OLD NEW [LIMIT] --- Replace returns a copy of `INPUT` with all occurrences of `OLD` replaced with `NEW`. diff --git a/content/en/functions/replacere.md b/content/en/functions/replacere.md index 4dba19bfe..4116e57d2 100644 --- a/content/en/functions/replacere.md +++ b/content/en/functions/replacere.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [regex] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FindRE + - strings.FindRESubmatch + - strings.Replace + - strings.ReplaceRE signature: - - "replaceRE PATTERN REPLACEMENT INPUT [LIMIT]" - - "strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]" -relatedfuncs: [findRE, FindRESubmatch, replace] + - strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT] + - replaceRE PATTERN REPLACEMENT INPUT [LIMIT] --- By default, `replaceRE` replaces all matches. You can limit the number of matches with an optional LIMIT argument. diff --git a/content/en/functions/safeCSS.md b/content/en/functions/safeCSS.md index 93595286c..7861932c9 100644 --- a/content/en/functions/safeCSS.md +++ b/content/en/functions/safeCSS.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [style,css,strings] -signature: ["safeCSS INPUT"] -relatedfuncs: [safeHTML,safeHTMLAttr,] +keywords: [] +namespace: safe +relatedFuncs: + - safe.CSS + - safe.HTML + - safe.HTMLAttr + - safe.JS + - safe.URL +signature: + - safe.CSS INPUT + - safeCSS INPUT --- In this context, *safe* means CSS content that matches any of the following: diff --git a/content/en/functions/safeHTML.md b/content/en/functions/safeHTML.md index 4e74b44d4..a80431cb7 100644 --- a/content/en/functions/safeHTML.md +++ b/content/en/functions/safeHTML.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["safeHTML INPUT"] -relatedfuncs: [] +keywords: [] +namespace: safe +relatedFuncs: + - safe.CSS + - safe.HTML + - safe.HTMLAttr + - safe.JS + - safe.URL +signature: + - safe.HTML INPUT + - safeHTML INPUT + --- It should not be used for HTML from a third-party, or HTML with unclosed tags or comments. diff --git a/content/en/functions/safeHTMLAttr.md b/content/en/functions/safeHTMLAttr.md index bced1ba10..b2e5f4649 100644 --- a/content/en/functions/safeHTMLAttr.md +++ b/content/en/functions/safeHTMLAttr.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["safeHTMLAttr INPUT"] -relatedfuncs: [] +keywords: [] +namespace: safe +relatedFuncs: + - safe.CSS + - safe.HTML + - safe.HTMLAttr + - safe.JS + - safe.URL +signature: + - safe.HTMLAttr INPUT + - safeHTMLAttr INPUT --- Given a site configuration that contains this menu entry: diff --git a/content/en/functions/safeJS.md b/content/en/functions/safeJS.md index 48c2c363b..8e32b0bd0 100644 --- a/content/en/functions/safeJS.md +++ b/content/en/functions/safeJS.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["safeJS INPUT"] -relatedfuncs: [] +keywords: [] +namespace: safe +relatedFuncs: + - safe.CSS + - safe.HTML + - safe.HTMLAttr + - safe.JS + - safe.URL +signature: + - safe.JS INPUT + - safeJS INPUT --- In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`). diff --git a/content/en/functions/safeURL.md b/content/en/functions/safeURL.md index b21de4953..e205e9748 100644 --- a/content/en/functions/safeURL.md +++ b/content/en/functions/safeURL.md @@ -6,8 +6,17 @@ categories: [functions] menu: docs: parent: functions -signature: ["safeURL INPUT"] -relatedfuncs: [] +keywords: [] +namespace: safe +relatedFuncs: + - safe.CSS + - safe.HTML + - safe.HTMLAttr + - safe.JS + - safe.URL +signature: + - safe.URL INPUT + - safeURL INPUT --- `safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector. diff --git a/content/en/functions/scratch.md b/content/en/functions/scratch.md index 16e502b84..5836ca225 100644 --- a/content/en/functions/scratch.md +++ b/content/en/functions/scratch.md @@ -1,14 +1,16 @@ --- title: .Scratch description: Acts as a "scratchpad" to store and manipulate data. -keywords: [iteration] categories: [functions] menu: docs: parent: functions -toc: -signature: [] -relatedfuncs: [] +keywords: [] +namespace: +relatedFuncs: + - .Store + - .Scratch +signature: aliases: [/extras/scratch/,/doc/scratch/] --- diff --git a/content/en/functions/seq.md b/content/en/functions/seq.md index 75edf5d2d..342250e39 100644 --- a/content/en/functions/seq.md +++ b/content/en/functions/seq.md @@ -6,8 +6,21 @@ menu: docs: parent: functions keywords: [] -signature: ["seq LAST", "seq FIRST LAST", "seq FIRST INCREMENT LAST"] -relatedfuncs: [] +namespace: collections +relatedFuncs: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice +signature: + - collections.Seq LAST + - collections.Seq FIRST LAST + - collections.Seq FIRST INCREMENT LAST + - seq LAST + - seq FIRST LAST + - seq FIRST INCREMENT LAST --- ```go-html-template diff --git a/content/en/functions/sha.md b/content/en/functions/sha.md deleted file mode 100644 index 1f6cf8da0..000000000 --- a/content/en/functions/sha.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: sha -description: Hashes the given input and returns either an SHA1 or SHA256 checksum. -categories: [functions] -menu: - docs: - parent: functions -keywords: [sha,checksum] -signature: ["sha1 INPUT", "sha256 INPUT"] -relatedfuncs: [md5] -aliases: [sha1, sha256] ---- - -`sha1` hashes the given input and returns its SHA1 checksum. - -```go-html-template -{{ sha1 "Hello world, gophers!" }} - -``` - -`sha256` hashes the given input and returns its SHA256 checksum. - -```go-html-template -{{ sha256 "Hello world, gophers!" }} - -``` diff --git a/content/en/functions/sha1.md b/content/en/functions/sha1.md new file mode 100644 index 000000000..80dae32af --- /dev/null +++ b/content/en/functions/sha1.md @@ -0,0 +1,24 @@ +--- +title: sha1 +description: Hashes the given input and returns its SHA1 checksum. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: crypto +relatedFuncs: + - crypto.FNV32a + - crypto.HMAC + - crypto.MD5 + - crypto.SHA1 + - crypto.SHA256 +signature: + - crypto.SHA1 INPUT + - sha1 INPUT +aliases: [sha] +--- + +```go-html-template +{{ sha1 "Hello world" }} → 7b502c3a1f48c8609ae212cdfb639dee39673f5e +``` diff --git a/content/en/functions/sha256.md b/content/en/functions/sha256.md new file mode 100644 index 000000000..dcd67cf78 --- /dev/null +++ b/content/en/functions/sha256.md @@ -0,0 +1,24 @@ +--- +title: sha256 +description: Hashes the given input and returns its SHA256 checksum. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: crypto +relatedFuncs: + - crypto.FNV32a + - crypto.HMAC + - crypto.MD5 + - crypto.SHA1 + - crypto.SHA256 +signature: + - crypto.SHA256 INPUT + - sha256 INPUT +aliases: [sha] +--- + +```go-html-template +{{ sha256 "Hello world" }} → 64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c +``` diff --git a/content/en/functions/shuffle.md b/content/en/functions/shuffle.md index 4de66da28..d07b3d2ac 100644 --- a/content/en/functions/shuffle.md +++ b/content/en/functions/shuffle.md @@ -6,8 +6,16 @@ categories: [functions] menu: docs: parent: functions -signature: ["shuffle COLLECTION"] -relatedfuncs: [seq] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Reverse + - collections.Shuffle + - collections.Sort + - collections.Uniq +signature: + - collections.Shuffle COLLECTION + - shuffle COLLECTION --- diff --git a/content/en/functions/singularize.md b/content/en/functions/singularize.md index 4e56684b9..f5b85d304 100644 --- a/content/en/functions/singularize.md +++ b/content/en/functions/singularize.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings,singular] -signature: ["singularize INPUT"] -relatedfuncs: [] +keywords: [] +namespace: inflect +relatedFuncs: + - inflect.Humanize + - inflect.Pluralize + - inflect.Singularize +signature: + - inflect.Singularize INPUT + - singularize INPUT --- `{{ "cats" | singularize }}` → "cat" diff --git a/content/en/functions/site.md b/content/en/functions/site.md index b408f7141..522375588 100644 --- a/content/en/functions/site.md +++ b/content/en/functions/site.md @@ -1,14 +1,32 @@ --- title: site -description: The `site` function provides global access to the same data as the `.Site` page method. -keywords: [] +description: Provides global access to the .Site object. categories: [functions] menu: docs: parent: functions -toc: -signature: ["site"] -relatedfuncs: ["hugo"] +keywords: [] +namespace: global +relatedFuncs: + - page + - site +signature: [site] --- -`site` is a global function which returns the same data as the `.Site` page method. See: [Site Variables](/variables/site). +At the top level of a template that receives the `Site` object in context, these are equivalent: + +```go-html-template +{{ .Site.Params.foo }} +{{ site.Params.foo }} +``` + +When the `Site` object is not in context, use the global `site` function: + +```go-html-template +{{ site.Params.foo }} +``` + +{{% note %}} +To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. + +{{% /note %}} diff --git a/content/en/functions/slice.md b/content/en/functions/slice.md index d2ef62861..12568b746 100644 --- a/content/en/functions/slice.md +++ b/content/en/functions/slice.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [slice, array, interface] -signature: ["slice ITEM..."] -relatedfuncs: [] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Apply + - collections.Delimit + - collections.In + - collections.Reverse + - collections.Seq + - collections.Slice +signature: + - collections.Slice ITEM... + - slice ITEM... --- One use case is the concatenation of elements in combination with the [`delimit` function]: diff --git a/content/en/functions/slicestr.md b/content/en/functions/slicestr.md index bbdf95696..2b088e493 100644 --- a/content/en/functions/slicestr.md +++ b/content/en/functions/slicestr.md @@ -5,11 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] +keywords: [] +namespace: strings +relatedFuncs: [] signature: - - "slicestr STRING START [END]" - - "strings.SliceString STRING START [END]" -relatedfuncs: [] + - strings.SliceString STRING START [END] + - slicestr STRING START [END] --- For example, 1 and 4 creates a slice including elements 1 through 3. diff --git a/content/en/functions/sort.md b/content/en/functions/sort.md index aa15f5cd6..d0c722b0b 100644 --- a/content/en/functions/sort.md +++ b/content/en/functions/sort.md @@ -2,12 +2,19 @@ title: sort description: Sorts slices, maps, and page collections. categories: [functions] -signature: ["sort COLLECTION [KEY] [ORDER]"] menu: docs: parent: functions -keywords: [ordering,sorting,lists] -toc: true +keywords: [] +namespace: collections +relatedFuncs: + - collections.Reverse + - collections.Shuffle + - collections.Sort + - collections.Uniq +signature: + - collections.Sort COLLECTION [KEY] [ORDER] + - sort COLLECTION [KEY] [ORDER] --- The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below. diff --git a/content/en/functions/split.md b/content/en/functions/split.md index d2f3cc8b3..d5d089b77 100644 --- a/content/en/functions/split.md +++ b/content/en/functions/split.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["split STRING DELIM"] -relatedfuncs: [] +keywords: [] +namespace: strings +relatedFuncs: + - collections.Delimit + - strings.Split +signature: + - strings.Split STRING DELIM + - split STRING DELIM --- Examples: diff --git a/content/en/functions/store.md b/content/en/functions/store.md index d57194d80..a9640a08a 100644 --- a/content/en/functions/store.md +++ b/content/en/functions/store.md @@ -5,8 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [scratch] -signature: [] +keywords: [] +namespace: +relatedFuncs: + - .Store + - .Scratch +signature: --- The `.Store` method on `.Page` returns a [Scratch] to store and manipulate data. In contrast to the `.Scratch` method, this Scratch is not reset on server rebuilds. diff --git a/content/en/functions/string.md b/content/en/functions/string.md index df9d07116..341a3a89c 100644 --- a/content/en/functions/string.md +++ b/content/en/functions/string.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [cast,strings] -signature: ["string INPUT"] -relatedfuncs: [] +keywords: [] +namespace: cast +relatedFuncs: + - cast.ToFloat + - cast.ToInt + - cast.ToString +signature: + - cast.ToString INPUT + - string INPUT --- With a decimal (base 10) input: diff --git a/content/en/functions/strings.Contains.md b/content/en/functions/strings.Contains.md index 44cb73b81..dc8a35370 100644 --- a/content/en/functions/strings.Contains.md +++ b/content/en/functions/strings.Contains.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [string strings substring contains] -signature: ["strings.Contains STRING SUBSTRING"] -relatedfuncs: [strings.ContainsAny] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix + - collections.In +signature: + - strings.Contains STRING SUBSTRING --- {{ strings.Contains "Hugo" "go" }} → true diff --git a/content/en/functions/strings.ContainsAny.md b/content/en/functions/strings.ContainsAny.md index 36fa8701b..f41ca0ec9 100644 --- a/content/en/functions/strings.ContainsAny.md +++ b/content/en/functions/strings.ContainsAny.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [string strings substring contains any] -signature: ["strings.ContainsAny STRING CHARACTERS"] -relatedfuncs: [strings.Contains] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix + - collections.In +signature: + - strings.ContainsAny STRING CHARACTERS + --- {{ strings.ContainsAny "Hugo" "gm" }} → true diff --git a/content/en/functions/strings.ContainsNonSpace.md b/content/en/functions/strings.ContainsNonSpace.md index eafe292f5..c8dcc1a45 100644 --- a/content/en/functions/strings.ContainsNonSpace.md +++ b/content/en/functions/strings.ContainsNonSpace.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [whitespace space] -signature: ["strings.ContainsNonSpace STRING"] -relatedfuncs: ["strings.Contains","strings.ContainsAny"] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix + - collections.In +signature: + - strings.ContainsNonSpace STRING --- ```go-html-template diff --git a/content/en/functions/strings.Count.md b/content/en/functions/strings.Count.md index 7c3945693..152685355 100644 --- a/content/en/functions/strings.Count.md +++ b/content/en/functions/strings.Count.md @@ -5,9 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [count, counting, character count] -signature: ["strings.Count SUBSTR STRING"] -relatedfuncs: [] +keywords: [] +namespace: strings +relatedFuncs: + - len + - strings.Count + - strings.CountRunes + - strings.CountWords + - strings.RuneCount +signature: + - strings.Count SUBSTR STRING --- If `SUBSTR` is an empty string, this function returns 1 plus the number of Unicode code points in `STRING`. diff --git a/content/en/functions/strings.FirstUpper.md b/content/en/functions/strings.FirstUpper.md index fab82a2dc..7571f3c9d 100644 --- a/content/en/functions/strings.FirstUpper.md +++ b/content/en/functions/strings.FirstUpper.md @@ -5,8 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings capitalize uppercase first] -signature: ["strings.FirstUpper STRING"] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FirstUpper + - strings.Title + - strings.ToLower + - strings.ToUpper +signature: + - strings.FirstUpper STRING --- - {{ strings.FirstUpper "foo" }} → "Foo" +{{ strings.FirstUpper "foo" }} → "Foo" diff --git a/content/en/functions/strings.HasPrefix.md b/content/en/functions/strings.HasPrefix.md index 70317a4c1..332050b7e 100644 --- a/content/en/functions/strings.HasPrefix.md +++ b/content/en/functions/strings.HasPrefix.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["hasPrefix STRING PREFIX","strings.HasPrefix STRING PREFIX"] -relatedfuncs: [hasSuffix] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix + - collections.In +signature: + - strings.HasPrefix STRING PREFIX + - hasPrefix STRING PREFIX aliases: [/functions/hasprefix/] --- diff --git a/content/en/functions/strings.HasSuffix.md b/content/en/functions/strings.HasSuffix.md index 3ead121a3..5ba29a550 100644 --- a/content/en/functions/strings.HasSuffix.md +++ b/content/en/functions/strings.HasSuffix.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["hasSuffix STRING SUFFIX","strings.HasSuffix STRING SUFFIX"] -relatedfuncs: [hasPrefix] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Contains + - strings.ContainsAny + - strings.ContainsNonSpace + - strings.HasPrefix + - strings.HasSuffix + - collections.In +signature: + - strings.HasSuffix STRING SUFFIX + - hasSuffix STRING SUFFIX aliases: [/functions/hassuffix/] --- diff --git a/content/en/functions/strings.Repeat.md b/content/en/functions/strings.Repeat.md index 99b2fe5a5..8578cf8cc 100644 --- a/content/en/functions/strings.Repeat.md +++ b/content/en/functions/strings.Repeat.md @@ -5,9 +5,11 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["strings.Repeat COUNT INPUT"] -relatedfuncs: [] +keywords: [] +namespace: strings +relatedFuncs: [] +signature: + - strings.Repeat COUNT INPUT --- ```go-html-template diff --git a/content/en/functions/strings.RuneCount.md b/content/en/functions/strings.RuneCount.md index 3a72e339a..c80d86e42 100644 --- a/content/en/functions/strings.RuneCount.md +++ b/content/en/functions/strings.RuneCount.md @@ -5,9 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [counting, character count, length, rune length, rune count] -signature: ["strings.RuneCount INPUT"] -relatedfuncs: ["len", "countrunes"] +keywords: [] +namespace: strings +relatedFuncs: + - len + - strings.Count + - strings.CountRunes + - strings.CountWords + - strings.RuneCount +signature: + - strings.RuneCount INPUT --- In contrast with `strings.CountRunes` function, which strips HTML and whitespace before counting runes, `strings.RuneCount` simply counts all the runes in a string. It relies on the Go [`utf8.RuneCountInString`] function. diff --git a/content/en/functions/strings.TrimLeft.md b/content/en/functions/strings.TrimLeft.md index b0271c8a8..eb9458b3e 100644 --- a/content/en/functions/strings.TrimLeft.md +++ b/content/en/functions/strings.TrimLeft.md @@ -5,9 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["strings.TrimLeft CUTSET STRING"] -relatedfuncs: [strings.TrimRight] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix +signature: + - strings.TrimLeft CUTSET STRING + --- Given the string `"abba"`, leading `"a"`'s can be removed a follows: diff --git a/content/en/functions/strings.TrimPrefix.md b/content/en/functions/strings.TrimPrefix.md index c3f702961..2103d64c7 100644 --- a/content/en/functions/strings.TrimPrefix.md +++ b/content/en/functions/strings.TrimPrefix.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["strings.TrimPrefix PREFIX STRING"] -relatedfuncs: [strings.TrimSuffix] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix +signature: + - strings.TrimPrefix PREFIX STRING --- Given the string `"aabbaa"`, the specified prefix is only removed if `"aabbaa"` starts with it: diff --git a/content/en/functions/strings.TrimRight.md b/content/en/functions/strings.TrimRight.md index e61b884cd..651fbcbca 100644 --- a/content/en/functions/strings.TrimRight.md +++ b/content/en/functions/strings.TrimRight.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["strings.TrimRight CUTSET STRING"] -relatedfuncs: [strings.TrimRight] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix +signature: + - strings.TrimRight CUTSET STRING --- Given the string `"abba"`, trailing `"a"`'s can be removed a follows: diff --git a/content/en/functions/strings.TrimSuffix.md b/content/en/functions/strings.TrimSuffix.md index 05bb92400..3fe81d94a 100644 --- a/content/en/functions/strings.TrimSuffix.md +++ b/content/en/functions/strings.TrimSuffix.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] -signature: ["strings.TrimSuffix SUFFIX STRING"] -relatedfuncs: [strings.TrimPrefix] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix +signature: + - strings.TrimSuffix SUFFIX STRING --- Given the string `"aabbaa"`, the specified suffix is only removed if `"aabbaa"` ends with it: diff --git a/content/en/functions/substr.md b/content/en/functions/substr.md index 90ee47b55..6bdb10126 100644 --- a/content/en/functions/substr.md +++ b/content/en/functions/substr.md @@ -5,11 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] +keywords: [] +namespace: strings +relatedFuncs: [] signature: - - "substr STRING START [LENGTH]" - - "strings.Substr STRING START [LENGTH]" -relatedfuncs: [] + - substr STRING START [LENGTH] + - strings.Substr STRING START [LENGTH] --- It normally takes two argument: `start` and `length`. It can also take one argument: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. diff --git a/content/en/functions/symdiff.md b/content/en/functions/symdiff.md index ffc309418..ad2e29333 100644 --- a/content/en/functions/symdiff.md +++ b/content/en/functions/symdiff.md @@ -5,8 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections,intersect,union,complement] -signature: ["COLLECTION | symdiff COLLECTION" ] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Complement + - collections.Intersect + - collections.SymDiff + - collections.Union +signature: + - COLLECTION | collections.SymDiff COLLECTION + - COLLECTION | symdiff COLLECTION --- Example: diff --git a/content/en/functions/templates.Exists.md b/content/en/functions/templates.Exists.md index b9f340c21..0b42d5fdb 100644 --- a/content/en/functions/templates.Exists.md +++ b/content/en/functions/templates.Exists.md @@ -2,14 +2,15 @@ title: templates.Exists description: "Checks whether a template file exists under the given path relative to the `layouts` directory." categories: [functions] -tags: [] menu: docs: parent: functions -ns: "" -keywords: ["templates", "template", "layouts"] -signature: ["templates.Exists PATH"] -relatedfuncs: [] +keywords: [] +namespace: templates +relatedFuncs: [] +signature: + - templates.Exists PATH + --- A template file is any file living below the `layouts` directories of either the project or any of its theme components including partials and shortcodes. diff --git a/content/en/functions/time.ParseDuration.md b/content/en/functions/time.ParseDuration.md index 0332c1706..146082ce9 100644 --- a/content/en/functions/time.ParseDuration.md +++ b/content/en/functions/time.ParseDuration.md @@ -5,8 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [time parse duration] -signature: ["time.ParseDuration DURATION"] +keywords: [] +namespace: time +relatedFuncs: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration +signature: + - time.ParseDuration DURATION --- `time.ParseDuration` parses a duration string into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. diff --git a/content/en/functions/time.md b/content/en/functions/time.md index 99182f317..d534098c9 100644 --- a/content/en/functions/time.md +++ b/content/en/functions/time.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [dates,time,location] -signature: ["time INPUT [TIMEZONE]"] -relatedfuncs: [] +keywords: [] +namespace: time +relatedFuncs: + - time.AsTime + - time.Duration + - time.Format + - time.Now + - time.ParseDuration +signature: + - time.AsTime INPUT [TIMEZONE] + - time INPUT [TIMEZONE] --- diff --git a/content/en/functions/title.md b/content/en/functions/title.md index d8e0f73a4..80627cf5d 100644 --- a/content/en/functions/title.md +++ b/content/en/functions/title.md @@ -5,11 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] +keywords: [] +namespace: strings +relatedFuncs: + - strings.FirstUpper + - strings.Title + - strings.ToLower + - strings.ToUpper signature: - - "title STRING" - - "strings.Title STRING" -relatedfuncs: [] + - strings.Title STRING + - title STRING --- ```go-html-template diff --git a/content/en/functions/transform.Remarshal.md b/content/en/functions/transform.Remarshal.md index e1605197f..f961a35cd 100644 --- a/content/en/functions/transform.Remarshal.md +++ b/content/en/functions/transform.Remarshal.md @@ -6,7 +6,13 @@ menu: docs: parent: functions keywords: [] -signature: [ transform.Remarshal FORMAT INPUT ] +namespace: transform +relatedFuncs: + - encoding.Jsonify + - transform.Remarshal + - transform.Unmarshal +signature: + - transform.Remarshal FORMAT INPUT --- The FORMAT must be one of `json`, `toml`, `yaml`, or `xml`. If the INPUT is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. diff --git a/content/en/functions/transform.Unmarshal.md b/content/en/functions/transform.Unmarshal.md index 7d0920da8..f976b2f3d 100644 --- a/content/en/functions/transform.Unmarshal.md +++ b/content/en/functions/transform.Unmarshal.md @@ -1,12 +1,19 @@ --- title: transform.Unmarshal -description: "`transform.Unmarshal` (alias `unmarshal`) parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV." +description: Parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV. categories: [functions] menu: docs: parent: functions keywords: [] -signature: ["RESOURCE or STRING | transform.Unmarshal [OPTIONS]"] +namespace: transform +relatedFuncs: + - encoding.Jsonify + - transform.Remarshal + - transform.Unmarshal +signature: + - RESOURCE or STRING | transform.Unmarshal [OPTIONS] + - RESOURCE or STRING | unmarshal [OPTIONS] --- The function accepts either a `Resource` created in [Hugo Pipes](/hugo-pipes/) or via [Page Bundles](/content-management/page-bundles/), or simply a string. The two examples below will produce the same map: diff --git a/content/en/functions/trim.md b/content/en/functions/trim.md index 3d664abea..a2048c832 100644 --- a/content/en/functions/trim.md +++ b/content/en/functions/trim.md @@ -5,11 +5,18 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] +keywords: [] +namespace: strings +relatedFuncs: + - strings.Chomp + - strings.Trim + - strings.TrimLeft + - strings.TrimPrefix + - strings.TrimRight + - strings.TrimSuffix signature: - - "trim INPUT CUTSET" - - "strings.Trim INPUT CUTSET" -relatedfuncs: [] + - strings.Trim INPUT CUTSET + - trim INPUT CUTSET --- ```go-html-template diff --git a/content/en/functions/truncate.md b/content/en/functions/truncate.md index cf38a2dfd..8b2121180 100644 --- a/content/en/functions/truncate.md +++ b/content/en/functions/truncate.md @@ -5,11 +5,12 @@ categories: [functions] menu: docs: parent: functions -keywords: [strings] +keywords: [] +namespace: strings +relatedFuncs: [] signature: - - "truncate SIZE [ELLIPSIS] INPUT" - - "strings.Truncate SIZE [ELLIPSIS] INPUT" -relatedfuncs: [] + - strings.Truncate SIZE [ELLIPSIS] INPUT + - truncate SIZE [ELLIPSIS] INPUT --- Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings: diff --git a/content/en/functions/union.md b/content/en/functions/union.md index 86a874c91..a20610acb 100644 --- a/content/en/functions/union.md +++ b/content/en/functions/union.md @@ -5,9 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [collections,intersect,union,complement] -signature: ["union SET1 SET2"] -relatedfuncs: [intersect,where] +namespace: collections +relatedFuncs: + - collections.Complement + - collections.Intersect + - collections.SymDiff + - collections.Union +signature: + - collections.Union SET1 SET2 + - union SET1 SET2 --- Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64). diff --git a/content/en/functions/uniq.md b/content/en/functions/uniq.md index aecdccf95..88be1cbd3 100644 --- a/content/en/functions/uniq.md +++ b/content/en/functions/uniq.md @@ -5,8 +5,16 @@ categories: [functions] menu: docs: parent: functions -keywords: [multilingual,i18n,urls] -signature: [uniq SET] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Reverse + - collections.Shuffle + - collections.Sort + - collections.Uniq +signature: + - collections.Uniq COLLECTION + - uniq COLLECTION --- diff --git a/content/en/functions/unix.md b/content/en/functions/unix.md index 60fae9248..0d1e72700 100644 --- a/content/en/functions/unix.md +++ b/content/en/functions/unix.md @@ -1,13 +1,17 @@ --- title: .Unix description: Converts a time.Time value to the number of seconds elapsed since the Unix epoch, excluding leap seconds. The Unix epoch is 00:00:00 UTC on 1 January 1970. -keywords: [dates,time] categories: [functions] menu: docs: parent: functions -signature: [".Unix",".UnixMilli",".UnixMicro",".UnixNano"] -relatedfuncs: [Format,dateFormat,now,time] +namespace: +relatedFuncs: [] +signature: + - .Unix + - .UnixMilli + - .UnixMicro + - .UnixNano --- The `Milli`, `Micro`, and `Nano` variants return the number of milliseconds, microseconds, and nanoseconds (respectively) elapsed since the Unix epoch. diff --git a/content/en/functions/upper.md b/content/en/functions/upper.md index e11065f79..73e861525 100644 --- a/content/en/functions/upper.md +++ b/content/en/functions/upper.md @@ -1,16 +1,21 @@ --- title: upper description: Converts all characters in a string to uppercase -keywords: [] + categories: [functions] menu: docs: parent: functions -toc: +keywords: [] +namespace: strings +relatedFuncs: + - strings.FirstUpper + - strings.Title + - strings.ToLower + - strings.ToUpper signature: - - "upper INPUT" - - "strings.ToUpper INPUT" -relatedfuncs: [] + - strings.ToUpper INPUT + - upper INPUT --- Note that `upper` can be applied in your templates in more than one way: diff --git a/content/en/functions/urlize.md b/content/en/functions/urlize.md index 7a9cf25e8..820d43f99 100644 --- a/content/en/functions/urlize.md +++ b/content/en/functions/urlize.md @@ -5,9 +5,14 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls,strings] -signature: ["urlize INPUT"] -relatedfuncs: [] +keywords: [] +namespace: urls +relatedFuncs: + - urls.Anchorize + - urls.URLize +signature: + - urls.URLize INPUT + - urlize INPUT --- The following examples pull from a content file with the following front matter: diff --git a/content/en/functions/urlquery.md b/content/en/functions/urlquery.md index 11ada38c4..92d17378f 100644 --- a/content/en/functions/urlquery.md +++ b/content/en/functions/urlquery.md @@ -5,12 +5,15 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls] -signature: ["urlquery INPUT [INPUT]..."] -relatedfuncs: [] +keywords: [] +namespace: text/template +relatedFuncs: + - collections.Querify + - urlquery +signature: + - urlquery INPUT [INPUT]... --- - This template code: ```go-html-template diff --git a/content/en/functions/urls.JoinPath.md b/content/en/functions/urls.JoinPath.md index f11632367..caf361c92 100644 --- a/content/en/functions/urls.JoinPath.md +++ b/content/en/functions/urls.JoinPath.md @@ -5,8 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls,path,join] -signature: ["urls.JoinPath ELEMENT..."] +keywords: [] +namespace: urls +relatedFuncs: + - path.Join + - urls.JoinPath +signature: + - urls.JoinPath ELEMENT... --- ```go-html-template diff --git a/content/en/functions/urls.Parse.md b/content/en/functions/urls.Parse.md index b2d781e7f..7358bfae0 100644 --- a/content/en/functions/urls.Parse.md +++ b/content/en/functions/urls.Parse.md @@ -5,8 +5,11 @@ categories: [functions] menu: docs: parent: functions -keywords: [urls] -signature: ["urls.Parse URL"] +keywords: [] +namespace: urls +relatedFuncs: [] +signature: + - urls.Parse URL --- The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/net/url#URL). The URL may be relative (a path, without a host) or absolute (starting with a [scheme]). Hugo throws an error when parsing an invalid URL. diff --git a/content/en/functions/warnf.md b/content/en/functions/warnf.md new file mode 100644 index 000000000..d076528f3 --- /dev/null +++ b/content/en/functions/warnf.md @@ -0,0 +1,28 @@ +--- +title: warnf +description: Log a WARNING from a template. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +namespace: fmt +relatedFuncs: + - fmt.Errorf + - fmt.Erroridf + - fmt.Warnf +signature: + - fmt.Warnf FORMAT [INPUT] + - warnf FORMAT [INPUT] +--- + +The documentation for [Go's fmt package] describes the structure and content of the format string. + +Like the [`printf`] function, the `warnf` function evaluates the format string. It then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings. + +```go-html-template +{{ warnf "Copyright notice missing from site configuration" }} +``` + +[`printf`]: /functions/printf/ +[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/content/en/functions/where.md b/content/en/functions/where.md index 9618ea4c6..6a076d1a1 100644 --- a/content/en/functions/where.md +++ b/content/en/functions/where.md @@ -5,9 +5,17 @@ categories: [functions] menu: docs: parent: functions -keywords: [filtering] -signature: ["where COLLECTION KEY [OPERATOR] MATCH"] -relatedfuncs: [intersect,first,after,last] +keywords: [] +namespace: collections +relatedFuncs: + - collections.Dictionary + - collections.Group + - collections.Index + - collections.IsSet + - collections.Where +signature: + - collections.Where COLLECTION KEY [OPERATOR] MATCH + - where COLLECTION KEY [OPERATOR] MATCH toc: true --- diff --git a/content/en/functions/with.md b/content/en/functions/with.md index 591aea01e..07426f281 100644 --- a/content/en/functions/with.md +++ b/content/en/functions/with.md @@ -5,9 +5,13 @@ categories: [functions] menu: docs: parent: functions -keywords: [conditionals] -signature: ["with INPUT"] -relatedfuncs: [] +keywords: [] +namespace: text/template +relatedFuncs: + - with + - range +signature: + - with INPUT --- An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent, unset or empty. diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index 834f72ec5..404732a23 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -64,6 +64,10 @@ A markup language for creating content. Typically markdown, but may also be HTML A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). +### content view + +A template called with the `.Page.Render` method. See [details](/templates/views/). + ### context Represented by a period "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). diff --git a/content/en/variables/page.md b/content/en/variables/page.md index 64cd80184..39a7cdb30 100644 --- a/content/en/variables/page.md +++ b/content/en/variables/page.md @@ -230,23 +230,6 @@ Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/marku `.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail). - -## The global page function - -{{< new-in "0.111.1" >}} - -Hugo almost always passes a `Page` as the data context into the top level template (e.g. `single.html`) (the one exception is the multihost sitemap template). This means that you can access the current page with the `.` variable in the template. - -But when you're deeply nested inside `.Render`, partial etc., accessing that `Page` object isn't always practical or possible. - -For this reason, Hugo provides a global `page` function that you can use to access the current page from anywhere in any template. - -```go-html-template -{{ page.Title }} -``` - -There are one caveat with this, and this isn't new, but it's worth mentioning here: There are situations in Hugo where you may see a cached value, e.g. when using `partialCached` or in a shortcode. - ## The `.RenderShortcodes` method {#rendershortcodes} {{< new-in "0.117.0" >}} This renders all the shortcodes in the content, preserving the surrounding markup (e.g. Markdown) as is. diff --git a/hugo.toml b/hugo.toml index 987026d0c..2f951c24b 100644 --- a/hugo.toml +++ b/hugo.toml @@ -66,6 +66,10 @@ disableAliases = true threshold = 80 includeNewer = true toLower = false + [[related.indices]] + toLower = true + name = "relatedFuncs" + weight = 60 [[related.indices]] name = "keywords" weight = 60 @@ -79,10 +83,6 @@ disableAliases = true applyFilter = false weight = 60 cardinalityThreshold = 50 - [[related.indices]] - name = "date" - weight = 10 - pattern = "2006" [social] twitter = "GoHugoIO" diff --git a/layouts/partials/related.html b/layouts/partials/related.html new file mode 100644 index 000000000..34c4f20f5 --- /dev/null +++ b/layouts/partials/related.html @@ -0,0 +1,17 @@ +{{- $heading := "See also" }} +{{- $related := site.RegularPages.Related . | first 5 }} + +{{- if eq .Type "functions" }} + {{- $heading = "Related functions" }} + {{- $opts := dict "document" . "indices" (slice "relatedFuncs") }} + {{- $related = site.RegularPages.Related $opts | first 7 }} +{{- end }} + +{{- with $related }} +

{{ $heading }}

+ +{{- end }}