diff options
Diffstat (limited to 'docs/content/en/functions')
292 files changed, 7031 insertions, 3265 deletions
diff --git a/docs/content/en/functions/AddDate.md b/docs/content/en/functions/AddDate.md deleted file mode 100644 index 7f5b39b16..000000000 --- a/docs/content/en/functions/AddDate.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: .AddDate -description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: time.Time - signatures: [.AddDate YEARS MONTHS DAYS] -relatedFunctions: [] ---- - -```go-html-template -{{ $d := "2022-01-01" | time.AsTime }} - -{{ $d.AddDate 0 0 1 | time.Format "2006-01-02" }} → 2022-01-02 -{{ $d.AddDate 0 1 1 | time.Format "2006-01-02" }} → 2022-02-02 -{{ $d.AddDate 1 1 1 | time.Format "2006-01-02" }} → 2023-02-02 - -{{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30 -``` - -{{% note %}} -When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. - -See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. -{{% /note %}} - -```go-html-template -{{ $d := "2023-01-31" | time.AsTime }} -{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2023-03-03 - -{{ $d := "2024-01-31" | time.AsTime }} -{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2024-03-02 - -{{ $d := "2024-02-29" | time.AsTime }} -{{ $d.AddDate 1 0 0 | time.Format "2006-01-02" }} → 2025-03-01 -``` diff --git a/docs/content/en/functions/Format.md b/docs/content/en/functions/Format.md deleted file mode 100644 index e679cb2c4..000000000 --- a/docs/content/en/functions/Format.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: .Format -description: Returns a formatted time.Time value. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: string - signatures: [.Format LAYOUT] -relatedFunctions: [] -toc: true ---- - -```go-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $t = time.AsTime $t }} -{{ $format := "2 Jan 2006" }} - -{{ $t.Format $format }} → 27 Jan 2023 -``` - -{{% note %}} -To return a formatted and localized `time.Time` value, use the [`time.Format`] function instead. - -[`time.Format`]: /functions/time/format -{{% /note %}} - -Use the `.Format` method with any `time.Time` value, including the four predefined front matter dates: - -```go-html-template -{{ $format := "2 Jan 2006" }} - -{{ .Date.Format $format }} -{{ .PublishDate.Format $format }} -{{ .ExpiryDate.Format $format }} -{{ .Lastmod.Format $format }} -``` - -## Layout string - -{{% readfile file="/functions/_common/time-layout-string.md" %}} - -## Examples - -Given this front matter: - -{{< code-toggle fm=true copy=false >}} -title = "About time" -date = 2023-01-27T23:44:58-08:00 -{{< /code-toggle >}} - -The examples below were rendered in the `America/Los_Angeles` time zone: - -Format string|Result -:--|:-- -`Monday, January 2, 2006`|`Friday, January 27, 2023` -`Mon Jan 2 2006`|`Fri Jan 27 2023` -`January 2006`|`January 2023` -`2006-01-02`|`2023-01-27` -`Monday`|`Friday` -`02 Jan 06 15:04 MST`|`27 Jan 23 23:44 PST` -`Mon, 02 Jan 2006 15:04:05 MST`|`Fri, 27 Jan 2023 23:44:58 PST` -`Mon, 02 Jan 2006 15:04:05 -0700`|`Fri, 27 Jan 2023 23:44:58 -0800` - -## UTC and local time - -Convert and format any `time.Time` value to either Coordinated Universal Time (UTC) or local time. - -```go-html-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $t = time.AsTime $t }} -{{ $format := "2 Jan 2006 3:04:05 PM MST" }} - -{{ $t.UTC.Format $format }} → 28 Jan 2023 7:44:58 AM UTC -{{ $t.Local.Format $format }} → 27 Jan 2023 11:44:58 PM PST -``` - -## Ordinal representation - -Use the [`humanize`](/functions/inflect/humanize) function to render the day of the month as an ordinal number: - -```go-html-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $t = time.AsTime $t }} - -{{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023 -``` diff --git a/docs/content/en/functions/Get.md b/docs/content/en/functions/Get.md deleted file mode 100644 index 142e9811b..000000000 --- a/docs/content/en/functions/Get.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: .Get -description: Accesses positional and ordered parameters in shortcode declaration. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: any - signatures: - - .Get INDEX - - .Get KEY -relatedFunctions: [] ---- - -`.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. - -When accessing named or positional parameters that do not exist, `.Get` returns an empty string instead of interrupting the build. This allows you to chain `.Get` with `if`, `with`, `default` or `cond` to check for parameter existence. For example: - -```go-html-template -{{ $quality := default "100" (.Get 1) }} -``` - -[sc]: /templates/shortcode-templates/ diff --git a/docs/content/en/functions/GetPage.md b/docs/content/en/functions/GetPage.md deleted file mode 100644 index 4afebaca7..000000000 --- a/docs/content/en/functions/GetPage.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: .GetPage -description: Gets a `Page` of a given `path`. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [.GetPage PATH] -relatedFunctions: [] ---- - -`.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. - -{{% note %}} -**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superfluous. -{{% /note %}} - - -```go-html-template -{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }} -``` - -This method will return `nil` when no page could be found, so the above will not print anything if the blog section is not found. - -To find a regular page in the blog section:: - -```go-html-template -{{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }} -``` - -And since `Page` also provides a `.GetPage` method, the above is the same as: - -```go-html-template -{{ with .Site.GetPage "/blog" }} -{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }} -{{ end }} -``` - -## .GetPage and multilingual sites - -The previous examples have used the full content file name to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page: - -```go-html-template -{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }} -``` - -## .GetPage example - -This code snippet---in the form of a [partial template][partials]---allows you to do the following: - -1. Grab the index object of your `tags` [taxonomy]. -2. Assign this object to a variable, `$t` -3. Sort the terms associated with the taxonomy by popularity. -4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content. - -{{< code file="grab-top-two-tags.html" >}} -<ul class="most-popular-tags"> -{{ $t := .Site.GetPage "/tags" }} -{{ range first 2 $t.Data.Terms.ByCount }} - <li>{{ . }}</li> -{{ end }} -</ul> -{{< /code >}} - -## `.GetPage` on page bundles - -If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you -need to get the nested _**page** resources_ in that, you will need to use the -methods in `.Resources` as explained in the [Page Resources][page_resources] -section. - -See the [Headless Bundle][headless_bundle] documentation for an example. - - -[partials]: /templates/partials/ -[taxonomy]: /content-management/taxonomies/ -[page_kinds]: /templates/section-templates/#page-kinds -[leaf_bundle]: /content-management/page-bundles/#leaf-bundles -[headless_bundle]: /content-management/page-bundles/#headless-bundle -[page_resources]: /content-management/page-resources/ diff --git a/docs/content/en/functions/HasMenuCurrent.md b/docs/content/en/functions/HasMenuCurrent.md deleted file mode 100644 index 5b4200c56..000000000 --- a/docs/content/en/functions/HasMenuCurrent.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: .HasMenuCurrent -description: Reports whether the given page object matches the page object associated with one of the child menu entries under the given menu entry in the given menu. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: bool - signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] -relatedFunctions: - - .HasMenuCurrent - - .IsMenuCurrent ---- - -If the page object associated with the menu entry is a section, this method also returns `true` for any descendant of that section. - -```go-html-template -{{ $currentPage := . }} -{{ range site.Menus.main }} - {{ if $currentPage.IsMenuCurrent .Menu . }} - <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a> - {{ else if $currentPage.HasMenuCurrent .Menu . }} - <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a> - {{ else }} - <a href="{{ .URL }}">{{ .Name }}</a> - {{ end }} -{{ end }} -``` - -See [menu templates] for a complete example. - -[menu templates]: /templates/menu-templates/#example diff --git a/docs/content/en/functions/IsMenuCurrent.md b/docs/content/en/functions/IsMenuCurrent.md deleted file mode 100644 index c9980b3e8..000000000 --- a/docs/content/en/functions/IsMenuCurrent.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: .IsMenuCurrent -description: Reports whether the given page object matches the page object associated with the given menu entry in the given menu. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: bool - signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] -relatedFunctions: - - .HasMenuCurrent - - .IsMenuCurrent ---- - -```go-html-template -{{ $currentPage := . }} -{{ range site.Menus.main }} - {{ if $currentPage.IsMenuCurrent .Menu . }} - <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a> - {{ else if $currentPage.HasMenuCurrent .Menu . }} - <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a> - {{ else }} - <a href="{{ .URL }}">{{ .Name }}</a> - {{ end }} -{{ end }} -``` - -See [menu templates] for a complete example. - -[menu templates]: /templates/menu-templates/#example diff --git a/docs/content/en/functions/Param.md b/docs/content/en/functions/Param.md deleted file mode 100644 index a2826a3c8..000000000 --- a/docs/content/en/functions/Param.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: .Param -description: Returns a page parameter, falling back to a site parameter if present. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: any - signatures: [.Param KEY] -relatedFunctions: [] ---- - -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`. - -Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level. - -For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed: - -**Configuration** - -{{< code-toggle file="hugo" copy=false >}} -[params] -display_toc = true -{{< /code-toggle >}} - -**Content** - -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title = 'Example' -date = 2023-01-01 -draft = false -display_toc = false -{{< /code-toggle >}} - -**Template** - -{{< code file="layouts/_default/single.html" copy=false >}} -{{ if .Param "display_toc" }} - {{ .TableOfContents }} -{{ end }} -{{< /code >}} - -The `.Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead: - -{{< code file="layouts/_default/single.html" copy=false >}} -{{ or .Params.foo site.Params.foo }} -{{< /code >}} diff --git a/docs/content/en/functions/Render.md b/docs/content/en/functions/Render.md deleted file mode 100644 index 02567845f..000000000 --- a/docs/content/en/functions/Render.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: .Render -description: Takes a view to apply when rendering content. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: template.HTML - signatures: [.Render LAYOUT] -relatedFunctions: [] ---- - -The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views). - -This function is only available when applied to a single piece of content within a [list context]. - -This example could render a piece of content using the content view located at `/layouts/_default/summary.html`: - -```go-html-template -{{ range .Pages }} - {{ .Render "summary" }} -{{ end }} -``` - -[list context]: /templates/lists/ diff --git a/docs/content/en/functions/RenderString.md b/docs/content/en/functions/RenderString.md deleted file mode 100644 index 91414d6a0..000000000 --- a/docs/content/en/functions/RenderString.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: .RenderString -description: Renders markup to HTML. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: template.HTML - signatures: ['.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). - -The method takes an optional map argument with these options: - -display ("inline") -: `inline` or `block`. If `inline` (default), surrounding `<p></p>` on short snippets will be trimmed. - -markup (defaults to the Page's markup) -: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats). - -Some examples: - -```go-html-template -{{ $optBlock := dict "display" "block" }} -{{ $optOrg := dict "markup" "org" }} -{{ "**Bold Markdown**" | $p.RenderString }} -{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }} -{{ "/italic org mode/" | $p.RenderString $optOrg }} -``` - -{{< new-in "0.93.0" >}} **Note**: [markdownify](/functions/transform/markdownify) uses this function in order to support [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks). diff --git a/docs/content/en/functions/Scratch.md b/docs/content/en/functions/Scratch.md deleted file mode 100644 index 0640d6bcc..000000000 --- a/docs/content/en/functions/Scratch.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: .Scratch -description: Acts as a "scratchpad" to store and manipulate data. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [] -relatedFunctions: - - .Store - - .Scratch -aliases: [/extras/scratch/,/doc/scratch/] ---- - -Scratch is a Hugo feature designed to conveniently manipulate data in a Go Template world. It is either a Page or Shortcode method for which the resulting data will be attached to the given context, or it can live as a unique instance stored in a variable. - -{{% note %}} -Note that Scratch was initially created as a workaround for a [Go template scoping limitation](https://github.com/golang/go/issues/10608) that affected Hugo versions prior to 0.48. For a detailed analysis of `.Scratch` and contextual use cases, see [this blog post](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/). -{{% /note %}} - -### Contexted `.Scratch` vs. local `newScratch` - -Since Hugo 0.43, there are two different ways of using Scratch: - -#### The Page's `.Scratch` - -`.Scratch` is available as a Page method or a Shortcode method and attaches the "scratched" data to the given page. Either a Page or a Shortcode context is required to use `.Scratch`. - -```go-html-template -{{ .Scratch.Set "greeting" "bonjour" }} -{{ range .Pages }} - {{ .Scratch.Set "greeting" (print "bonjour" .Title) }} -{{ end }} -``` - -#### The local `newScratch` - -A Scratch instance can also be assigned to any variable using the `newScratch` function. In this case, no Page or Shortcode context is required and the scope of the scratch is only local. The methods detailed below are available from the variable the Scratch instance was assigned to. - -```go-html-template -{{ $data := newScratch }} -{{ $data.Set "greeting" "hola" }} -``` - -### Methods - -A Scratch has the following methods: - -{{% note %}} -Note that the following examples assume a [local Scratch instance](#the-local-newscratch) has been stored in `$scratch`. -{{% /note %}} - -#### .Set - -Set the value of a given key. - -```go-html-template -{{ $scratch.Set "greeting" "Hello" }} -``` - -#### .Get - -Get the value of a given key. - -```go-html-template -{{ $scratch.Set "greeting" "Hello" }} ----- -{{ $scratch.Get "greeting" }} > Hello -``` - -#### .Add - -Add a given value to existing value(s) of the given key. - -For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be [appended](/functions/collections/append/) to that list. - -```go-html-template -{{ $scratch.Add "greetings" "Hello" }} -{{ $scratch.Add "greetings" "Welcome" }} ----- -{{ $scratch.Get "greetings" }} > HelloWelcome -``` - -```go-html-template -{{ $scratch.Add "total" 3 }} -{{ $scratch.Add "total" 7 }} ----- -{{ $scratch.Get "total" }} > 10 -``` - -```go-html-template -{{ $scratch.Add "greetings" (slice "Hello") }} -{{ $scratch.Add "greetings" (slice "Welcome" "Cheers") }} ----- -{{ $scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"} -``` - -#### .SetInMap - -Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. - -```go-html-template -{{ $scratch.SetInMap "greetings" "english" "Hello" }} -{{ $scratch.SetInMap "greetings" "french" "Bonjour" }} ----- -{{ $scratch.Get "greetings" }} > map[french:Bonjour english:Hello] -``` - -#### .DeleteInMap -Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. - -```go-html-template -{{ .Scratch.SetInMap "greetings" "english" "Hello" }} -{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }} ----- -{{ .Scratch.DeleteInMap "greetings" "english" }} ----- -{{ .Scratch.Get "greetings" }} > map[french:Bonjour] -``` - -#### .GetSortedMapValues - -Return an array of values from `key` sorted by `mapKey`. - -```go-html-template -{{ $scratch.SetInMap "greetings" "english" "Hello" }} -{{ $scratch.SetInMap "greetings" "french" "Bonjour" }} ----- -{{ $scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour] -``` - -#### .Delete - -Remove the given key. - -```go-html-template -{{ $scratch.Set "greeting" "Hello" }} ----- -{{ $scratch.Delete "greeting" }} -``` - -#### .Values - -Return the raw backing map. Note that you should only use this method on the locally scoped Scratch instances you obtain via [`newScratch`](#the-local-newscratch), not `.Page.Scratch` etc., as that will lead to concurrency issues. - - -[pagevars]: /variables/page/ diff --git a/docs/content/en/functions/Store.md b/docs/content/en/functions/Store.md deleted file mode 100644 index 49b38188b..000000000 --- a/docs/content/en/functions/Store.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: .Store -description: Returns a Scratch that is not reset on server rebuilds. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [] -relatedFunctions: - - .Store - - .Scratch ---- - -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. - -[Scratch]: /functions/scratch/ - -### Methods - -#### .Set - -Sets the value of a given key. - -```go-html-template -{{ .Store.Set "greeting" "Hello" }} -``` - -#### .Get - -Gets the value of a given key. - -```go-html-template -{{ .Store.Set "greeting" "Hello" }} - -{{ .Store.Get "greeting" }} → Hello -``` - -#### .Add - -Adds a given value to existing value(s) of the given key. - -For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list. - -```go-html-template -{{ .Store.Add "greetings" "Hello" }} -{{ .Store.Add "greetings" "Welcome" }} - -{{ .Store.Get "greetings" }} → HelloWelcome -``` - -```go-html-template -{{ .Store.Add "total" 3 }} -{{ .Store.Add "total" 7 }} - -{{ .Store.Get "total" }} → 10 -``` - -```go-html-template -{{ .Store.Add "greetings" (slice "Hello") }} -{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }} - -{{ .Store.Get "greetings" }} → []interface {}{"Hello", "Welcome", "Cheers"} -``` - -#### .SetInMap - -Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. - -```go-html-template -{{ .Store.SetInMap "greetings" "english" "Hello" }} -{{ .Store.SetInMap "greetings" "french" "Bonjour" }} - -{{ .Store.Get "greetings" }} → map[french:Bonjour english:Hello] -``` - -#### .DeleteInMap - -Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. - -```go-html-template -{{ .Store.SetInMap "greetings" "english" "Hello" }} -{{ .Store.SetInMap "greetings" "french" "Bonjour" }} -{{ .Store.DeleteInMap "greetings" "english" }} - -{{ .Store.Get "greetings" }} → map[french:Bonjour] -``` - -#### .GetSortedMapValues - -Returns an array of values from `key` sorted by `mapKey`. - -```go-html-template -{{ .Store.SetInMap "greetings" "english" "Hello" }} -{{ .Store.SetInMap "greetings" "french" "Bonjour" }} - -{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] -``` - -#### .Delete - -Removes the given key. - -```go-html-template -{{ .Store.Set "greeting" "Hello" }} - -{{ .Store.Delete "greeting" }} -``` diff --git a/docs/content/en/functions/Unix.md b/docs/content/en/functions/Unix.md deleted file mode 100644 index ed49b72b5..000000000 --- a/docs/content/en/functions/Unix.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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. -categories: [functions] -menu: - docs: - parent: functions -function: - aliases: [] - returnType: int64 - signatures: - - .Unix - - .UnixMilli - - .UnixMicro - - .UnixNano -relatedFunctions: [] ---- - -The `Milli`, `Micro`, and `Nano` variants return the number of milliseconds, microseconds, and nanoseconds (respectively) elapsed since the Unix epoch. - -```go-html-template -.Date.Unix → 1637259694 -.ExpiryDate.Unix → 1672559999 -.Lastmod.Unix → 1637361786 -.PublishDate.Unix → 1637421261 - -("1970-01-01T00:00:00-00:00" | time.AsTime).Unix → 0 -("1970-01-01T00:00:42-00:00" | time.AsTime).Unix → 42 -("1970-04-11T01:48:29-08:00" | time.AsTime).Unix → 8675309 -("2026-05-02T20:09:31-07:00" | time.AsTime).Unix → 1777777771 - -now.Unix → 1637447841 -now.UnixMilli → 1637447841347 -now.UnixMicro → 1637447841347378 -now.UnixNano → 1637447841347378799 -``` diff --git a/docs/content/en/functions/_common/_index.md b/docs/content/en/functions/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/_common/glob-patterns.md b/docs/content/en/functions/_common/glob-patterns.md new file mode 100644 index 000000000..3b0813f6f --- /dev/null +++ b/docs/content/en/functions/_common/glob-patterns.md @@ -0,0 +1,23 @@ +--- +# Do not remove front matter. +--- + +Path|Pattern|Match +:--|:--|:-- +`images/foo/a.jpg`|`images/foo/*.jpg`|`true` +`images/foo/a.jpg`|`images/foo/*.*`|`true` +`images/foo/a.jpg`|`images/foo/*`|`true` +`images/foo/a.jpg`|`images/*/*.jpg`|`true` +`images/foo/a.jpg`|`images/*/*.*`|`true` +`images/foo/a.jpg`|`images/*/*`|`true` +`images/foo/a.jpg`|`*/*/*.jpg`|`true` +`images/foo/a.jpg`|`*/*/*.*`|`true` +`images/foo/a.jpg`|`*/*/*`|`true` +`images/foo/a.jpg`|`**/*.jpg`|`true` +`images/foo/a.jpg`|`**/*.*`|`true` +`images/foo/a.jpg`|`**/*`|`true` +`images/foo/a.jpg`|`**`|`true` +`images/foo/a.jpg`|`*/*.jpg`|`false` +`images/foo/a.jpg`|`*.jpg`|`false` +`images/foo/a.jpg`|`*.*`|`false` +`images/foo/a.jpg`|`*`|`false` diff --git a/docs/content/en/functions/_common/go-template-functions.md b/docs/content/en/functions/_common/go-template-functions.md deleted file mode 100644 index b8722743e..000000000 --- a/docs/content/en/functions/_common/go-template-functions.md +++ /dev/null @@ -1,3 +0,0 @@ -See Go's [text/template] documentation for more details. - -[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/_common/index.md b/docs/content/en/functions/_common/index.md deleted file mode 100644 index cbb7365a6..000000000 --- a/docs/content/en/functions/_common/index.md +++ /dev/null @@ -1,3 +0,0 @@ -+++ -headless = true -+++ diff --git a/docs/content/en/functions/_common/locales.md b/docs/content/en/functions/_common/locales.md index 259231cbf..fd8415781 100644 --- a/docs/content/en/functions/_common/locales.md +++ b/docs/content/en/functions/_common/locales.md @@ -1,3 +1,10 @@ +--- +# Do not remove front matter. +--- + +{{% note %}} + Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales. [gohugoio/locales]: https://github.com/gohugoio/locales +{{% /note %}} diff --git a/docs/content/en/functions/_common/regular-expressions.md b/docs/content/en/functions/_common/regular-expressions.md index 9da340849..48e020ac6 100644 --- a/docs/content/en/functions/_common/regular-expressions.md +++ b/docs/content/en/functions/_common/regular-expressions.md @@ -1,3 +1,7 @@ +--- +# Do not remove front matter. +--- + When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes. Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported. diff --git a/docs/content/en/functions/_common/time-layout-string.md b/docs/content/en/functions/_common/time-layout-string.md index 40932f8cf..827dc9894 100644 --- a/docs/content/en/functions/_common/time-layout-string.md +++ b/docs/content/en/functions/_common/time-layout-string.md @@ -1,12 +1,16 @@ +--- +# Do not remove front matter. +--- + Format a `time.Time` value based on [Go's reference time]: [Go's reference time]: https://pkg.go.dev/time#pkg-constants -```text {copy=false} +```text Mon Jan 2 15:04:05 MST 2006 ``` -Create a format string using these components: +Create a layout string using these components: Description|Valid components :--|:-- @@ -21,7 +25,7 @@ Second|`"5" "05"` AM/PM mark|`"PM"` Time zone offsets|`"-0700" "-07:00" "-07" "-070000" "-07:00:00"` -Replace the sign in the format string with a Z to print Z instead of an offset for the UTC zone. +Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone. Description|Valid components :--|:-- diff --git a/docs/content/en/functions/_index.md b/docs/content/en/functions/_index.md index 4f8aa47ca..b4b58eada 100644 --- a/docs/content/en/functions/_index.md +++ b/docs/content/en/functions/_index.md @@ -1,7 +1,8 @@ --- title: Functions linkTitle: Overview -description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples. +description: A list of Hugo template functions including examples. +categories: [] keywords: [] menu: docs: @@ -9,9 +10,8 @@ menu: parent: functions weight: 10 weight: 10 +showSectionMenu: true aliases: [/layout/functions/,/templates/functions] --- -Go templates are lightweight but extensible. Go itself supplies built-in functions, including comparison operators and other basic tools. These are listed in the [Go template documentation][gofuncs]. Hugo has added additional functions to the basic template logic. - -[gofuncs]: https://golang.org/pkg/text/template/#hdr-Functions +Use these functions within your templates and archetypes. diff --git a/docs/content/en/functions/cast/ToFloat.md b/docs/content/en/functions/cast/ToFloat.md index acf70bc43..51bc908b6 100644 --- a/docs/content/en/functions/cast/ToFloat.md +++ b/docs/content/en/functions/cast/ToFloat.md @@ -1,20 +1,15 @@ --- title: cast.ToFloat -linkTitle: float -description: Casts a value to a decimal (base 10) floating point value. -categories: [functions] +description: Converts a value to a decimal floating-point number (base 10). +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [float] + related: + - functions/cast/ToInt + - functions/cast/ToString returnType: float64 signatures: [cast.ToFloat INPUT] -relatedFunctions: - - cast.ToFloat - - cast.ToInt - - cast.ToString aliases: [/functions/float] --- diff --git a/docs/content/en/functions/cast/ToInt.md b/docs/content/en/functions/cast/ToInt.md index b4a37cb6c..f82f029d5 100644 --- a/docs/content/en/functions/cast/ToInt.md +++ b/docs/content/en/functions/cast/ToInt.md @@ -1,20 +1,14 @@ --- title: cast.ToInt -linkTitle: int -description: Casts a value to a decimal (base 10) integer. -categories: [functions] +description: Converts a value to a decimal integer (base 10). keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [int] + related: + - functions/cast/ToFloat + - functions/cast/ToString returnType: int - signatures: [cast.ToInt INPUT] -relatedFunctions: - - cast.ToFloat - - cast.ToInt - - cast.ToString + signatures: [cast/ToInt INPUT] aliases: [/functions/int] --- @@ -55,5 +49,5 @@ With a hexadecimal (base 16) input: {{% note %}} Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros: -`{{ strings.TrimLeft "0" "0011" | int }} → 11` +`{{ strings/TrimLeft "0" "0011" | int }} → 11` {{% /note %}} diff --git a/docs/content/en/functions/cast/ToString.md b/docs/content/en/functions/cast/ToString.md index d677ecdbf..a701c9421 100644 --- a/docs/content/en/functions/cast/ToString.md +++ b/docs/content/en/functions/cast/ToString.md @@ -1,20 +1,15 @@ --- title: cast.ToString -linkTitle: string -description: Cast a value to a string. -categories: [functions] +description: Converts a value to a string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [string] + related: + - functions/cast/ToFloat + - functions/cast/ToInt returnType: string signatures: [cast.ToString INPUT] -relatedFunctions: - - cast.ToFloat - - cast.ToInt - - cast.ToString aliases: [/functions/string] --- diff --git a/docs/content/en/functions/cast/_index.md b/docs/content/en/functions/cast/_index.md new file mode 100644 index 000000000..82389237a --- /dev/null +++ b/docs/content/en/functions/cast/_index.md @@ -0,0 +1,12 @@ +--- +title: Cast functions +linkTitle: cast +description: Template functions to cast a value from one data type to another. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to cast a value from one data type to another. diff --git a/docs/content/en/functions/collections/After.md b/docs/content/en/functions/collections/After.md index e27c1507f..0cf25c7dd 100644 --- a/docs/content/en/functions/collections/After.md +++ b/docs/content/en/functions/collections/After.md @@ -1,20 +1,15 @@ --- title: collections.After -linkTitle: after description: Slices an array to the items after the Nth item. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [after] + related: + - functions/collections/First + - functions/collections/Last returnType: any signatures: [collections.After INDEX COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last aliases: [/functions/after] --- @@ -22,10 +17,20 @@ The following shows `after` being used in conjunction with the [`slice`]function ```go-html-template {{ $data := slice "one" "two" "three" "four" }} -{{ range after 2 $data }} - {{ . }} -{{ end }} -→ ["three", "four"] +<ul> + {{ range after 2 $data }} + <li>{{ . }}</li> + {{ end }} +</ul> +``` + +The template above is rendered to: + +```html +<ul> + <li>three</li> + <li>four</li> +</ul> ``` ## Example of `after` with `first`: 2nd–4th most recent articles @@ -35,32 +40,32 @@ You can use `after` in combination with the [`first`] function and Hugo's [power 1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter). 2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles. -{{< code file="layouts/section/articles.html" >}} +{{< code file=layouts/section/articles.html >}} {{ define "main" }} -<section class="row featured-article"> - <h2>Featured Article</h2> - {{ range first 1 .Pages.ByPublishDate.Reverse }} - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> -{{ end }} -</section> -<div class="row recent-articles"> - <h2>Recent Articles</h2> - {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} - <section class="recent-article"> - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> - </section> + <section class="row featured-article"> + <h2>Featured Article</h2> + {{ range first 1 .Pages.ByPublishDate.Reverse }} + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> {{ end }} -</div> + </section> + <div class="row recent-articles"> + <h2>Recent Articles</h2> + {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} + <section class="recent-article"> + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> + </section> + {{ end }} + </div> {{ end }} {{< /code >}} [`first`]: /functions/collections/first [list/section page]: /templates/section-templates -[lists]: /templates/lists/#order-content +[lists]: /templates/lists/#sort-content [`slice`]: /functions/collections/slice/ diff --git a/docs/content/en/functions/collections/Append.md b/docs/content/en/functions/collections/Append.md index 31657288f..5632dccfb 100644 --- a/docs/content/en/functions/collections/Append.md +++ b/docs/content/en/functions/collections/Append.md @@ -1,22 +1,17 @@ --- title: collections.Append -linkTitle: append description: Appends one or more elements to a slice and returns the resulting slice. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [append] + related: + - functions/collections/Merge + - functions/collections/Slice returnType: any signatures: - - COLLECTION | collections.Append ELEMENT [ELEMENT]... - - COLLECTION | collections.Append COLLECTION -relatedFunctions: - - collections.Append - - collections.Merge - - collections.Slice + - collections.Append ELEMENT [ELEMENT...] COLLECTION + - collections.Append COLLECTION1 COLLECTION2 aliases: [/functions/append] --- diff --git a/docs/content/en/functions/collections/Apply.md b/docs/content/en/functions/collections/Apply.md index 4d972b853..abd6fca77 100644 --- a/docs/content/en/functions/collections/Apply.md +++ b/docs/content/en/functions/collections/Apply.md @@ -1,18 +1,13 @@ --- title: collections.Apply -linkTitle: apply description: Returns a new collection with each element transformed by the given function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [apply] returnType: '[]any' signatures: [collections.Apply COLLECTION FUNCTION PARAM...] relatedFunctions: - - collections.Apply - collections.Delimit - collections.In - collections.Reverse @@ -25,7 +20,6 @@ The `apply` function takes three or more arguments, depending on the function be The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element. - ```go-html-template {{ $s := slice "hello" "world" }} diff --git a/docs/content/en/functions/collections/Complement.md b/docs/content/en/functions/collections/Complement.md index 28b7ded3d..b2a4b42a4 100644 --- a/docs/content/en/functions/collections/Complement.md +++ b/docs/content/en/functions/collections/Complement.md @@ -1,21 +1,16 @@ --- title: collections.Complement -linkTitle: complement description: Returns the elements of the last collection that are not in any of the others. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [complement] + related: + - functions/collections/Intersect + - functions/collections/SymDiff + - functions/collections/Union returnType: any - signatures: ['collections.Complement COLLECTION [COLLECTION]...'] -relatedFunctions: - - collections.Complement - - collections.Intersect - - collections.SymDiff - - collections.Union + signatures: ['collections.Complement COLLECTION [COLLECTION...]'] aliases: [/functions/complement] --- @@ -35,7 +30,6 @@ Make your code simpler to understand by using a [chained pipeline]: [chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines {{% /note %}} - ```go-html-template {{ $c3 | complement $c1 $c2 }} → [1 2] ``` @@ -65,7 +59,7 @@ To list everything except blog articles (`blog`) and frequently asked questions Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: [`where`]: /functions/collections/where -{{% /note %}} +{{% /note %}} ```go-html-template {{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }} diff --git a/docs/content/en/functions/collections/Delimit.md b/docs/content/en/functions/collections/Delimit.md index 0fc3ef537..6aea467ee 100644 --- a/docs/content/en/functions/collections/Delimit.md +++ b/docs/content/en/functions/collections/Delimit.md @@ -1,24 +1,19 @@ --- title: collections.Delimit -linkTitle: delimit description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [delimit] - returnType: template.HTML + related: + - functions/collections/Apply + - functions/collections/In + - functions/collections/Reverse + - functions/collections/Seq + - functions/collections/Slice + - functions/strings/Split + returnType: string signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] -relatedFunctions: - - collections.Apply - - collections.Delimit - - collections.In - - collections.Reverse - - collections.Seq - - collections.Slice - - strings.Split aliases: [/functions/delimit] --- @@ -26,8 +21,8 @@ Delimit a slice: ```go-html-template {{ $s := slice "b" "a" "c" }} -{{ delimit $s ", " }} → "b, a, c" -{{ delimit $s ", " " and "}} → "b, a and c" +{{ delimit $s ", " }} → b, a, c +{{ delimit $s ", " " and "}} → b, a and c ``` Delimit a map: @@ -38,6 +33,6 @@ The `delimit` function sorts maps by key, returning the values. ```go-html-template {{ $m := dict "b" 2 "a" 1 "c" 3 }} -{{ delimit $m ", " }} → "1, 2, 3" -{{ delimit $m ", " " and "}} → "1, 2 and 3" +{{ delimit $m ", " }} → 1, 2, 3 +{{ delimit $m ", " " and "}} → 1, 2 and 3 ``` diff --git a/docs/content/en/functions/collections/Dictionary.md b/docs/content/en/functions/collections/Dictionary.md index 28c387726..2e933aca9 100644 --- a/docs/content/en/functions/collections/Dictionary.md +++ b/docs/content/en/functions/collections/Dictionary.md @@ -1,40 +1,59 @@ --- title: collections.Dictionary -linkTitle: dict description: Creates a map from a list of key and value pairs. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [dict] + related: + - functions/collections/Group + - functions/collections/IndexFunction + - functions/collections/IsSet + - functions/collections/Where returnType: mapany - signatures: ['collections.Dictionary KEY VALUE [KEY VALUE]...'] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where + signatures: ['collections.Dictionary KEY VALUE [VALUE...]'] aliases: [/functions/dict] --- -`dict` is especially useful for passing more than one value to a partial template. +```go-html-template +{{ $m := dict "a" 1 "b" 2 }} +``` + +The above produces this data structure: + +```json +{ + "a": 1, + "b": 2 +} +``` + Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.: -```go-text-template +```go-html-template {{ $m := dict (slice "a" "b" "c") "value" }} ``` -## Example: using `dict` to pass multiple values to a `partial` +The above produces this data structure: + +```json +{ + "a": { + "b": { + "c": "value" + } + } +} +``` + +## Pass values to a partial template The partial below creates an SVG and expects `fill`, `height` and `width` from the caller: ### Partial definition -{{< code file="layouts/partials/svgs/external-links.svg" >}} +{{< code file=layouts/partials/svgs/external-links.svg >}} <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link"> <path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path> @@ -45,7 +64,7 @@ fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 3 The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial: -{{< code file="layouts/_default/list.html" >}} +{{< code file=layouts/_default/list.html >}} {{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }} {{< /code >}} diff --git a/docs/content/en/functions/collections/EchoParam.md b/docs/content/en/functions/collections/EchoParam.md deleted file mode 100644 index 7617eedd9..000000000 --- a/docs/content/en/functions/collections/EchoParam.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: collections.EchoParam -linkTitle: echoParam -description: Prints a parameter if it is set. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [echoParam] - returnType: any - signatures: [collections.EchoParam COLLECTION KEY] -relatedFunctions: [] -aliases: [/functions/echoparam] ---- - -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 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 will 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/docs/content/en/functions/collections/First.md b/docs/content/en/functions/collections/First.md index ddb045382..49a0362f5 100644 --- a/docs/content/en/functions/collections/First.md +++ b/docs/content/en/functions/collections/First.md @@ -1,53 +1,36 @@ --- title: collections.First -linkTitle: first -description: Slices an array to the first N elements. -categories: [functions] +description: Returns the given collection, limited to the first N elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [first] + related: + - functions/collections/After + - functions/collections/Last returnType: any - signatures: [collections.First LIMIT COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last + signatures: [collections.First N COLLECTION] aliases: [/functions/first] --- -`first` works in a similar manner to the [`limit` keyword in -SQL][limitkeyword]. It reduces the array to only the `first N` -elements. It takes the array and number of elements as input. - -`first` takes two arguments: -1. `number of elements` -2. `array` *or* `slice of maps or structs` - -{{< code file="layout/_default/section.html" >}} -{{ range first 10 .Pages }} - {{ .Render "summary" }} +```go-html-template +{{ range first 5 .Pages }} + {{ .Render "summary" }} {{ end }} -{{< /code >}} +``` -*Note: Exclusive to `first`, LIMIT can be '0' to return an empty array.* +Set `N` to zero to return an empty collection. -## `first` and `where` Together +```go-html-template +{{ $emptyPageCollection := first 0 .Pages}} +``` -Using `first` and [`where`] together can be very -powerful. Below snippet gets a list of posts only from [main -sections], sorts it by the `title` parameter, and then -ranges through only the first 5 posts in that list: +Use `first` and [`where`] together. -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }} - {{ .Content }} +```go-html-template +{{ range where .Pages "Section" "articles" | first 5 }} + {{ .Render "summary" }} {{ end }} -{{< /code >}} - +``` -[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php [`where`]: /functions/collections/where -[main sections]: /functions/collections/where#mainsections diff --git a/docs/content/en/functions/collections/Group.md b/docs/content/en/functions/collections/Group.md index 29220f1f7..74aa869df 100644 --- a/docs/content/en/functions/collections/Group.md +++ b/docs/content/en/functions/collections/Group.md @@ -1,26 +1,21 @@ --- title: collections.Group -linkTitle: group -description: Groups a list of pages. -categories: [functions] +description: Groups the given page collection by the given key. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [group] + related: + - functions/collections/Dictionary + - functions/collections/IndexFunction + - functions/collections/IsSet + - functions/collections/Where returnType: any - signatures: [PAGES | collections.Group KEY] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where + signatures: [collections.Group KEY PAGES] aliases: [/functions/group] --- -{{< code file="layouts/partials/groups.html" >}} +```go-html-template {{ $new := .Site.RegularPages | first 10 | group "New" }} {{ $old := .Site.RegularPages | last 10 | group "Old" }} {{ $groups := slice $new $old }} @@ -29,12 +24,12 @@ aliases: [/functions/group] <ul> {{ range .Pages }} <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li> {{ end }} </ul> {{ 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 be [paginated](/templates/pagination/#list-paginator-pages). diff --git a/docs/content/en/functions/collections/In.md b/docs/content/en/functions/collections/In.md index 57ffbd653..a3ec83d9b 100644 --- a/docs/content/en/functions/collections/In.md +++ b/docs/content/en/functions/collections/In.md @@ -1,21 +1,27 @@ --- title: collections.In -linkTitle: in -description: Reports whether an element is in an array or slice, or if a substring is in a string. +description: Reports whether the given value is a member of the given set. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [in] + related: + - functions/collections/Slice + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix returnType: bool - signatures: [collections.In SET ITEM] -relatedFunctions: - - collections.Slice + signatures: [collections.In SET VALUE] aliases: [/functions/in] --- +The `SET` can be an [array], [slice], or [string]. +[array]: /getting-started/glossary/#array +[slice]: /getting-started/glossary/#slice +[string]: /getting-started/glossary/#string ```go-html-template {{ $s := slice "a" "b" "c" }} diff --git a/docs/content/en/functions/collections/IndexFunction.md b/docs/content/en/functions/collections/IndexFunction.md index cd063f36e..e595d2b41 100644 --- a/docs/content/en/functions/collections/IndexFunction.md +++ b/docs/content/en/functions/collections/IndexFunction.md @@ -1,71 +1,66 @@ --- title: collections.Index -linkTitle: index description: Looks up the index(es) or key(s) of the data structure passed into it. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [index] + related: + - functions/collections/Dictionary + - functions/collections/Group + - functions/collections/IsSet + - functions/collections/Where returnType: any signatures: - collections.Index COLLECTION INDEXES - collections.Index COLLECTION KEYS -relatedFunctions: - - collections.Dictionary - - collections.EchoParam - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where aliases: [/functions/index,/functions/index-function] --- The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.: -```go-text-template +```go-html-template {{ $slice := slice "a" "b" "c" }} -{{ index $slice 1 }} => b +{{ index $slice 0 }} → a +{{ index $slice 1 }} → b + {{ $map := dict "a" 100 "b" 200 }} -{{ index $map "b" }} => 200 +{{ index $map "b" }} → 200 ``` The function takes multiple indices as arguments, and this can be used to get nested values, e.g.: -```go-text-template +```go-html-template {{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }} -{{ index $map "c" 1 }} => 20 +{{ index $map "c" 1 }} → 20 {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} -{{ index $map "c" "e" }} => 20 +{{ index $map "c" "e" }} → 20 ``` You may write multiple indices as a slice: -```go-text-template +```go-html-template {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} {{ $slice := slice "c" "e" }} -{{ index $map $slice }} => 20 +{{ index $map $slice }} → 20 ``` ## Example: load data from a path based on front matter parameters Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following: -``` -. -└── data - └── locations - ├── abilene.toml - ├── chicago.toml - ├── oslo.toml - └── provo.toml +```text +data/ + └── locations/ + ├── abilene.toml + ├── chicago.toml + ├── oslo.toml + └── provo.toml ``` Here is an example: -{{< code-toggle file="data/locations/oslo" copy=false >}} +{{< code-toggle file=data/locations/oslo >}} website = "https://www.oslo.kommune.no" pop_city = 658390 pop_metro = 1717900 @@ -73,7 +68,7 @@ pop_metro = 1717900 The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`: -{{< code-toggle file="content/articles/oslo.md" fm=true copy=false >}} +{{< code-toggle file=content/articles/oslo.md fm=true >}} title = "My Norwegian Vacation" location = "oslo" {{< /code-toggle >}} diff --git a/docs/content/en/functions/collections/Intersect.md b/docs/content/en/functions/collections/Intersect.md index 6a2c131b4..8bc60f8e1 100644 --- a/docs/content/en/functions/collections/Intersect.md +++ b/docs/content/en/functions/collections/Intersect.md @@ -1,26 +1,20 @@ --- title: collections.Intersect -linkTitle: intersect description: Returns the common elements of two arrays or slices, in the same order as the first array. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [intersect] + related: + - functions/collections/Complement + - functions/collections/SymDiff + - functions/collections/Union returnType: any signatures: [collections.Intersect SET1 SET2] -relatedFunctions: - - collections.Complement - - collections.Intersect - - collections.SymDiff - - collections.Union aliases: [/functions/intersect] --- -A useful example is to use it as `AND` filters when combined with where: -## AND filter in where query +A useful example is to use it as `AND` filters when combined with where: ```go-html-template {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} @@ -32,6 +26,5 @@ The above fetches regular pages not of `page` or `about` type unless they are pi See [union](/functions/collections/union) for `OR`. - [partials]: /templates/partials/ [single]: /templates/single-page-templates/ diff --git a/docs/content/en/functions/collections/IsSet.md b/docs/content/en/functions/collections/IsSet.md index 93fb9f8f6..76b336ae3 100644 --- a/docs/content/en/functions/collections/IsSet.md +++ b/docs/content/en/functions/collections/IsSet.md @@ -1,28 +1,25 @@ --- title: collections.IsSet -linkTitle: isset description: Reports whether the key exists within the collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [isset] + related: + - functions/collections/Dictionary + - functions/collections/Group + - functions/collections/IndexFunction + - functions/collections/Where + - functions/go-template/if + - functions/go-template/with returnType: bool signatures: [collections.IsSet COLLECTION KEY] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where aliases: [/functions/isset] --- For example, consider this site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [params] showHeroImage = false {{< /code-toggle >}} diff --git a/docs/content/en/functions/collections/KeyVals.md b/docs/content/en/functions/collections/KeyVals.md index f3e0c559d..3d21ca6fd 100644 --- a/docs/content/en/functions/collections/KeyVals.md +++ b/docs/content/en/functions/collections/KeyVals.md @@ -1,21 +1,20 @@ --- title: collections.KeyVals -linkTitle: keyVals description: Returns a KeyVals struct. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [keyVals] - returnType: KeyValues + related: + - methods/pages/Related + returnType: types.KeyValues signatures: [collections.KeyVals KEY VALUES...] -relatedFunctions: [] aliases: [/functions/keyvals] --- -The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the `.Related` method on the `Page` object. +The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object. + +[`Related`]: /methods/pages/related See [related content](/content-management/related). @@ -39,7 +38,6 @@ The resulting data structure is: To extract the key and values: ```go-html-template - {{ $kv.Key }} → foo {{ $kv.Values }} → [a b c] ``` diff --git a/docs/content/en/functions/collections/Last.md b/docs/content/en/functions/collections/Last.md index 3f8496354..8219e120d 100644 --- a/docs/content/en/functions/collections/Last.md +++ b/docs/content/en/functions/collections/Last.md @@ -1,20 +1,15 @@ --- title: collections.Last -linkTitle: last -description: Slices an array to the last N elements. -categories: [functions] +description: Returns the given collection, limited to the last N elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [last] + related: + - functions/collections/After + - functions/collections/First returnType: any - signatures: [collections.Last INDEX COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last + signatures: [collections.Last N COLLECTION] aliases: [/functions/last] --- @@ -23,3 +18,17 @@ aliases: [/functions/last] {{ .Render "summary" }} {{ end }} ``` + +Set `N` to zero to return an empty collection. + +```go-html-template +{{ $emptyPageCollection := last 0 .Pages}} +``` + +Use `last` and [`where`] together. + +```go-html-template +{{ range where .Pages "Section" "articles" | last 5 }} + {{ .Render "summary" }} +{{ end }} +``` diff --git a/docs/content/en/functions/collections/Merge.md b/docs/content/en/functions/collections/Merge.md index 908f1738a..3f5208cfc 100644 --- a/docs/content/en/functions/collections/Merge.md +++ b/docs/content/en/functions/collections/Merge.md @@ -1,19 +1,14 @@ --- title: collections.Merge -linkTitle: merge description: Returns the result of merging two or more maps. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [merge] + related: + - functions/collections/Append returnType: any signatures: [collections.Merge MAP MAP...] -relatedFunctions: - - collections.Append - - collections.Merge aliases: [/functions/merge] --- diff --git a/docs/content/en/functions/collections/NewScratch.md b/docs/content/en/functions/collections/NewScratch.md index 0df90bb96..793b2b4b5 100644 --- a/docs/content/en/functions/collections/NewScratch.md +++ b/docs/content/en/functions/collections/NewScratch.md @@ -1,22 +1,115 @@ --- title: collections.NewScratch -linkTitle: newScratch -description: Creates a new Scratch which can be used to store values in a thread safe way. -categories: [functions] +description: Returns a locally scoped "scratch pad" to store and manipulate data. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [newScratch] - returnType: Scratch + related: + - methods/page/scratch + - methods/page/store + returnType: maps.Scratch signatures: [collections.NewScratch ] -relatedFunctions: [] --- +The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method. + +[`Scratch`]: /methods/page/scratch +[`Store`]: /methods/page/store +[scratch pad]: /getting-started/glossary/#scratch-pad + +## Methods + +Set +: Sets the value of a given key. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +``` + +Get +: Gets the value of a given key. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Get "greeting" }} → Hello +``` + +Add +: Adds a given value to existing value(s) of the given key. + +: For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Add "greeting" "Welcome" }} +{{ $s.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "total" 3 }} +{{ $s.Add "total" 7 }} +{{ $s.Get "total" }} → 10 +``` + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greetings" (slice "Hello") }} +{{ $s.Add "greetings" (slice "Welcome" "Cheers") }} +{{ $s.Get "greetings" }} → [Hello Welcome Cheers] +``` + +SetInMap +: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour] +``` + +DeleteInMap +: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.DeleteInMap "greetings" "english" }} +{{ $s.Get "greetings" }} → map[french:Bonjour] +``` + +GetSortedMapValues +: Returns an array of values from `key` sorted by `mapKey`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour] +``` + +Delete +: Removes the given key. + ```go-html-template -{{ $scratch := newScratch }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Get "b" }} → 4 +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Delete "greeting" }} +``` + +Values +: Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} + +{{ $map := $s.Values }} ``` diff --git a/docs/content/en/functions/collections/Querify.md b/docs/content/en/functions/collections/Querify.md index c94d51133..e195c417f 100644 --- a/docs/content/en/functions/collections/Querify.md +++ b/docs/content/en/functions/collections/Querify.md @@ -1,19 +1,15 @@ --- title: collections.Querify -linkTitle: querify description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [querify] returnType: string signatures: - - collections.Querify KEY VALUE [KEY VALUE]... + - collections.Querify VALUE [VALUE...] - collections.Querify COLLECTION -relatedFunctions: +related: - collections.Querify - urlquery aliases: [/functions/querify] diff --git a/docs/content/en/functions/collections/Reverse.md b/docs/content/en/functions/collections/Reverse.md index 521adc6f2..12c964c76 100644 --- a/docs/content/en/functions/collections/Reverse.md +++ b/docs/content/en/functions/collections/Reverse.md @@ -1,16 +1,13 @@ --- title: collections.Reverse description: Reverses the order of a collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] returnType: any signatures: [collections.Reverse COLLECTION] -relatedFunctions: +related: - collections.Apply - collections.Delimit - collections.In @@ -20,7 +17,6 @@ relatedFunctions: aliases: [/functions/collections.reverse] --- - ```go-html-template {{ slice 2 1 3 | collections.Reverse }} → [3 1 2] ``` diff --git a/docs/content/en/functions/collections/Seq.md b/docs/content/en/functions/collections/Seq.md index 65ff1432f..e7430e0d0 100644 --- a/docs/content/en/functions/collections/Seq.md +++ b/docs/content/en/functions/collections/Seq.md @@ -1,20 +1,16 @@ --- title: collections.Seq -linkTitle: seq description: Returns a slice of integers. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [seq] returnType: '[]int' signatures: - collections.Seq LAST - collections.Seq FIRST LAST - collections.Seq FIRST INCREMENT LAST -relatedFunctions: +related: - collections.Apply - collections.Delimit - collections.In @@ -40,3 +36,11 @@ Iterate over a sequence of integers: {{ end }} {{ $product }} → 24 ``` + +The example above is contrived. To calculate the product of 2 or more numbers, use the [`math.Product`] function: + +```go-html-template +{{ math.Product (seq 4) }} → 24 +``` + +[`math.Product`]: /functions/math/product diff --git a/docs/content/en/functions/collections/Shuffle.md b/docs/content/en/functions/collections/Shuffle.md index 8388d5332..18b8cc664 100644 --- a/docs/content/en/functions/collections/Shuffle.md +++ b/docs/content/en/functions/collections/Shuffle.md @@ -1,18 +1,13 @@ --- title: collections.Shuffle -linkTitle: shuffle description: Returns a random permutation of a given array or slice. -keywords: [ordering] -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [shuffle] returnType: any signatures: [collections.Shuffle COLLECTION] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort diff --git a/docs/content/en/functions/collections/Slice.md b/docs/content/en/functions/collections/Slice.md index a30800ed3..e24b394ca 100644 --- a/docs/content/en/functions/collections/Slice.md +++ b/docs/content/en/functions/collections/Slice.md @@ -1,17 +1,13 @@ --- title: collections.Slice -linkTitle: slice -description: Creates a slice (array) of all passed arguments. -categories: [functions] +description: Creates a slice of all passed arguments. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [slice] returnType: any signatures: [collections.Slice ITEM...] -relatedFunctions: +related: - collections.Append - collections.Apply - collections.Delimit @@ -22,8 +18,6 @@ relatedFunctions: aliases: [/functions/slice] --- -One use case is the concatenation of elements in combination with the [`delimit` function]: - ```go-html-template {{ $s := slice "a" "b" "c" }} {{ $s }} → [a b c] diff --git a/docs/content/en/functions/collections/Sort.md b/docs/content/en/functions/collections/Sort.md index bb0f82cde..6b9ea2c34 100644 --- a/docs/content/en/functions/collections/Sort.md +++ b/docs/content/en/functions/collections/Sort.md @@ -1,17 +1,13 @@ --- title: collections.Sort -linkTitle: sort description: Sorts slices, maps, and page collections. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sort] returnType: any signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort @@ -27,7 +23,7 @@ The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default The examples below assume this site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params] grades = ['b','a','c'] {{< /code-toggle >}} @@ -36,10 +32,10 @@ grades = ['b','a','c'] Sort slice elements in ascending order using either of these constructs: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ sort site.Params.grades }} → [a b c] {{ sort site.Params.grades "value" "asc" }} → [a b c] -{{< /code >}} +``` In the examples above, `value` is the `KEY` representing the value of the slice element. @@ -47,9 +43,9 @@ In the examples above, `value` is the `KEY` representing the value of the slice Sort slice elements in descending order: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ sort site.Params.grades "value" "desc" }} → [c b a] -{{< /code >}} +``` In the example above, `value` is the `KEY` representing the value of the slice element. @@ -57,7 +53,7 @@ In the example above, `value` is the `KEY` representing the value of the slice e The examples below assume this site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params.authors.a] firstName = "Marius" lastName = "Pontmercy" @@ -77,7 +73,7 @@ When sorting maps, the `KEY` argument must be lowercase. Sort map objects in ascending order using either of these constructs: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ range sort site.Params.authors "firstname" }} {{ .firstName }} {{ end }} @@ -85,7 +81,7 @@ Sort map objects in ascending order using either of these constructs: {{ range sort site.Params.authors "firstname" "asc" }} {{ .firstName }} {{ end }} -{{< /code >}} +``` These produce: @@ -97,11 +93,11 @@ Jean Marius Victor Sort map objects in descending order: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ range sort site.Params.authors "firstname" "desc" }} {{ .firstName }} {{ end }} -{{< /code >}} +``` This produces: @@ -111,25 +107,16 @@ Victor Marius Jean ## Sort a page collection -Although you can use the `sort` function to sort a page collection, Hugo provides [built-in methods for sorting page collections] by: +{{% note %}} +Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. -- weight -- linktitle -- title -- front matter parameter -- date -- expiration date -- last modified date -- publish date -- length +[sorting and grouping methods]: /methods/pages +{{% /note %}} In this contrived example, sort the site's regular pages by `.Type` in descending order: -{{< code file="layouts/_default/home.html" copy=false >}} +```go-html-template {{ range sort site.RegularPages "Type" "desc" }} - <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} -{{< /code >}} - - -[built-in methods for sorting page collections]: /templates/lists/#order-content +``` diff --git a/docs/content/en/functions/collections/SymDiff.md b/docs/content/en/functions/collections/SymDiff.md index ea9f20123..828c10ce5 100644 --- a/docs/content/en/functions/collections/SymDiff.md +++ b/docs/content/en/functions/collections/SymDiff.md @@ -1,17 +1,13 @@ --- title: collections.SymDiff -linkTitle: symdiff description: Returns the symmetric difference of two collections. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [symdiff] returnType: any signatures: [COLLECTION | collections.SymDiff COLLECTION] -relatedFunctions: +related: - collections.Complement - collections.Intersect - collections.SymDiff @@ -25,4 +21,4 @@ Example: {{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4] ``` -Also see https://en.wikipedia.org/wiki/Symmetric_difference +Also see <https://en.wikipedia.org/wiki/Symmetric_difference>. diff --git a/docs/content/en/functions/collections/Union.md b/docs/content/en/functions/collections/Union.md index 119da6fb4..e2eb61313 100644 --- a/docs/content/en/functions/collections/Union.md +++ b/docs/content/en/functions/collections/Union.md @@ -1,17 +1,13 @@ --- title: collections.Union -linkTitle: union -description: Given two arrays or slices, returns a new array that contains the elements or objects that belong to either or both arrays/slices. -categories: [functions] +description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [union] returnType: any signatures: [collections.Union SET1 SET2] -relatedFunctions: +related: - collections.Complement - collections.Intersect - collections.SymDiff @@ -19,7 +15,7 @@ relatedFunctions: aliases: [/functions/union] --- -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). +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. ```go-html-template {{ union (slice 1 2 3) (slice 3 4 5) }} diff --git a/docs/content/en/functions/collections/Uniq.md b/docs/content/en/functions/collections/Uniq.md index 1b0a8f8f4..8266142ac 100644 --- a/docs/content/en/functions/collections/Uniq.md +++ b/docs/content/en/functions/collections/Uniq.md @@ -1,17 +1,13 @@ --- title: collections.Uniq -linkTitle: uniq -description: Takes in a slice or array and returns a slice with duplicate elements removed. -categories: [functions] +description: Returns the given collection, removing duplicate elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [uniq] returnType: any signatures: [collections.Uniq COLLECTION] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort @@ -19,7 +15,6 @@ relatedFunctions: aliases: [/functions/uniq] --- - ```go-html-template {{ slice 1 3 2 1 | uniq }} → [1 3 2] ``` diff --git a/docs/content/en/functions/collections/Where.md b/docs/content/en/functions/collections/Where.md index df6cec89f..e053ed3d5 100644 --- a/docs/content/en/functions/collections/Where.md +++ b/docs/content/en/functions/collections/Where.md @@ -1,17 +1,13 @@ --- title: collections.Where -linkTitle: where -description: Filters an array to only the elements containing a matching value for a given field. -categories: [functions] +description: Returns the given collection, removing elements that do not satisfy the comparison condition. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [where] returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] MATCH'] -relatedFunctions: + signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] +related: - collections.Dictionary - collections.Group - collections.Index @@ -21,170 +17,434 @@ aliases: [/functions/where] toc: true --- -`where` filters an array to only the elements containing a matching -value for a given field. +The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments: -It works in a similar manner to the [`where` keyword in -SQL][wherekeyword]. +```text +collections.Where COLLECTION KEY [OPERATOR] VALUE + -------------------- + comparison condition +``` + +Hugo will test for equality if you do not provide an `OPERATOR` argument. For example: ```go-html-template -{{ range where .Pages "Section" "foo" }} - {{ .Content }} -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "books" }} +{{ $books := where .Site.Data.books "genres" "suspense" }} ``` -It can be used by dot-chaining the second argument to refer to a nested element of a value. +## Arguments -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -series: golang -{{< /code-toggle >}} +The where function takes three or four arguments. The `OPERATOR` argument is optional. -```go-html-template -{{ range where .Site.Pages "Params.series" "golang" }} - {{ .Content }} -{{ end }} -``` +COLLECTION +: (`any`) Typically a page collection or a [slice] of [maps]. -It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`. +[maps]: /getting-started/glossary/#map +[slice]: /getting-started/glossary/#slice + +KEY +: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below: ```go-html-template -{{ range where .Pages "Section" "!=" "foo" }} - {{ .Content }} -{{ end }} +{{ $result := where .Site.RegularPages "Params.foo" "bar" }} ``` -The following logical operators are available with `where`: +[chain]: /getting-started/glossary/#chain + +OPERATOR +: (`string`) The logical comparison [operator](#operators). + +VALUE +: (`any`) The value with which to compare. The values to compare must have comparable data types. For example: + +Comparison|Result +:--|:-- +`"123" "eq" "123"`|`true` +`"123" "eq" 123`|`false` +`false "eq" "false"`|`false` +`false "eq" false`|`true` + +When one or both of the values to compare is a slice, use the `in`, `not in` or `intersect` operators as described below. + +## Operators + +Use any of the following logical operators: `=`, `==`, `eq` -: `true` if a given field value equals a matching value +: (`bool`) Reports whether the given field value is equal to `VALUE`. `!=`, `<>`, `ne` -: `true` if a given field value doesn't equal a matching value +: (`bool`) Reports whether the given field value is not equal to `VALUE`. `>=`, `ge` -: `true` if a given field value is greater than or equal to a matching value +: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`. `>`, `gt` -: `true` if a given field value is greater than a matching value +: `true` Reports whether the given field value is greater than `VALUE`. `<=`, `le` -: `true` if a given field value is lesser than or equal to a matching value +: (`bool`) Reports whether the given field value is less than or equal to `VALUE`. `<`, `lt` -: `true` if a given field value is lesser than a matching value +: (`bool`) Reports whether the given field value is less than `VALUE`. `in` -: `true` if a given field value is included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `not in` -: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `intersect` -: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect]. +: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect). + +`like` {{< new-in 0.116.0 >}} +: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. + +{{% note %}} +The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. +{{% /note %}} + +## String comparison -`like` -: `true` if a given field value matches a regular expression. Use the `like` operator to compare `string` values. Returns `false` when comparing other data types to the regular expression. +Compare the value of the given field to a [`string`]: + +[`string`]: /getting-started/glossary/#string -## Use `where` with boolean values -When using booleans you should not put quotation marks. ```go-html-template -{{ range where .Pages "Draft" true }} - <p>{{ .Title }}</p> -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "eq" "books" }} +{{ $pages := where .Site.RegularPages "Section" "ne" "books" }} ``` -## Use `where` with `intersect` +## Numeric comparison + +Compare the value of the given field to an [`int`] or [`float`]: + +[`int`]: /getting-started/glossary/#int +[`float`]: /getting-started/glossary/#float ```go-html-template -{{ range where .Site.Pages "Params.tags" "intersect" .Params.tags }} - {{ if ne .Permalink $.Permalink }} - {{ .Render "summary" }} - {{ end }} -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.price" "eq" 42 }} +{{ $pages := where $sectionPages "Params.price" "ne" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "ge" 42 }} +{{ $pages := where $sectionPages "Params.price" "gt" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "le" 42 }} +{{ $pages := where $sectionPages "Params.price" "lt" 42.67 }} ``` -You can also put the returned value of the `where` clauses into a variable: +## Boolean comparison -{{< code file="where-intersect-variables.html" >}} -{{ $v1 := where .Site.Pages "Params.a" "v1" }} -{{ $v2 := where .Site.Pages "Params.b" "v2" }} -{{ $filtered := $v1 | intersect $v2 }} -{{ range $filtered }} -{{ end }} -{{< /code >}} +Compare the value of the given field to a [`bool`]: -## Use `where` with `like` +[`bool`]: /getting-started/glossary/#bool -This example matches pages where the "foo" parameter begins with "ab": +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.fiction" "eq" true }} +{{ $pages := where $sectionPages "Params.fiction" "eq" false }} +{{ $pages := where $sectionPages "Params.fiction" "ne" true }} +{{ $pages := where $sectionPages "Params.fiction" "ne" false }} +``` + +## Member comparison + +Compare a [`scalar`] to a [`slice`]. + +[`scalar`]: /getting-started/glossary/#scalar +[`slice`]: /getting-started/glossary/#slice + +For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow": ```go-html-template -{{ range where site.RegularPages "Params.foo" "like" `^ab` }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} + +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "in" $colors }} ``` -{{% readfile file="/functions/_common/regular-expressions.md" %}} +To return a collection of pages where the "color" page parameter is neither "red" nor "yellow": -## Use `where` with `first` +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} -Using `first` and `where` together can be very -powerful. Below snippet gets a list of posts only from [**main -sections**](#mainsections), sorts it using the [default -ordering](/templates/lists/) for lists (i.e., `weight => date`), and -then ranges through only the first 5 posts in that list: +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "not in" $colors }} +``` -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }} - {{ .Content }} -{{ end }} -{{< /code >}} +## Intersection comparison + +Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms. + +For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": + +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $genres := slice "suspense" "romance" }} +{{ $pages := where $sectionPages "Params.genres" "intersect" $genres }} +``` + +## Regular expression comparison -## Nest `where` clauses +{{< new-in 0.116.0 >}} -You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured: +To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor": ```go-html-template -{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }} +{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} ``` -## Unset fields +{{% include "functions/_common/regular-expressions.md" %}} + +{{% note %}} +Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. +{{% /note %}} -Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`. +## Date comparison -This can be useful to filter a small amount of pages from a large pool. Instead of setting a field on all pages, you can set that field on required pages only. +### Predefined dates -Only the following operators are available for `nil` +There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons. -* `=`, `==`, `eq`: True if the given field is not set. -* `!=`, `<>`, `ne`: True if the given field is set. +[`date`]: /methods/page/date +[`publishdate`]: /methods/page/publishdate +[`lastmod`]: /methods/page/lastmod +[`expirydate`]: /methods/page/expirydate +[`time.Time`]: https://pkg.go.dev/time#Time + +For example, to return a collection of pages that were created before the current year: ```go-html-template -{{ range where .Pages "Params.specialpost" "!=" nil }} - {{ .Content }} +{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }} +{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }} +``` + +### Custom dates + +With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON). + +{{% note %}} +Using TOML for pages with custom front matter dates enables precise date comparisons. +{{% /note %}} + +With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. + +In the TOML example below, note that the event date is not quoted. + +{{< code file="content/events/2024-user-conference.md" >}} ++++ +title = '2024 User Conference" +eventDate = 2024-04-01 ++++ +{{< /code >}} + +To return a collection of future events: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "events" }} +{{ $futureEvents := where $events "Params.eventDate" "gt" now }} +``` + +When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "events" }} +{{ $futureEvents := slice }} +{{ range $events }} + {{ if gt (time.AsTime .Params.eventDate) now }} + {{ $futureEvents = $futureEvents | append . }} + {{ end }} {{ end }} ``` -## Portable `where` filters -- `site.Params.mainSections` {#mainsections} +## Nil comparison -**This is especially important for themes.** +To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`: + +```go-html-template +{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }} +``` -To list the most relevant pages on the front page or similar, you -should use the `site.Params.mainSections` list instead of comparing -section names to hard-coded values like `"posts"` or `"post"`. +To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`: ```go-html-template -{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }} +{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }} ``` -If the user has not set this configuration parameter in their site configuration, it will default to the *section with the most pages*. +In both examples above, note that `nil` is not quoted. + +## Nested comparison -The user can override the default: +These are equivalent: -{{< code-toggle file="hugo" >}} +```go-html-template +{{ $pages := where .Site.RegularPages "Type" "tutorials" }} +{{ $pages = where $pages "Params.level" "eq" "beginner" }} +``` + +```go-html-template +{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }} +``` + +## Portable section comparison + +Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object. + +[`MainSections`]: /methods/site/mainsections + +```go-html-template +{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} +``` + +With this construct, a theme author can instruct users to specify their main sections in the site configuration: + +{{< code-toggle file=hugo >}} [params] - mainSections = ["blog", "docs"] +mainSections = ['blog','galleries'] {{< /code-toggle >}} -[intersect]: /functions/collections/intersect -[wherekeyword]: https://www.techonthenet.com/sql/where.php +If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages. + +## Boolean/undefined comparison + +Consider this site content: + +```text +content/ +├── posts/ +│ ├── _index.md +│ ├── post-1.md <-- front matter: exclude = false +│ ├── post-2.md <-- front matter: exclude = true +│ └── post-3.md <-- front matter: exclude not defined +└── _index.md +``` + +The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result. + +### Equality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> +</ul> +``` + +### Inequality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +To exclude a page with an undefined field from a boolean _inequality_ test: + +1. Create a collection using a boolean comparison +2. Create a collection using a nil comparison +3. Subtract the second collection from the first collection using the [`collections.Complement`] function. + +[`collections.Complement`]: /functions/collections/complement + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 2</a></li> +</ul> +``` diff --git a/docs/content/en/functions/collections/_index.md b/docs/content/en/functions/collections/_index.md new file mode 100644 index 000000000..51981f79b --- /dev/null +++ b/docs/content/en/functions/collections/_index.md @@ -0,0 +1,12 @@ +--- +title: Collections functions +linkTitle: collections +description: Template functions to work with arrays, slices, maps, and page collections. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with arrays, slices, maps, and page collections. diff --git a/docs/content/en/functions/compare/Cond.md b/docs/content/en/functions/compare/Conditional.md index 4b92a893c..6d693770d 100644 --- a/docs/content/en/functions/compare/Cond.md +++ b/docs/content/en/functions/compare/Conditional.md @@ -1,19 +1,14 @@ --- title: compare.Conditional -linkTitle: cond description: Returns one of two arguments depending on the value of the control argument. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [cond] + related: + - functions/compare/Default returnType: any signatures: [compare.Conditional CONTROL ARG1 ARG2] -relatedFunctions: - - compare.Conditional - - compare.Default aliases: [/functions/cond] --- @@ -21,14 +16,14 @@ The CONTROL argument is a boolean value that indicates whether the function shou ```go-html-template {{ $qty := 42 }} -{{ cond (le $qty 3) "few" "many" }} → "many" +{{ cond (le $qty 3) "few" "many" }} → many ``` The CONTROL argument must be either `true` or `false`. To cast a non-boolean value to boolean, pass it through the `not` operator twice. ```go-html-template -{{ cond (42 | not | not) "truthy" "falsy" }} → "truthy" -{{ cond ("" | not | not) "truthy" "falsy" }} → "falsy" +{{ cond (42 | not | not) "truthy" "falsy" }} → truthy +{{ cond ("" | not | not) "truthy" "falsy" }} → falsy ``` {{% note %}} @@ -38,7 +33,6 @@ Unlike [ternary operators] in other languages, the `cond` function does not perf [ternary operators]: https://en.wikipedia.org/wiki/Ternary_conditional_operator {{% /note %}} - Due to the absence of short-circuit evaluation, these examples throw an error: ```go-html-template diff --git a/docs/content/en/functions/compare/Default.md b/docs/content/en/functions/compare/Default.md index 24ad37ef2..1e6bd7968 100644 --- a/docs/content/en/functions/compare/Default.md +++ b/docs/content/en/functions/compare/Default.md @@ -1,88 +1,48 @@ --- title: compare.Default -linkTitle: default -description: Allows setting a default value that can be returned if a first value is not set. -categories: [functions] +description: Returns the second argument if set, else the first argument. keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [default] + related: + - functions/compare/Conditional + - functions/go-template/Or returnType: any signatures: [compare.Default DEFAULT INPUT] -relatedFunctions: - - compare.Conditional - - compare.Default aliases: [/functions/default] --- -`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: +The `default` function returns the second argument if set, else the first argument. -* non-zero for numeric types and times -* non-zero length for strings, arrays, slices, and maps -* any boolean or struct value -* non-nil for any other types +{{% note %}} +When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. -`default` function examples reference the following content page: +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -{{< code file="content/posts/default-function-example.md" >}} ---- -title: Sane Defaults -seo_title: -date: 2017-02-18 -font: -oldparam: The default function helps make your templating DRYer. -newparam: ---- -{{< /code >}} - -`default` can be written in more than one way: - -```go-html-template -{{ .Params.font | default "Roboto" }} -{{ default "Roboto" .Params.font }} -``` - -Both of the above `default` function calls return `Roboto`. - -A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation: - -```go-html-template -{{ $old := .Params.oldparam }} -<p>{{ .Params.newparam | default $old }}</p> -``` - -Which would return: - -```html -<p>The default function helps make your templating DRYer.</p> -``` - -And then using dot notation - -```go-html-template -<title>{{ .Params.seo_title | default .Title }}</title> -``` - -Which would return - -```html -<title>Sane Defaults</title> -``` +To set a default value based on truthiness, use the [`or`] operator instead. -The following have equivalent return values but are far less terse. This demonstrates the utility of `default`: +[`or`]: /functions/go-template/or +{{% /note %}} -Using `if`: +The `default` function returns the second argument if set: ```go-html-template -<title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title> -=> Sane Defaults +{{ default 42 1 }} → 1 +{{ default 42 "foo" }} → foo +{{ default 42 (dict "k" "v") }} → map[k:v] +{{ default 42 (slice "a" "b") }} → [a b] +{{ default 42 true }} → true + +<!-- As noted above, the boolean "false" is considered set --> +{{ default 42 false }} → false ``` -Using `with`: +The `default` function returns the first argument if the second argument is not set: ```go-html-template -<title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title> -=> Sane Defaults +{{ default 42 0 }} → 42 +{{ default 42 "" }} → 42 +{{ default 42 dict }} → 42 +{{ default 42 slice }} → 42 +{{ default 42 <nil> }} → 42 ``` diff --git a/docs/content/en/functions/compare/Eq.md b/docs/content/en/functions/compare/Eq.md index 010fc51b3..49350e676 100644 --- a/docs/content/en/functions/compare/Eq.md +++ b/docs/content/en/functions/compare/Eq.md @@ -1,23 +1,18 @@ --- title: compare.Eq -linkTitle: eq description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [eq] + related: + - functions/compare/Ge + - functions/compare/Gt + - functions/compare/Le + - functions/compare/Lt + - functions/compare/Ne returnType: bool signatures: ['compare.Eq ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/eq] --- diff --git a/docs/content/en/functions/compare/Ge.md b/docs/content/en/functions/compare/Ge.md index 6bb48dd00..479ecf990 100644 --- a/docs/content/en/functions/compare/Ge.md +++ b/docs/content/en/functions/compare/Ge.md @@ -1,23 +1,18 @@ --- title: compare.Ge -linkTitle: ge description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [ge] + related: + - functions/compare/Eq + - functions/compare/Gt + - functions/compare/Le + - functions/compare/Lt + - functions/compare/Ne returnType: bool signatures: ['compare.Ge ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/ge] --- diff --git a/docs/content/en/functions/compare/Gt.md b/docs/content/en/functions/compare/Gt.md index 4691718ef..0af289ce2 100644 --- a/docs/content/en/functions/compare/Gt.md +++ b/docs/content/en/functions/compare/Gt.md @@ -1,23 +1,18 @@ --- title: compare.Gt -linkTitle: gt description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [gt] + related: + - functions/compare/Eq + - functions/compare/Ge + - functions/compare/Le + - functions/compare/Lt + - functions/compare/Ne returnType: bool signatures: ['compare.Gt ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/gt] --- diff --git a/docs/content/en/functions/compare/Le.md b/docs/content/en/functions/compare/Le.md index 792ea6ce6..319d376f6 100644 --- a/docs/content/en/functions/compare/Le.md +++ b/docs/content/en/functions/compare/Le.md @@ -1,23 +1,18 @@ --- title: compare.Le -linkTitle: le description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [le] + related: + - functions/compare/Eq + - functions/compare/Ge + - functions/compare/Gt + - functions/compare/Lt + - functions/compare/Ne returnType: bool signatures: ['compare.Le ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/le] --- diff --git a/docs/content/en/functions/compare/Lt.md b/docs/content/en/functions/compare/Lt.md index 537c23b6f..3fe8f1d2c 100644 --- a/docs/content/en/functions/compare/Lt.md +++ b/docs/content/en/functions/compare/Lt.md @@ -1,23 +1,18 @@ --- title: compare.Lt -linkTitle: lt description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [lt] + related: + - functions/compare/Eq + - functions/compare/Ge + - functions/compare/Gt + - functions/compare/Le + - functions/compare/Ne returnType: bool signatures: ['compare.Lt ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/lt] --- diff --git a/docs/content/en/functions/compare/Ne.md b/docs/content/en/functions/compare/Ne.md index 412f43d49..2d9f826fc 100644 --- a/docs/content/en/functions/compare/Ne.md +++ b/docs/content/en/functions/compare/Ne.md @@ -1,23 +1,18 @@ --- title: compare.Ne -linkTitle: ne description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [ne] + related: + - functions/compare/Eq + - functions/compare/Ge + - functions/compare/Gt + - functions/compare/Le + - functions/compare/Lt returnType: bool signatures: ['compare.Ne ARG1 ARG2 [ARG...]'] -relatedFunctions: - - compare.Eq - - compare.Ge - - compare.Gt - - compare.Le - - compare.Lt - - compare.Ne aliases: [/functions/ne] --- diff --git a/docs/content/en/functions/compare/_index.md b/docs/content/en/functions/compare/_index.md new file mode 100644 index 000000000..a9b3a7b27 --- /dev/null +++ b/docs/content/en/functions/compare/_index.md @@ -0,0 +1,12 @@ +--- +title: Compare functions +linkTitle: compare +description: Template functions to compare two or more values. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to compare two or more values. diff --git a/docs/content/en/functions/crypto/FNV32a.md b/docs/content/en/functions/crypto/FNV32a.md index 7a7fe303e..5c091ebee 100644 --- a/docs/content/en/functions/crypto/FNV32a.md +++ b/docs/content/en/functions/crypto/FNV32a.md @@ -1,21 +1,17 @@ --- title: crypto.FNV32a description: Returns the FNV (Fowler–Noll–Vo) 32 bit hash of a given string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: int signatures: [crypto.FNV32a STRING] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/crypto.fnv32a] --- diff --git a/docs/content/en/functions/crypto/HMAC.md b/docs/content/en/functions/crypto/HMAC.md index e58619b38..1906689a2 100644 --- a/docs/content/en/functions/crypto/HMAC.md +++ b/docs/content/en/functions/crypto/HMAC.md @@ -1,22 +1,17 @@ --- title: crypto.HMAC -linkTitle: hmac description: Returns a cryptographic hash that uses a key to sign a message. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hmac] + related: + - functions/crypto/FNV32a + - functions/crypto/MD5 + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: string signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/hmac] --- diff --git a/docs/content/en/functions/crypto/MD5.md b/docs/content/en/functions/crypto/MD5.md index 9415e015c..ba44660df 100644 --- a/docs/content/en/functions/crypto/MD5.md +++ b/docs/content/en/functions/crypto/MD5.md @@ -1,28 +1,22 @@ --- title: crypto.MD5 -linkTitle: md5 -description: hashes the given input and returns its MD5 checksum. -categories: [functions] +description: Hashes the given input and returns its MD5 checksum encoded to a hexadecimal string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [md5] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/SHA1 + - functions/crypto/SHA256 returnType: string signatures: [crypto.MD5 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/md5] --- ```go-html-template {{ 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/docs/content/en/functions/crypto/SHA1.md b/docs/content/en/functions/crypto/SHA1.md index 6269efe38..204ff0384 100644 --- a/docs/content/en/functions/crypto/SHA1.md +++ b/docs/content/en/functions/crypto/SHA1.md @@ -1,22 +1,17 @@ --- title: crypto.SHA1 -linkTitle: sha1 -description: Hashes the given input and returns its SHA1 checksum. -categories: [functions] +description: Hashes the given input and returns its SHA1 checksum encoded to a hexadecimal string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sha1] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA256 returnType: string signatures: [crypto.SHA1 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/sha,/functions/sha1] --- diff --git a/docs/content/en/functions/crypto/SHA256.md b/docs/content/en/functions/crypto/SHA256.md index 3019432d2..6fb657767 100644 --- a/docs/content/en/functions/crypto/SHA256.md +++ b/docs/content/en/functions/crypto/SHA256.md @@ -1,22 +1,17 @@ --- title: crypto.SHA256 -linkTitle: sha256 -description: Hashes the given input and returns its SHA256 checksum. -categories: [functions] +description: Hashes the given input and returns its SHA256 checksum encoded to a hexadecimal string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sha256] + related: + - functions/crypto/FNV32a + - functions/crypto/HMAC + - functions/crypto/MD5 + - functions/crypto/SHA1 returnType: string signatures: [crypto.SHA256 INPUT] -relatedFunctions: - - crypto.FNV32a - - crypto.HMAC - - crypto.MD5 - - crypto.SHA1 - - crypto.SHA256 aliases: [/functions/sha256] --- diff --git a/docs/content/en/functions/crypto/_index.md b/docs/content/en/functions/crypto/_index.md new file mode 100644 index 000000000..5c95aab6e --- /dev/null +++ b/docs/content/en/functions/crypto/_index.md @@ -0,0 +1,12 @@ +--- +title: Crypto functions +linkTitle: crypto +description: Template functions to create cryptographic hashes. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to create cryptographic hashes. diff --git a/docs/content/en/functions/data/GetCSV.md b/docs/content/en/functions/data/GetCSV.md index e02c1588c..d61ea791d 100644 --- a/docs/content/en/functions/data/GetCSV.md +++ b/docs/content/en/functions/data/GetCSV.md @@ -1,19 +1,17 @@ --- title: data.GetCSV -linkTitle: getCSV description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getCSV] - returnType: '[]string' - signatures: [data.GetCSV SEPARATOR PATHPART...] -relatedFunctions: - - data.GetCSV - - data.GetJSON + related: + - functions/data/GetJSON + - functions/resources/Get + - functions/resources/GetRemote + - methods/page/Resources + returnType: '[][]string' + signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] toc: true --- @@ -32,6 +30,12 @@ Access the data with either of the following: {{ $data := getCSV "," "other-files/" "pets.csv" }} ``` +{{% note %}} +When working with local data, the filepath is relative to the working directory. + +You must not place CSV files in the project's data directory. +{{% /note %}} + Access remote data with either of the following: ```go-html-template @@ -49,9 +53,25 @@ The resulting data structure is an array of arrays: ] ``` +## Options + +Add headers to the request by providing an options map: + +```go-html-template +{{ $opts := dict "Authorization" "Bearer abcd" }} +{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} +``` + +Add multiple headers using a slice: + +```go-html-template +{{ $opts := dict "X-List" (slice "a" "b" "c") }} +{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} +``` + ## Global resource alternative -Consider using `resources.Get` with [`transform.Unmarshal`] when accessing a global resource. +Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource. ```text my-project/ @@ -73,7 +93,7 @@ my-project/ ## Page resource alternative -Consider using `.Resources.Get` with [`transform.Unmarshal`] when accessing a page resource. +Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource. ```text my-project/ @@ -97,7 +117,7 @@ my-project/ ## Remote resource alternative -Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved error handling when accessing a remote resource. +Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. ```go-html-template {{ $data := "" }} @@ -114,4 +134,7 @@ Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved e {{ end }} ``` +[`Resources.Get`]: methods/page/Resources +[`resources.GetRemote`]: /functions/resources/getremote +[`resources.Get`]: /functions/resources/get [`transform.Unmarshal`]: /functions/transform/unmarshal diff --git a/docs/content/en/functions/data/GetJSON.md b/docs/content/en/functions/data/GetJSON.md index 37ee8e9a1..96812e7c0 100644 --- a/docs/content/en/functions/data/GetJSON.md +++ b/docs/content/en/functions/data/GetJSON.md @@ -1,19 +1,17 @@ --- title: data.GetJSON -linkTitle: getJSON description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getJSON] + related: + - functions/data/GetCSV + - functions/resources/Get + - functions/resources/GetRemote + - methods/page/Resources returnType: any - signatures: [data.GetJSON PATHPART...] -relatedFunctions: - - data.GetCSV - - data.GetJSON + signatures: ['data.GetJSON INPUT... [OPTIONS]'] toc: true --- @@ -28,15 +26,19 @@ my-project/ Access the data with either of the following: ```go-html-template -{{ $data := getCSV "," "other-files/books.json" }} -{{ $data := getCSV "," "other-files/" "books.json" }} +{{ $data := getJSON "other-files/books.json" }} +{{ $data := getJSON "other-files/" "books.json" }} ``` +{{% note %}} +When working with local data, the filepath is relative to the working directory. +{{% /note %}} + Access remote data with either of the following: ```go-html-template -{{ $data := getCSV "," "https://example.org/books.json" }} -{{ $data := getCSV "," "https://example.org/" "books.json" }} +{{ $data := getJSON "https://example.org/books.json" }} +{{ $data := getJSON "https://example.org/" "books.json" }} ``` The resulting data structure is a JSON object: @@ -56,9 +58,25 @@ The resulting data structure is a JSON object: ] ``` +## Options + +Add headers to the request by providing an options map: + +```go-html-template +{{ $opts := dict "Authorization" "Bearer abcd" }} +{{ $data := getJSON "https://example.org/books.json" $opts }} +``` + +Add multiple headers using a slice: + +```go-html-template +{{ $opts := dict "X-List" (slice "a" "b" "c") }} +{{ $data := getJSON "https://example.org/books.json" $opts }} +``` + ## Global resource alternative -Consider using `resources.Get` with [`transform.Unmarshal`] when accessing a global resource. +Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource. ```text my-project/ @@ -80,7 +98,7 @@ my-project/ ## Page resource alternative -Consider using `.Resources.Get` with [`transform.Unmarshal`] when accessing a page resource. +Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource. ```text my-project/ @@ -104,7 +122,7 @@ my-project/ ## Remote resource alternative -Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved error handling when accessing a remote resource. +Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. ```go-html-template {{ $data := "" }} @@ -121,4 +139,7 @@ Consider using `resources.GetRemote` with [`transform.Unmarshal`] for improved e {{ end }} ``` +[`Resources.Get`]: methods/page/Resources +[`resources.GetRemote`]: /functions/resources/getremote +[`resources.Get`]: /functions/resources/get [`transform.Unmarshal`]: /functions/transform/unmarshal diff --git a/docs/content/en/functions/data/_index.md b/docs/content/en/functions/data/_index.md new file mode 100644 index 000000000..142d6b528 --- /dev/null +++ b/docs/content/en/functions/data/_index.md @@ -0,0 +1,12 @@ +--- +title: Data functions +linkTitle: data +description: Template functions to read local or remote data files. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to read local or remote data files. diff --git a/docs/content/en/functions/debug/Dump.md b/docs/content/en/functions/debug/Dump.md index ff505a76b..d3161605f 100644 --- a/docs/content/en/functions/debug/Dump.md +++ b/docs/content/en/functions/debug/Dump.md @@ -1,16 +1,13 @@ --- title: debug.Dump description: Returns an object dump as a string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: string signatures: [debug.Dump VALUE] -relatedFunctions: [] --- ```go-html-template @@ -43,8 +40,6 @@ relatedFunctions: [] } ``` - - {{% note %}} Output from this function may change from one release to the next. Use for debugging only. {{% /note %}} diff --git a/docs/content/en/functions/debug/Timer.md b/docs/content/en/functions/debug/Timer.md new file mode 100644 index 000000000..ae6c3188f --- /dev/null +++ b/docs/content/en/functions/debug/Timer.md @@ -0,0 +1,37 @@ +--- +title: debug.Timer +description: Creates a named timer that reports elapsed time to the console. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: debug.Timer + signatures: [debug.Timer NAME] +--- + +{{< new-in 0.120.0 >}} + +Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. + +The timer starts when you instantiate it, and stops when you call its `Stop` method. + +```go-html-template +{{ $t := debug.Timer "TestSqrt" }} +{{ range seq 2000 }} + {{ $f := math.Sqrt . }} +{{ end }} +{{ $t.Stop }} +``` + +Use the `--logLevel info` command line flag when you build the site. + +```sh +hugo --logLevel info +``` + +The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build. + +```text +INFO timer: name TestSqrt total 12.429355ms +``` diff --git a/docs/content/en/functions/debug/_index.md b/docs/content/en/functions/debug/_index.md new file mode 100644 index 000000000..418828515 --- /dev/null +++ b/docs/content/en/functions/debug/_index.md @@ -0,0 +1,12 @@ +--- +title: Debug functions +linkTitle: debug +description: Template functions to debug your templates. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to debug your templates. diff --git a/docs/content/en/functions/diagrams/Goat.md b/docs/content/en/functions/diagrams/Goat.md new file mode 100644 index 000000000..2b31d9824 --- /dev/null +++ b/docs/content/en/functions/diagrams/Goat.md @@ -0,0 +1,113 @@ +--- +title: diagrams.Goat +description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: diagrams.goatDiagram + signatures: ['diagrams.Goat INPUT'] +toc: true +--- + +Useful in a code block [render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods: + +[GoAT]: https://github.com/blampe/goat#readme +[render hook]: https://gohugo.io/templates/render-hooks/ + +Inner +: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper. + +Wrapped +: (`template.HTML`) Returns the SVG child elements wrapped in an `svg` element. + +Width +: (`int`) Returns the width of the rendered diagram, in pixels. + +Height +: (`int`) Returns the height of the rendered diagram, in pixels. + +## GoAT Diagrams + +Hugo natively supports [GoAT] diagrams. + +This markdown: + +```` +```goat +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` +```` + +Is rendered to: + +```html +<div class="goat svg-container"> + <svg xmlns="http://www.w3.org/2000/svg" font-family="Menlo,Lucida Console,monospace" viewBox="0 0 352 57"> + ... + </svg> +</div> +``` + +Which appears in your browser as: + +```goat {class="mw6-ns"} +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` + +To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams. + +[built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html + +## Code block render hook + +By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. + +{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}} +{{ $caption := or .Attributes.caption "" }} +{{ $class := or .Attributes.class "diagram" }} +{{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} + +<figure id="{{ $id }}"> + {{ with diagrams.Goat (trim .Inner "\n\r") }} + <svg class="{{ $class }}" width="{{ .Width }}" height="{{ .Height }}" xmlns="http://www.w3.org/2000/svg" version="1.1"> + {{ .Inner }} + </svg> + {{ end }} + <figcaption>{{ $caption }}</figcaption> +</figure> +{{< /code >}} + +This markdown: + +{{< code file=content/example.md lang=text >}} +```goat {class="foo" caption="Diagram 1: Example"} +.---. .-. .-. .-. .---. +| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | +'---' '-' '+' '+' '---' +``` +{{< /code >}} + +Is rendered to: + +```html +<figure id="diagram-1"> + <svg class="foo" width="272" height="57" xmlns="http://www.w3.org/2000/svg" version="1.1"> + ... + </svg> + <figcaption>Diagram 1: Example</figcaption> +</figure> +``` + +Use CSS to style the SVG as needed: + +```css +svg.foo { + font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif +} +``` diff --git a/docs/content/en/functions/diagrams/_index.md b/docs/content/en/functions/diagrams/_index.md new file mode 100644 index 000000000..e136b4f33 --- /dev/null +++ b/docs/content/en/functions/diagrams/_index.md @@ -0,0 +1,12 @@ +--- +title: Diagram functions +linkTitle: diagrams +description: Template functions to render diagrams. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to render diagrams. diff --git a/docs/content/en/functions/encoding/Base64Decode.md b/docs/content/en/functions/encoding/Base64Decode.md index 8bd554c83..821ca805a 100644 --- a/docs/content/en/functions/encoding/Base64Decode.md +++ b/docs/content/en/functions/encoding/Base64Decode.md @@ -1,24 +1,19 @@ --- title: encoding.Base64Decode -linkTitle: base64Decode description: Returns the base64 decoding of the given content. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [base64Decode] + related: + - functions/encoding/Base64Encode returnType: string signatures: [encoding.Base64Decode INPUT] -signatures: - - - - base64Decode INPUT aliases: [/functions/base64Decode] --- ```go-html-template -{{ "SHVnbw==" | base64Decode }} → "Hugo" +{{ "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: diff --git a/docs/content/en/functions/encoding/Base64Encode.md b/docs/content/en/functions/encoding/Base64Encode.md index d548aca8e..14f67a132 100644 --- a/docs/content/en/functions/encoding/Base64Encode.md +++ b/docs/content/en/functions/encoding/Base64Encode.md @@ -1,22 +1,17 @@ --- title: encoding.Base64Encode -linkTitle: base64Encode description: Returns the base64 decoding of the given content. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [base64Encode] + related: + - functions/encoding/Base64Decode returnType: string signatures: [encoding.Base64Encode INPUT] -relatedFunctions: - - encoding.Base64Decode - - encoding.Base64Encode aliases: [/functions/base64, /functions/base64Encode] --- ```go-html-template -{{ "Hugo" | base64Encode }} → "SHVnbw==" +{{ "Hugo" | base64Encode }} → SHVnbw== ``` diff --git a/docs/content/en/functions/encoding/Jsonify.md b/docs/content/en/functions/encoding/Jsonify.md index 0b9cb2e74..475f8a76a 100644 --- a/docs/content/en/functions/encoding/Jsonify.md +++ b/docs/content/en/functions/encoding/Jsonify.md @@ -1,31 +1,24 @@ --- title: encoding.Jsonify -linkTitle: jsonify -description: Encodes a given object to JSON. -categories: [functions] +description: Encodes the given object to JSON. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [jsonify] returnType: template.HTML + related: + - functions/transform/Remarshal + - functions/transform/Unmarshal signatures: - - encoding.Jsonify INPUT - - encoding.Jsonify OPTIONS INPUT -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal + - encoding.Jsonify [OPTIONS] INPUT aliases: [/functions/jsonify] --- -To customize the printing of the JSON, pass a map of options as the first -argument. Supported options are "prefix" and "indent". Each JSON element in +To customize the printing of the JSON, pass an options map as the first +argument. Supported options are "prefix" and "indent". Each JSON element in the output will begin on a new line beginning with *prefix* followed by one or more copies of *indent* according to the indentation nesting. - ```go-html-template {{ dict "title" .Title "content" .Plain | jsonify }} {{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }} @@ -34,15 +27,11 @@ more copies of *indent* according to the indentation nesting. ## Options -indent ("") -: Indentation to use. - -prefix ("") -: Indentation prefix. - -noHTMLEscape (false) -: Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML. +indent +: (`string`) Indentation to use. Default is "". -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. +prefix +: (`string`) Indentation prefix. Default is "". -[pagevars]: /variables/page/ +noHTMLEscape +: (`bool`) Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. diff --git a/docs/content/en/functions/encoding/_index.md b/docs/content/en/functions/encoding/_index.md new file mode 100644 index 000000000..3c4c4519e --- /dev/null +++ b/docs/content/en/functions/encoding/_index.md @@ -0,0 +1,12 @@ +--- +title: Encoding functions +linkTitle: encoding +description: Template functions to encode and decode data. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to encode and decode data. diff --git a/docs/content/en/functions/fmt/Errorf.md b/docs/content/en/functions/fmt/Errorf.md index da9845073..bbdd62c53 100644 --- a/docs/content/en/functions/fmt/Errorf.md +++ b/docs/content/en/functions/fmt/Errorf.md @@ -1,26 +1,21 @@ --- title: fmt.Errorf -linkTitle: errorf description: Log an ERROR from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [errorf] + related: + - functions/fmt/Erroridf + - functions/fmt/Warnf returnType: string signatures: ['fmt.Errorf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/errorf] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -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. +The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build. ```go-html-template {{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }} @@ -29,5 +24,3 @@ Like the [`printf`] function, the `errorf` function evaluates the format string Use the [`erroridf`] function to allow optional suppression of specific errors. [`erroridf`]: /functions/fmt/erroridf -[`printf`]: /functions/fmt/printf -[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/docs/content/en/functions/fmt/Erroridf.md b/docs/content/en/functions/fmt/Erroridf.md index 986810436..9884f4935 100644 --- a/docs/content/en/functions/fmt/Erroridf.md +++ b/docs/content/en/functions/fmt/Erroridf.md @@ -1,28 +1,21 @@ --- title: fmt.Erroridf -linkTitle: erroridf description: Log a suppressable ERROR from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [erroridf] + related: + - functions/fmt/Errorf + - functions/fmt/Warnf returnType: string signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/erroridf] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -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 suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration. +The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration. This template code: @@ -34,15 +27,14 @@ 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"] +You can suppress this error by adding the following to your site configuration: +ignoreErrors = ['error-42'] ``` To suppress this message: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} ignoreErrors = ["error-42"] {{< /code-toggle >}} [`errorf`]: /functions/fmt/errorf -[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/docs/content/en/functions/fmt/Print.md b/docs/content/en/functions/fmt/Print.md index f9ff885f8..6f3128e5f 100644 --- a/docs/content/en/functions/fmt/Print.md +++ b/docs/content/en/functions/fmt/Print.md @@ -1,25 +1,20 @@ --- title: fmt.Print -linkTitle: print description: Prints the default representation of the given arguments using the standard `fmt.Print` function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [print] + related: + - functions/fmt/Printf + - functions/fmt/Println returnType: string signatures: [fmt.Print INPUT] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/print] --- ```go-html-template -{{ print "foo" }} → "foo" -{{ print "foo" "bar" }} → "foobar" +{{ print "foo" }} → foo +{{ print "foo" "bar" }} → foobar {{ print (slice 1 2 3) }} → [1 2 3] ``` diff --git a/docs/content/en/functions/fmt/Printf.md b/docs/content/en/functions/fmt/Printf.md index 06b7222e9..5d0127460 100644 --- a/docs/content/en/functions/fmt/Printf.md +++ b/docs/content/en/functions/fmt/Printf.md @@ -1,26 +1,19 @@ --- title: fmt.Printf -linkTitle: printf description: Formats a string using the standard `fmt.Sprintf` function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [printf] + related: + - functions/fmt/Print + - functions/fmt/Println returnType: string signatures: ['fmt.Printf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/printf] --- -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 +{{% include "functions/fmt/_common/fmt-layout.md" %}} ```go-html-template {{ $var := "world" }} diff --git a/docs/content/en/functions/fmt/Println.md b/docs/content/en/functions/fmt/Println.md index 358b5f8ac..a4db56ffb 100644 --- a/docs/content/en/functions/fmt/Println.md +++ b/docs/content/en/functions/fmt/Println.md @@ -1,23 +1,18 @@ --- title: fmt.Println -linkTitle: println -description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a linebreak. -categories: [functions] +description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a line break. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [println] + related: + - functions/fmt/Print + - functions/fmt/Printf returnType: string signatures: [fmt.Println INPUT] -relatedFunctions: - - fmt.Print - - fmt.Printf - - fmt.Println aliases: [/functions/println] --- ```go-html-template -{{ println "foo" }} → "foo\n" +{{ println "foo" }} → foo\n ``` diff --git a/docs/content/en/functions/fmt/Warnf.md b/docs/content/en/functions/fmt/Warnf.md index be579a216..b07cf3cc3 100644 --- a/docs/content/en/functions/fmt/Warnf.md +++ b/docs/content/en/functions/fmt/Warnf.md @@ -1,30 +1,22 @@ --- title: fmt.Warnf -linkTitle: warnf description: Log a WARNING from a template. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [warnf] + related: + - functions/fmt/Errorf + - functions/fmt/Erroridf returnType: string signatures: ['fmt.Warnf FORMAT [INPUT]'] -relatedFunctions: - - fmt.Errorf - - fmt.Erroridf - - fmt.Warnf aliases: [/functions/warnf] --- -The documentation for [Go's fmt package] describes the structure and content of the format string. +{{% include "functions/fmt/_common/fmt-layout.md" %}} -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. +The `warnf` function evaluates the format string, 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" }} +{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }} ``` - -[`printf`]: /functions/fmt/printf -[Go's fmt package]: https://pkg.go.dev/fmt diff --git a/docs/content/en/functions/fmt/_common/_index.md b/docs/content/en/functions/fmt/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/fmt/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/fmt/_common/fmt-layout.md b/docs/content/en/functions/fmt/_common/fmt-layout.md new file mode 100644 index 000000000..ff69ce5e4 --- /dev/null +++ b/docs/content/en/functions/fmt/_common/fmt-layout.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +The documentation for Go's [fmt] package describes the structure and content of the format string. + +[fmt]: https://pkg.go.dev/fmt diff --git a/docs/content/en/functions/fmt/_index.md b/docs/content/en/functions/fmt/_index.md new file mode 100644 index 000000000..51ef847ca --- /dev/null +++ b/docs/content/en/functions/fmt/_index.md @@ -0,0 +1,12 @@ +--- +title: Fmt functions +linkTitle: fmt +description: Template functions to print strings within a template or to print messages to the terminal +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to print strings within a template or to print messages to the terminal. diff --git a/docs/content/en/functions/global/_index.md b/docs/content/en/functions/global/_index.md new file mode 100644 index 000000000..1e609b56e --- /dev/null +++ b/docs/content/en/functions/global/_index.md @@ -0,0 +1,11 @@ +--- +title: Global functions +linkTitle: global +description: Global template functions to access page and site data. +categories: [] +menu: + docs: + parent: functions +--- + +Use these global functions to access page and site data. diff --git a/docs/content/en/functions/page/index.md b/docs/content/en/functions/global/page.md index 01f014078..e17fb0767 100644 --- a/docs/content/en/functions/page/index.md +++ b/docs/content/en/functions/global/page.md @@ -1,23 +1,21 @@ --- title: page -description: Provides global access to the .Page object. -categories: [functions] +description: Provides global access to a Page object. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/global/site returnType: signatures: [page] -relatedFunctions: - - hugo - - page - - site +toc: true aliases: [/functions/page] --- -At the top level of a template that receives the `Page` object in context, these are equivalent: +{{< new-in 0.111.0 >}} + +At the top level of a template that receives a `Page` object in context, these are equivalent: ```go-html-template {{ .Params.foo }} @@ -25,7 +23,7 @@ At the top level of a template that receives the `Page` object in context, these {{ page.Params.foo }} ``` -When the `Page` object is not in context, you can use the global `page` function: +When a `Page` object is not in context, you can use the global `page` function: ```go-html-template {{ page.Params.foo }} @@ -39,7 +37,7 @@ Do not use the global `page` function in shortcodes, partials called by shortcod 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. +But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object. Use the global `page` function to access the `Page` object from anywhere in any template. @@ -47,7 +45,7 @@ Use the global `page` function to access the `Page` object from anywhere in any ### Be aware of top-level context -The global `page` function accesses the `Page` object passed into the top-level template. +The global `page` function accesses the `Page` object passed into the top-level template. With this content structure: @@ -86,9 +84,9 @@ Do not use the global `page` function in: - Shortcodes - Partials called by shortcodes -- Partials cached by the `partialCached` function +- 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. +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: @@ -99,10 +97,12 @@ Consider this section template: {{ 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. +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. +[`Summary`]: /methods/page/summary +[`partialCached`]: /functions/partials/includecached [content view]: /getting-started/glossary/#content-view [partial]: /getting-started/glossary/#partial [render hook]: /getting-started/glossary/#render-hook diff --git a/docs/content/en/functions/site/index.md b/docs/content/en/functions/global/site.md index 3341bff98..a097e471b 100644 --- a/docs/content/en/functions/site/index.md +++ b/docs/content/en/functions/global/site.md @@ -1,19 +1,14 @@ --- title: site -description: Provides global access to the .Site object. -categories: [functions] +description: Provides global access to the current Site object. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/global/page returnType: signatures: [site] -relatedFunctions: - - hugo - - page - - site aliases: [/functions/site] --- diff --git a/docs/content/en/functions/go-template/_common/_index.md b/docs/content/en/functions/go-template/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/go-template/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/go-template/_common/text-template.md b/docs/content/en/functions/go-template/_common/text-template.md new file mode 100644 index 000000000..71718c3fd --- /dev/null +++ b/docs/content/en/functions/go-template/_common/text-template.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +See Go's [text/template] documentation for more information. + +[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/_common/truthy-falsy.md b/docs/content/en/functions/go-template/_common/truthy-falsy.md new file mode 100644 index 000000000..c8fc9e09e --- /dev/null +++ b/docs/content/en/functions/go-template/_common/truthy-falsy.md @@ -0,0 +1,5 @@ +--- +# Do not remove front matter. +--- + +In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy. diff --git a/docs/content/en/functions/go-template/_index.md b/docs/content/en/functions/go-template/_index.md new file mode 100644 index 000000000..9075756aa --- /dev/null +++ b/docs/content/en/functions/go-template/_index.md @@ -0,0 +1,14 @@ +--- +title: Go template functions, operators, and statements +linkTitle: go template +description: Template functions, operators, and statements provided by Go's text/template package. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +These are the functions, operators, and statements provided by Go's [text/template] package. + +[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/and.md b/docs/content/en/functions/go-template/and.md new file mode 100644 index 000000000..6bc8c60a5 --- /dev/null +++ b/docs/content/en/functions/go-template/and.md @@ -0,0 +1,26 @@ +--- +title: and +description: Returns the first falsy argument. If all arguments are truthy, returns the last argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/not + - functions/go-template/or + returnType: any + signatures: [and VALUE...] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ and 1 0 "" }} → 0 (int) +{{ and 1 false 0 }} → false (bool) + +{{ and 1 2 3 }} → 3 (int) +{{ and "a" "b" "c" }} → c (string) +{{ and "a" 1 true }} → true (bool) +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/block.md b/docs/content/en/functions/go-template/block.md new file mode 100644 index 000000000..f8a082037 --- /dev/null +++ b/docs/content/en/functions/go-template/block.md @@ -0,0 +1,55 @@ +--- +title: block +description: Defines a template and executes it in place. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/define + - functions/go-template/end + returnType: + signatures: [block NAME CONTEXT] +--- + +A block is shorthand for defining a template: + +```go-html-template +{{ define "name" }} T1 {{ end }} +``` + +and then executing it in place: + +```go-html-template +{{ template "name" pipeline }} +``` +The typical use is to define a set of root templates that are then customized by redefining the block templates within. + +{{< code file=layouts/_default/baseof.html >}} +<body> + <main> + {{ block "main" . }} + {{ print "default value if 'main' template is empty" }} + {{ end }} + </main> +</body> +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} +{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/list.html >}} +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} + {{ range .Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/break.md b/docs/content/en/functions/go-template/break.md new file mode 100644 index 000000000..14074d7c0 --- /dev/null +++ b/docs/content/en/functions/go-template/break.md @@ -0,0 +1,33 @@ +--- +title: break +description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/continue + - functions/go-template/range + returnType: + signatures: [break] +--- + +This template code: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ if eq . "bar" }} + {{ break }} + {{ end }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: + +```html +<p>foo</p> +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/continue.md b/docs/content/en/functions/go-template/continue.md new file mode 100644 index 000000000..c8030b8b7 --- /dev/null +++ b/docs/content/en/functions/go-template/continue.md @@ -0,0 +1,34 @@ +--- +title: continue +description: Used with the range statement, stops the innermost iteration and continues to the next iteration. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/break + - functions/go-template/range + returnType: + signatures: [continue] +--- + +This template code: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ if eq . "bar" }} + {{ continue }} + {{ end }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: + +```html +<p>foo</p> +<p>baz</p> +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/define.md b/docs/content/en/functions/go-template/define.md new file mode 100644 index 000000000..4d09c14f3 --- /dev/null +++ b/docs/content/en/functions/go-template/define.md @@ -0,0 +1,55 @@ +--- +title: define +description: Defines a template. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/block + - functions/go-template/end + - functions/go-template/template + - functions/partials/Include + - functions/partials/IncludeCached + returnType: + signatures: [define NAME] +--- + +Use with the [`block`] statement: + +```go-html-template +{{ block "main" . }} + {{ print "default value if 'main' template is empty" }} +{{ end }} + +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} +{{ end }} +``` + +Use with the [`partial`] function: + +```go-html-template +{{ partial "inline/foo.html" (dict "answer" 42) }} + +{{ define "partials/inline/foo.html" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +Use with the [`template`] function: + +```go-html-template +{{ template "foo" (dict "answer" 42) }} + +{{ define "foo" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +[`block`]: /functions/go-template/block +[`template`]: /functions/go-template/block +[`partial`]: /functions/partials/include/ + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/else.md b/docs/content/en/functions/go-template/else.md new file mode 100644 index 000000000..ccb8b722c --- /dev/null +++ b/docs/content/en/functions/go-template/else.md @@ -0,0 +1,69 @@ +--- +title: else +description: Begins an alternate block for if, with, and range statements. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/if + - functions/go-template/range + - functions/go-template/with + - functions/go-template/end + returnType: + signatures: [else VALUE] +--- + +Use with the [`if`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use with the [`with`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use with the [`range`] statement: + +```go-html-template +{{ $var := slice 1 2 3 }} +{{ range $var }} + {{ . }} → 1 2 3 +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use `else if` to check multiple conditions. + +```go-html-template +{{ $var := 12 }} +{{ if eq $var 6 }} + {{ print "var is 6" }} +{{ else if eq $var 7 }} + {{ print "var is 7" }} +{{ else if eq $var 42 }} + {{ print "var is 42" }} +{{ else }} + {{ print "var is something else" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`if`]: /functions/go-template/if +[`with`]: /functions/go-template/with +[`range`]: /functions/go-template/range diff --git a/docs/content/en/functions/go-template/end.md b/docs/content/en/functions/go-template/end.md new file mode 100644 index 000000000..07d004de5 --- /dev/null +++ b/docs/content/en/functions/go-template/end.md @@ -0,0 +1,65 @@ +--- +title: end +description: Terminates if, with, range, block, and define statements. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/block + - functions/go-template/define + - functions/go-template/if + - functions/go-template/range + - functions/go-template/with + returnType: + signatures: [end] +--- + +Use with the [`if`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ end }} +``` + +Use with the [`with`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ end }} +``` + +Use with the [`range`] statement: + +```go-html-template +{{ $var := slice 1 2 3 }} +{{ range $var }} + {{ . }} → 1 2 3 +{{ end }} +``` + +Use with the [`block`] statement: + +```go-html-template +{{ block "main" . }}{{ end }} +``` + +Use with the [`define`] statement: + +```go-html-template +{{ define "main" }} + {{ print "this is the main section" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`block`]: /functions/go-template/block +[`define`]: /functions/go-template/define +[`if`]: /functions/go-template/if +[`range`]: /functions/go-template/range +[`with`]: /functions/go-template/with diff --git a/docs/content/en/functions/go-template/if.md b/docs/content/en/functions/go-template/if.md new file mode 100644 index 000000000..e63c382e1 --- /dev/null +++ b/docs/content/en/functions/go-template/if.md @@ -0,0 +1,54 @@ +--- +title: if +description: Executes the block if the expression is truthy. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/with + - functions/go-template/else + - functions/go-template/end + - functions/collections/IsSet + returnType: + signatures: [if EXPR] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ end }} +``` + +Use with the [`else`] statement: + +```go-html-template +{{ $var := "foo" }} +{{ if $var }} + {{ $var }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` + +Use `else if` to check multiple conditions. + +```go-html-template +{{ $var := 12 }} +{{ if eq $var 6 }} + {{ print "var is 6" }} +{{ else if eq $var 7 }} + {{ print "var is 7" }} +{{ else if eq $var 42 }} + {{ print "var is 42" }} +{{ else }} + {{ print "var is something else" }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else diff --git a/docs/content/en/functions/go-template/len.md b/docs/content/en/functions/go-template/len.md index b8be621e8..43f150a5f 100644 --- a/docs/content/en/functions/go-template/len.md +++ b/docs/content/en/functions/go-template/len.md @@ -1,26 +1,20 @@ --- title: len description: Returns the length of a string, slice, map, or collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int - signatures: [len INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount + signatures: [len VALUE] aliases: [/functions/len] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - With a string: ```go-html-template @@ -53,3 +47,5 @@ You may also determine the number of pages in a collection with: ```go-html-template {{ site.RegularPages.Len }} → 42 ``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/not.md b/docs/content/en/functions/go-template/not.md new file mode 100644 index 000000000..4c7747c7b --- /dev/null +++ b/docs/content/en/functions/go-template/not.md @@ -0,0 +1,35 @@ +--- +title: not +description: Returns the boolean negation of its single argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/and + - functions/go-template/or + returnType: bool + signatures: [not VALUE] +--- + +Unlike the `and` and `or` operators, the `not` operator always returns a boolean value. + +```go-html-template +{{ not true }} → false +{{ not false }} → true + +{{ not 1 }} → false +{{ not 0 }} → true + +{{ not "x" }} → false +{{ not "" }} → true +``` + +Use the `not` operator, twice in succession, to cast any value to a boolean value. For example: + +```go-html-template +{{ 42 | not | not }} → true +{{ "" | not | not }} → false +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/or.md b/docs/content/en/functions/go-template/or.md new file mode 100644 index 000000000..0d8619608 --- /dev/null +++ b/docs/content/en/functions/go-template/or.md @@ -0,0 +1,26 @@ +--- +title: or +description: Returns the first truthy argument. If all arguments are falsy, returns the last argument. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/and + - functions/go-template/not + returnType: any + signatures: [or VALUE...] +--- + +{{% include "functions/go-template/_common/truthy-falsy.md" %}} + +```go-html-template +{{ or 0 1 2 }} → 1 +{{ or false "a" 1 }} → a +{{ or 0 true "a" }} → true + +{{ or false "" 0 }} → 0 +{{ or 0 "" false }} → false +``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index cf01633b4..e8642e50b 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -1,36 +1,95 @@ --- title: range -description: Iterates over slices, maps, and page collections. -categories: [functions] +description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/break + - functions/go-template/continue + - functions/go-template/else + - functions/go-template/end returnType: signatures: [range COLLECTION] -relatedFunctions: - - with - - range aliases: [/functions/range] toc: true --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -## Slices +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $var }} + {{ . }} → foo bar baz +{{ end }} +``` -Template: +Use with the [`else`] statement: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} {{ range $s }} <p>{{ . }}</p> +{{ else }} + <p>The collection is empty</p> +{{ end }} +``` + +Within a range block: + +- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration +- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations + +## Understanding context + +At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element. + +With this contrived example that uses the [`seq`] function to generate a slice of integers: + +```go-html-template +{{ range seq 3 }} + {{ .Title }} +{{ end }} +``` + +Hugo will throw an error: + + can't evaluate field Title in type int + +The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +This template will render the page title three times: + +```go-html-template +{{ range seq 3 }} + {{ $.Title }} {{ end }} ``` -Result: +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[`seq`]: functions/collections/seq/ +[context]: /getting-started/glossary/#context + +## Array or slice of scalars + +This template code: + +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + <p>{{ . }}</p> +{{ end }} +``` + +Is rendered to: ```html <p>foo</p> @@ -38,7 +97,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -47,7 +106,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>foo</p> @@ -55,7 +114,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -64,7 +123,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>0: foo</p> @@ -72,9 +131,9 @@ Result: <p>2: baz</p> ``` -## Maps +## Array or slice of maps -Template: +This template code: ```go-html-template {{ $m := slice @@ -87,7 +146,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>John is 30</p> @@ -95,9 +154,9 @@ Result: <p>Joey is 24</p> ``` -## Page collections +## Array or slice of pages -Template: +This template code: ```go-html-template {{ range where site.RegularPages "Type" "articles" }} @@ -105,7 +164,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <h2><a href="/articles/article-3/">Article 3</a></h2> @@ -113,47 +172,28 @@ Result: <h2><a href="/articles/article-1/">Article 1</a></h2> ``` -## Break - -Use the `break` statement to stop the innermost iteration and bypass all remaining iterations. +## Maps -Template: +This template code: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ break }} - {{ end }} - <p>{{ . }}</p> +{{ $m := dict "name" "John" "age" 30 }} +{{ range $k, $v := $m }} + <p>key = {{ $k }} value = {{ $v }}</p> {{ end }} ``` -Result: - -```html -<p>foo</p> -``` - -## Continue - -Use the `continue` statement to stop the innermost iteration and continue to the next iteration. - -Template: +Is rendered to: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ continue }} - {{ end }} - <p>{{ . }}</p> -{{ end }} +<p>key = age value = 30</p> +<p>key = name value = John</p> ``` -Result: +Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -```html -<p>foo</p> -<p>baz</p> -``` +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else +[`break`]: /functions/go-template/break +[`continue`]: /functions/go-template/continue diff --git a/docs/content/en/functions/go-template/return.md b/docs/content/en/functions/go-template/return.md new file mode 100644 index 000000000..2a166c718 --- /dev/null +++ b/docs/content/en/functions/go-template/return.md @@ -0,0 +1,110 @@ +--- +title: return +description: Used within partial templates, terminates template execution and returns the given value, if any. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/partials/Include + - functions/partials/IncludeCached + returnType: any + signatures: ['return [VALUE]'] +toc: true +--- + +The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any. + +The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`]. + +A `return` statement without a value returns an empty string of type `template.HTML`. + +[`bool`]: /getting-started/glossary/#bool +[`float`]: /getting-started/glossary/#float +[`int`]: /getting-started/glossary/#int +[`map`]: /getting-started/glossary/#map +[`resource`]: /getting-started/glossary/#resource +[`slice`]: /getting-started/glossary/#slice +[`string`]: /getting-started/glossary/#string +[text/template]: https://pkg.go.dev/text/template + +{{% note %}} +Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below. +{{% /note %}} + +## Example + +By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: + +{{< code file="layouts/partials/odd-or-even.html" >}} +{{ if math.ModBool . 2 }} + <p>{{ . }} is even</p> +{{ else }} + <p>{{ . }} is odd</p> +{{ end }} +{{< /code >}} + +When called, the partial renders HTML: + +```go-html-template +{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p> +``` + +Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: + +{{< code file="layouts/partials/is-even.html" >}} +{{ return math.ModBool . 2 }} +{{< /code >}} + +With this template: + +```go-html-template +{{ $number := 42 }} +{{ if partial "is-even.html" $number }} + <p>{{ $number }} is even</p> +{{ else }} + <p>{{ $number }} is odd</p> +{{ end }} +``` + +Hugo renders: + +```html +<p>42 is even</p> +``` + +See additional examples in the [partial templates] section. + +[partial templates]: /templates/partials/#returning-a-value-from-a-partial + +## Usage + +{{% note %}} +Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks +{{% /note %}} + +A partial that returns a value must contain only one `return` statement, placed at the end of the template. + +For example: + +{{< code file="layouts/partials/is-even.html" >}} +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +{{< /code >}} + +{{% note %}} +The construct below is incorrect; it contains more than one `return` statement. +{{% /note %}} + +{{< code file="layouts/partials/do-not-do-this.html" >}} +{{ if math.ModBool . 2 }} + {{ return "even" }} +{{ else }} + {{ return "odd" }} +{{ end }} +{{< /code >}} diff --git a/docs/content/en/functions/go-template/template.md b/docs/content/en/functions/go-template/template.md new file mode 100644 index 000000000..a78ec5c65 --- /dev/null +++ b/docs/content/en/functions/go-template/template.md @@ -0,0 +1,49 @@ +--- +title: template +description: Executes the given template, optionally passing context. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/define + - functions/partials/Include + - functions/partials/IncludeCached + returnType: + signatures: ['template NAME [CONTEXT]'] +--- + +Use the `template` function to execute [internal templates]. For example: + +```go-html-template +{{ range (.Paginate .Pages).Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} +{{ template "_internal/pagination.html" . }} +``` + +You can also use the `template` function to execute a defined template: + +```go-html-template +{{ template "foo" (dict "answer" 42) }} + +{{ define "foo" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +The example above can be rewritten using an [inline partial] template: + +```go-html-template +{{ partial "inline/foo.html" (dict "answer" 42) }} + +{{ define "partials/inline/foo.html" }} + {{ printf "The answer is %v." .answer }} +{{ end }} +``` + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`partial`]: /functions/partials/include/ +[inline partial]: /templates/partials/#inline-partials +[internal templates]: /templates/internal diff --git a/docs/content/en/functions/go-template/urlquery.md b/docs/content/en/functions/go-template/urlquery.md index cbbfdfa7d..946828f56 100644 --- a/docs/content/en/functions/go-template/urlquery.md +++ b/docs/content/en/functions/go-template/urlquery.md @@ -1,23 +1,17 @@ --- title: urlquery description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/collections/Querify returnType: string - signatures: ['urlquery INPUT [INPUT]...'] -relatedFunctions: - - collections.Querify - - urlquery + signatures: ['urlquery VALUE [VALUE...]'] aliases: [/functions/urlquery] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - This template code: ```go-html-template @@ -30,3 +24,5 @@ Is rendered to: ```html <a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a> ``` + +{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/with.md b/docs/content/en/functions/go-template/with.md index 06ca38150..197181953 100644 --- a/docs/content/en/functions/go-template/with.md +++ b/docs/content/en/functions/go-template/with.md @@ -1,35 +1,87 @@ --- title: with -description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent or empty. -categories: [functions] +description: Binds context (the dot) to the expression and executes the block if expression is truthy. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: any - signatures: [with PIPELINE] -relatedFunctions: - - with - - range + related: + - functions/go-template/if + - functions/go-template/else + - functions/go-template/end + - functions/collections/IsSet + returnType: + signatures: [with EXPR] aliases: [/functions/with] +toc: true --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -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. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ end }} +``` -The set of *empty* values is defined by [the Go templates package](https://golang.org/pkg/text/template/). Empty values include `false`, the number zero, and the empty string. +Use with the [`else`] statement: -If you want to render a block if an index or key is present in a slice, array, channel or map, regardless of whether the value is empty, you should use [`isset`](/functions/collections/isset) instead. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` -The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing: +Intialize a variable, scoped to the current block: -{{< code file="layouts/partials/twitter.html" >}} -{{ with .Site.Params.twitteruser }}<span class="twitter"> -<a href="https://twitter.com/{{ . }}" rel="author"> -<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" - alt="Twitter"></a> -</span>{{ end }} -{{< /code >}} +```go-html-template +{{ with $var := 42 }} + {{ . }} → 42 + {{ $var }} → 42 +{{ end }} +{{ $var }} → undefined +``` + +## Understanding context + +At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement. + +With this contrived example: + +```go-html-template +{{ with 42 }} + {{ .Title }} +{{ end }} +``` + +Hugo will throw an error: + + can't evaluate field Title in type int + +The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template. + +{{% note %}} +Use the `$` to get the context passed into the template. +{{% /note %}} + +This template will render the page title as desired: + +```go-html-template +{{ with 42 }} + {{ $.Title }} +{{ end }} +``` + +{{% note %}} +Gaining a thorough understanding of context is critical for anyone writing template code. +{{% /note %}} + +[context]: /getting-started/glossary/#context + +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else diff --git a/docs/content/en/functions/hugo/BuildDate.md b/docs/content/en/functions/hugo/BuildDate.md new file mode 100644 index 000000000..1fbdbeac6 --- /dev/null +++ b/docs/content/en/functions/hugo/BuildDate.md @@ -0,0 +1,19 @@ +--- +title: hugo.BuildDate +description: Returns the compile date of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.BuildDate] +--- + +The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339]. + +[RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339 + +```go-html-template +{{ hugo.BuildDate }} → 2023-11-01T17:57:00Z +``` diff --git a/docs/content/en/functions/hugo/CommitHash.md b/docs/content/en/functions/hugo/CommitHash.md new file mode 100644 index 000000000..cd4f2ce92 --- /dev/null +++ b/docs/content/en/functions/hugo/CommitHash.md @@ -0,0 +1,15 @@ +--- +title: hugo.CommitHash +description: Returns the Git commit hash of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.CommitHash] +--- + +```go-html-template +{{ hugo.CommitHash }} → a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970 +``` diff --git a/docs/content/en/functions/hugo/Deps.md b/docs/content/en/functions/hugo/Deps.md new file mode 100644 index 000000000..2f3f75e65 --- /dev/null +++ b/docs/content/en/functions/hugo/Deps.md @@ -0,0 +1,66 @@ +--- +title: hugo.Deps +description: Returns a slice of project dependencies, either Hugo Modules or local theme components. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: '[]hugo.Dependency' + signatures: [hugo.Deps] +--- + +The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains: + +Owner +: (`hugo.Dependency`) In the dependency tree, this is the first module that defines this module as a dependency (e.g., `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`). + +Path +: (`string`) The module path or the path below your `themes` directory (e.g., `github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2`). + +Replace +: (`hugo.Dependency`) Replaced by this dependency. + +Time +: (`time.Time`) The time that the version was created (e.g., `2022-02-13 15:11:28 +0000 UTC`). + +Vendor +: (`bool`) Reports whether the dependency is vendored. + +Version +: (`string`) The module version (e.g., `v2.21100.20000`). + +An example table listing the dependencies: + +```go-html-template +<h2>Dependencies</h2> +<table class="table table-dark"> + <thead> + <tr> + <th scope="col">#</th> + <th scope="col">Owner</th> + <th scope="col">Path</th> + <th scope="col">Version</th> + <th scope="col">Time</th> + <th scope="col">Vendor</th> + </tr> + </thead> + <tbody> + {{ range $index, $element := hugo.Deps }} + <tr> + <th scope="row">{{ add $index 1 }}</th> + <td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td> + <td> + {{ $element.Path }} + {{ with $element.Replace }} + => {{ .Path }} + {{ end }} + </td> + <td>{{ $element.Version }}</td> + <td>{{ with $element.Time }}{{ . }}{{ end }}</td> + <td>{{ $element.Vendor }}</td> + </tr> + {{ end }} + </tbody> +</table> +``` diff --git a/docs/content/en/functions/hugo/Environment.md b/docs/content/en/functions/hugo/Environment.md new file mode 100644 index 000000000..f130de787 --- /dev/null +++ b/docs/content/en/functions/hugo/Environment.md @@ -0,0 +1,30 @@ +--- +title: hugo.Environment +description: Returns the current running environment. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsDevelopment + - functions/hugo/IsProduction + returnType: string + signatures: [hugo.Environment] +--- + +The `hugo.Environment` function returns the current running [environment] as defined through the `--environment` command line flag. + +```go-html-template +{{ hugo.Environment }} → production +``` + +Command line examples: + +Command|Environment +:--|:-- +`hugo`|`production` +`hugo --environment staging`|`staging` +`hugo server`|`development` +`hugo server --environment staging`|`staging` + +[environment]: /getting-started/glossary/#environment diff --git a/docs/content/en/functions/hugo/Generator.md b/docs/content/en/functions/hugo/Generator.md new file mode 100644 index 000000000..a9496d87f --- /dev/null +++ b/docs/content/en/functions/hugo/Generator.md @@ -0,0 +1,15 @@ +--- +title: hugo.Generator +description: Renders an HTML meta element identifying the software that generated the site. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: template.HTML + signatures: [hugo.Generator] +--- + +```go-html-template +{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.120.3"> +``` diff --git a/docs/content/en/functions/hugo/GoVersion.md b/docs/content/en/functions/hugo/GoVersion.md new file mode 100644 index 000000000..1640c3862 --- /dev/null +++ b/docs/content/en/functions/hugo/GoVersion.md @@ -0,0 +1,17 @@ +--- +title: hugo.GoVersion +description: Returns the Go version used to compile the Hugo binary +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.GoVersion] +--- + +{{< new-in 0.101.0 >}} + +```go-html-template +{{ hugo.GoVersion }} → go1.21.1 +``` diff --git a/docs/content/en/functions/hugo/IsDevelopment.md b/docs/content/en/functions/hugo/IsDevelopment.md new file mode 100644 index 000000000..9926b67c9 --- /dev/null +++ b/docs/content/en/functions/hugo/IsDevelopment.md @@ -0,0 +1,19 @@ +--- +title: hugo.IsDevelopment +description: Reports whether the current running environment is "development". +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsProduction + - functions/hugo/Environment + returnType: bool + signatures: [hugo.IsDevelopment] +--- + +{{< new-in 0.120.0 >}} + +```go-html-template +{{ hugo.IsDevelopment }} → true/false +``` diff --git a/docs/content/en/functions/hugo/IsExtended.md b/docs/content/en/functions/hugo/IsExtended.md new file mode 100644 index 000000000..84b68e6d3 --- /dev/null +++ b/docs/content/en/functions/hugo/IsExtended.md @@ -0,0 +1,15 @@ +--- +title: hugo.IsExtended +description: Reports whether the Hugo binary is the extended version. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsExtended] +--- + +```go-html-template +{{ hugo.IsExtended }} → true/false +``` diff --git a/docs/content/en/functions/hugo/IsProduction.md b/docs/content/en/functions/hugo/IsProduction.md new file mode 100644 index 000000000..7e9bda0e3 --- /dev/null +++ b/docs/content/en/functions/hugo/IsProduction.md @@ -0,0 +1,17 @@ +--- +title: hugo.IsProduction +description: Reports whether the current running environment is "production". +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/hugo/IsDevelopment + - functions/hugo/Environment + returnType: bool + signatures: [hugo.IsProduction] +--- + +```go-html-template +{{ hugo.IsProduction }} → true/false +``` diff --git a/docs/content/en/functions/hugo/IsServer.md b/docs/content/en/functions/hugo/IsServer.md new file mode 100644 index 000000000..942261007 --- /dev/null +++ b/docs/content/en/functions/hugo/IsServer.md @@ -0,0 +1,17 @@ +--- +title: hugo.IsServer +description: Reports whether the built-in development server is running. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: bool + signatures: [hugo.IsServer] +--- + +{{< new-in 0.120.0 >}} + +```go-html-template +{{ hugo.IsServer }} → true/false +``` diff --git a/docs/content/en/functions/hugo/Version.md b/docs/content/en/functions/hugo/Version.md new file mode 100644 index 000000000..9bb361a71 --- /dev/null +++ b/docs/content/en/functions/hugo/Version.md @@ -0,0 +1,15 @@ +--- +title: hugo.Version +description: Returns the current version of the Hugo binary. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: hugo.VersionString + signatures: [hugo.Version] +--- + +```go-html-template +{{ hugo.Version }} → 0.120.3 +``` diff --git a/docs/content/en/functions/hugo/WorkingDir.md b/docs/content/en/functions/hugo/WorkingDir.md new file mode 100644 index 000000000..ac3835ea8 --- /dev/null +++ b/docs/content/en/functions/hugo/WorkingDir.md @@ -0,0 +1,15 @@ +--- +title: hugo.WorkingDir +description: Returns the project working directory. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [hugo.WorkingDir] +--- + +```go-html-template +{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site +``` diff --git a/docs/content/en/functions/hugo/_index.md b/docs/content/en/functions/hugo/_index.md new file mode 100644 index 000000000..c3ad686da --- /dev/null +++ b/docs/content/en/functions/hugo/_index.md @@ -0,0 +1,12 @@ +--- +title: Hugo functions +linkTitle: hugo +description: Template functions to access information about the Hugo application and the current environment. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to access information about the Hugo application and the current environment. diff --git a/docs/content/en/functions/images/Brightness.md b/docs/content/en/functions/images/Brightness.md new file mode 100644 index 000000000..0001bcba8 --- /dev/null +++ b/docs/content/en/functions/images/Brightness.md @@ -0,0 +1,36 @@ +--- +title: images.Brightness +description: Returns an image filter that changes the brightness of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Brightness PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid black image, and a value of `100` produces a solid white image. + +## Usage + +Create the image filter: + +```go-html-template +{{ $filter := images.Brightness 12 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Brightness" + filterArgs="12" + example=true +>}} diff --git a/docs/content/en/functions/images/ColorBalance.md b/docs/content/en/functions/images/ColorBalance.md new file mode 100644 index 000000000..29829f9e6 --- /dev/null +++ b/docs/content/en/functions/images/ColorBalance.md @@ -0,0 +1,36 @@ +--- +title: images.ColorBalance +description: Returns an image filter that changes the color balance of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] +toc: true +--- + +The percentage for each channel (red, green, blue) must be in the range [-100, 500]. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.ColorBalance -10 10 50 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="ColorBalance" + filterArgs="-10,10,50" + example=true +>}} diff --git a/docs/content/en/functions/images/Colorize.md b/docs/content/en/functions/images/Colorize.md new file mode 100644 index 000000000..c974103b9 --- /dev/null +++ b/docs/content/en/functions/images/Colorize.md @@ -0,0 +1,40 @@ +--- +title: images.Colorize +description: Returns an image filter that produces a colorized version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Colorize HUE SATURATION PERCENTAGE] +toc: true +--- + +The hue is the angle on the color wheel, typically in the range [0, 360]. + +The saturation must be in the range [0, 100]. + +The percentage specifies the strength of the effect, and must be in the range [0, 100]. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Colorize 180 50 20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Colorize" + filterArgs="180,50,20" + example=true +>}} diff --git a/docs/content/en/functions/images/Config.md b/docs/content/en/functions/images/Config.md new file mode 100644 index 000000000..0a4d225bc --- /dev/null +++ b/docs/content/en/functions/images/Config.md @@ -0,0 +1,36 @@ +--- +title: images.Config +description: Returns an image.Config structure from the image at the specified path, relative to the working directory. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: image.Config + signatures: [images.Config PATH] +aliases: [/functions/imageconfig] +--- + +See [image processing] for an overview of Hugo's image pipeline. + +[image processing]: /content-management/image-processing/ + +```go-html-template +{{ $ic := images.Config "/static/images/a.jpg" }} + +{{ $ic.Width }} → 600 (int) +{{ $ic.Height }} → 400 (int) +``` + +Supported image formats include GIF, JPEG, PNG, TIFF, and WebP. + +{{% note %}} +This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global], [page], and [remote] resources. See the [image processing] section for details. + +[`Width`]: /methods/resource/width +[`Height`]: /methods/resource/height +[global]: /getting-started/glossary/#global-resource +[image processing]: /content-management/image-processing +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource +{{% /note %}} diff --git a/docs/content/en/functions/images/Contrast.md b/docs/content/en/functions/images/Contrast.md new file mode 100644 index 000000000..532ae8c9c --- /dev/null +++ b/docs/content/en/functions/images/Contrast.md @@ -0,0 +1,36 @@ +--- +title: images.Contrast +description: Returns an image filter that changes the contrast of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Contrast PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid grey image, and a value of `100` produces an over-contrasted image. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Contrast -20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Contrast" + filterArgs="-20" + example=true +>}} diff --git a/docs/content/en/functions/images/Filter.md b/docs/content/en/functions/images/Filter.md new file mode 100644 index 000000000..450a64814 --- /dev/null +++ b/docs/content/en/functions/images/Filter.md @@ -0,0 +1,67 @@ +--- +title: images.Filter +description: Applies one or more image filters to the given image resource. +categories: [] +keywords: [] +action: + aliases: [] + related: + - methods/resource/Filter + returnType: images.ImageResource + signatures: [images.Filter FILTERS... IMAGE] +toc: true +--- + +Apply one or more [image filters](#image-filters) to the given image. + +To apply a single filter: + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter images.Grayscale . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +To apply two or more filters, executing from left to right: + +```go-html-template +{{ $filters := slice + images.Grayscale + (images.GaussianBlur 8) +}} +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter $filters . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +You can also apply image filters using the [`Filter`] method on a `Resource` object. + +[`Filter`]: /methods/resource/filter + +## Example + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with images.Filter images.Grayscale . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Grayscale" + filterArgs="" + example=true +>}} + +## Image filters + +Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object. + +{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} diff --git a/docs/content/en/functions/images/Gamma.md b/docs/content/en/functions/images/Gamma.md new file mode 100644 index 000000000..affbdcfa8 --- /dev/null +++ b/docs/content/en/functions/images/Gamma.md @@ -0,0 +1,36 @@ +--- +title: images.Gamma +description: Returns an image filter that performs gamma correction on an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Gamma GAMMA] +toc: true +--- + +The gamma value must be positive. A value greater than 1 lightens the image, while a value less than 1 darkens the image. The filter has no effect when the gamma value is 1. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Gamma 1.667 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Gamma" + filterArgs="1.667" + example=true +>}} diff --git a/docs/content/en/functions/images/GaussianBlur.md b/docs/content/en/functions/images/GaussianBlur.md new file mode 100644 index 000000000..e2f49a847 --- /dev/null +++ b/docs/content/en/functions/images/GaussianBlur.md @@ -0,0 +1,36 @@ +--- +title: images.GaussianBlur +description: Returns an image filter that applies a gaussian blur to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.GaussianBlur SIGMA] +toc: true +--- + +The sigma value must be positive, and indicates how much the image will be blurred. The blur-affected radius is approximately 3 times the sigma value. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.GaussianBlur 5 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="GaussianBlur" + filterArgs="5" + example=true +>}} diff --git a/docs/content/en/functions/images/Grayscale.md b/docs/content/en/functions/images/Grayscale.md new file mode 100644 index 000000000..d8a89b7f2 --- /dev/null +++ b/docs/content/en/functions/images/Grayscale.md @@ -0,0 +1,34 @@ +--- +title: images.Grayscale +description: Returns an image filter that produces a grayscale version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Grayscale] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Grayscale }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Grayscale" + filterArgs="" + example=true +>}} diff --git a/docs/content/en/functions/images/Hue.md b/docs/content/en/functions/images/Hue.md new file mode 100644 index 000000000..6eafac437 --- /dev/null +++ b/docs/content/en/functions/images/Hue.md @@ -0,0 +1,36 @@ +--- +title: images.Hue +description: Returns an image filter that rotates the hue of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Hue SHIFT] +toc: true +--- + +The hue angle shift is typically in the range [-180, 180] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Hue -15 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Hue" + filterArgs="-15" + example=true +>}} diff --git a/docs/content/en/functions/images/Invert.md b/docs/content/en/functions/images/Invert.md new file mode 100644 index 000000000..1ee85e514 --- /dev/null +++ b/docs/content/en/functions/images/Invert.md @@ -0,0 +1,34 @@ +--- +title: images.Invert +description: Returns an image filter that negates the colors of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Invert] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Invert }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Invert" + filterArgs="" + example=true +>}} diff --git a/docs/content/en/functions/images/Opacity.md b/docs/content/en/functions/images/Opacity.md new file mode 100644 index 000000000..6a74fd081 --- /dev/null +++ b/docs/content/en/functions/images/Opacity.md @@ -0,0 +1,52 @@ +--- +title: images.Opacity +description: Returns an image filter that changes the opacity of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Opacity OPACITY] +toc: true +--- + +{{< new-in 0.119.0 >}} + +The opacity value must be in the range [0, 1]. A value of `0` produces a transparent image, and a value of `1` produces an opaque image (no transparency). + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Opacity 0.65 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter: + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ $filters := slice + (images.Opacity 0.65) + (images.Process "png") + }} + {{ with . | images.Filter $filters }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Opacity" + filterArgs="0.65" + example=true +>}} diff --git a/docs/content/en/functions/images/Overlay.md b/docs/content/en/functions/images/Overlay.md new file mode 100644 index 000000000..39e62b121 --- /dev/null +++ b/docs/content/en/functions/images/Overlay.md @@ -0,0 +1,52 @@ +--- +title: images.Overlay +description: Returns an image filter that overlays the source image at the given coordinates, relative to the upper left corner. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Overlay RESOURCE X Y] +toc: true +--- + +## Usage + +Capture the overlay image as a resource: + +```go-html-template +{{ $overlay := "" }} +{{ $path := "images/logo.png" }} +{{ with resources.Get $path }} + {{ $overlay = . }} +{{ else }} + {{ errorf "Unable to get resource %q" $path }} +{{ end }} +``` + +The overlay image can be a [global resource], a [page resource], or a [remote resource]. + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource + +Create the filter: + +```go-html-template +{{ $filter := images.Overlay $overlay 20 20 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Overlay" + filterArgs="images/logos/logo-64x64.png,20,20" + example=true +>}} diff --git a/docs/content/en/functions/images/Padding.md b/docs/content/en/functions/images/Padding.md new file mode 100644 index 000000000..139626596 --- /dev/null +++ b/docs/content/en/functions/images/Padding.md @@ -0,0 +1,75 @@ +--- +title: images.Padding +description: Returns an image filter that resizes the image canvas without resizing the image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] +toc: true +--- + +{{< new-in 0.120.0 >}} + +The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image. + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Padding 20 40 "#976941" }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +Combine with the [`Colors`] method to create a border with one of the image's most dominant colors: + +[`Colors`]: /methods/resource/colors + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ $filter := images.Padding 20 40 (index .Colors 2) }} + {{ with . | images.Filter $filter }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Padding" + filterArgs="20,40,20,40,#976941" + example=true +>}} + +## Other recipes + +This example resizes an image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity. + +Conversion to WebP is required to support transparency. PNG and WebP images have an alpha channel; JPEG and GIF do not. + +```go-html-template +{{ $img := resources.Get "images/a.jpg" }} +{{ $filters := slice + (images.Process "resize 300x webp") + (images.Padding 20 50 "#0705") +}} +{{ $img = $img.Filter $filters }} +``` + +To add a 2px gray border to an image: + +```go-html-template +{{ $img = $img.Filter (images.Padding 2 "#777") }} +``` diff --git a/docs/content/en/functions/images/Pixelate.md b/docs/content/en/functions/images/Pixelate.md new file mode 100644 index 000000000..2016877ed --- /dev/null +++ b/docs/content/en/functions/images/Pixelate.md @@ -0,0 +1,34 @@ +--- +title: images.Pixelate +description: Returns an image filter that applies a pixelation effect to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Pixelate SIZE] +toc: true +--- + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Pixelate 4 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Pixelate" + filterArgs="4" + example=true +>}} diff --git a/docs/content/en/functions/images/Process.md b/docs/content/en/functions/images/Process.md new file mode 100644 index 000000000..a5e4d88dd --- /dev/null +++ b/docs/content/en/functions/images/Process.md @@ -0,0 +1,115 @@ +--- +title: images.Process +description: Returns an image filter that processes the given image using the given specification. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + - methods/resource/Process + returnType: images.filter + signatures: [images.Process SPEC] +toc: true +--- + +{{< new-in 0.119.0 >}} + +This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image. + +[`Process`]: /methods/resource/process + +The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: + +action +: Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. See [details](content-management/image-processing/#image-processing-methods). + +```go-html-template +{{ $filter := images.Process "resize 300x" }} +``` + +dimensions +: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). + +```go-html-template +{{ $filter := images.Process "crop 200x200" }} +``` + +anchor +: Use with the `crop` or `fill` action. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). + +```go-html-template +{{ $filter := images.Process "crop 200x200 center" }} +``` + +rotation +: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). + +```go-html-template +{{ $filter := images.Process "r90" }} +{{ $filter := images.Process "crop 200x200 center r90" }} +``` + +target format +: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). + +```go-html-template +{{ $filter := images.Process "webp" }} +{{ $filter := images.Process "crop 200x200 center r90 webp" }} +``` + +quality +: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). + +```go-html-template +{{ $filter := images.Process "q50" }} +{{ $filter := images.Process "crop 200x200 center r90 webp q50" }} +``` + +hint +: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). + +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp + + +```go-html-template +{{ $filter := images.Process "webp" "icon" }} +{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }} +``` + +background color +: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). + +```go-html-template +{{ $filter := images.Process "jpeg #000" }} +{{ $filter := images.Process "crop 200x200 center r90 q50 jpeg #000" }} +``` + +resampling filter +: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). + +```go-html-template +{{ $filter := images.Process "resize 300x lanczos" }} +{{ $filter := images.Process "resize 300x r90 q50 jpeg #000 lanczos" }} +``` + +## Usage + +Create a filter: + +```go-html-template +{{ $filter := images.Process "resize 256x q40 webp" }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Process" + filterArgs="resize 256x q40 webp" + example=true +>}} diff --git a/docs/content/en/functions/images/Saturation.md b/docs/content/en/functions/images/Saturation.md new file mode 100644 index 000000000..118bd0213 --- /dev/null +++ b/docs/content/en/functions/images/Saturation.md @@ -0,0 +1,36 @@ +--- +title: images.Saturation +description: Returns an image filter that changes the saturation of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Saturation PERCENTAGE] +toc: true +--- + +The percentage must be in the range [-100, 500] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Saturation 65 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Saturation" + filterArgs="65" + example=true +>}} diff --git a/docs/content/en/functions/images/Sepia.md b/docs/content/en/functions/images/Sepia.md new file mode 100644 index 000000000..9f0b7adfb --- /dev/null +++ b/docs/content/en/functions/images/Sepia.md @@ -0,0 +1,36 @@ +--- +title: images.Sepia +description: Returns an image filter that produces a sepia-toned version of an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Sepia PERCENTAGE] +toc: true +--- + +The percentage must be in the range [0, 100] where 0 has no effect. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Sepia 75 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Sepia" + filterArgs="75" + example=true +>}} diff --git a/docs/content/en/functions/images/Sigmoid.md b/docs/content/en/functions/images/Sigmoid.md new file mode 100644 index 000000000..32765f923 --- /dev/null +++ b/docs/content/en/functions/images/Sigmoid.md @@ -0,0 +1,40 @@ +--- +title: images.Sigmoid +description: Returns an image filter that changes the contrast of an image using a sigmoidal function. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.Sigmoid MIDPOINT FACTOR] +toc: true +--- + +This is a non-linear contrast change useful for photo adjustments; it preserves highlight and shadow detail. + +The midpoint is the midpoint of contrast. It must be in the range [0, 1], typically 0.5. + +The factor indicates how much to increase or decrease the contrast, typically in the range [-10, 10] where 0 has no effect. A positive value increases contrast, while a negative value decrease contrast. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.Sigmoid 0.6 -4 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Sigmoid" + filterArgs="0.6,-4" + example=true +>}} diff --git a/docs/content/en/functions/images/Text.md b/docs/content/en/functions/images/Text.md new file mode 100644 index 000000000..0c1e74bce --- /dev/null +++ b/docs/content/en/functions/images/Text.md @@ -0,0 +1,95 @@ +--- +title: images.Text +description: Returns an image filter that adds text to an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: ['images.Text TEXT [OPTIONS]'] +toc: true +--- + +## Options + +Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height. + +color +: (`string`) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is `#ffffff` (white). + +font +: (`resource.Resource`) The font can be a [global resource], a [page resource], or a [remote resource]. Default is the "Go Regular" TrueType font. + +linespacing +: (`int`) The number of pixels between each line. For a line height of 1.4, set the `linespacing` to 0.4 multiplied by the `size`. Default is `2`. + +size +: (`int`) The font size in pixels. Default is `20`. + +x +: (`int`) The horizontal offset, in pixels, relative to the left of the image. Default is `10`. + +y +: (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`. + +[global resource]: /getting-started/glossary/#global-resource +[page resource]: /getting-started/glossary/#page-resource +[remote resource]: /getting-started/glossary/#remote-resource + +## Usage + +Capture the font as a resource: + +```go-html-template +{{ $font := "" }} +{{ $path := "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Regular.ttf" }} +{{ with resources.GetRemote $path }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $font = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get resource %q" $path }} +{{ end }} +``` + +Create the options map: + +```go-html-template +{{ $opts := dict + "color" "#fbfaf5" + "font" $font + "linespacing" 8 + "size" 40 + "x" 25 + "y" 190 +}} +``` + +Set the text: + +```go-html-template +{{ $text := "Zion National Park" }} +``` + +Create the filter: + +```go-html-template +{{ $filter := images.Text $text $opts }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="Text" + filterArgs="Zion National Park,25,190,40,1.2,#fbfaf5" + example=true +>}} diff --git a/docs/content/en/functions/images/UnsharpMask.md b/docs/content/en/functions/images/UnsharpMask.md new file mode 100644 index 000000000..57a74a54a --- /dev/null +++ b/docs/content/en/functions/images/UnsharpMask.md @@ -0,0 +1,40 @@ +--- +title: images.UnsharpMask +description: Returns an image filter that sharpens an image. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/images/Filter + - methods/resource/Filter + returnType: images.filter + signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] +toc: true +--- + +The sigma parameter is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value. + +The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5. + +The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05. + +## Usage + +Create the filter: + +```go-html-template +{{ $filter := images.UnsharpMask 10 0.4 0.03 }} +``` + +{{% include "functions/images/_common/apply-image-filter.md" %}} + +## Example + +{{< img + src="images/examples/zion-national-park.jpg" + alt="Zion National Park" + filter="UnsharpMask" + filterArgs="10,0.4,0.03" + example=true +>}} diff --git a/docs/content/en/functions/images/_common/_index.md b/docs/content/en/functions/images/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/images/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/images/_common/apply-image-filter.md b/docs/content/en/functions/images/_common/apply-image-filter.md new file mode 100644 index 000000000..acd3a733d --- /dev/null +++ b/docs/content/en/functions/images/_common/apply-image-filter.md @@ -0,0 +1,27 @@ +--- +# Do not remove front matter. +--- + +Apply the filter using the [`images.Filter`] function: + +[`images.Filter`]: /functions/images/filter + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with . | images.Filter $filter }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +You can also apply the filter using the [`Filter`] method on a `Resource` object: + +[`Filter`]: methods/resource/filter + +```go-html-template +{{ with resources.Get "images/original.jpg" }} + {{ with .Filter $filter }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` diff --git a/docs/content/en/functions/images/_index.md b/docs/content/en/functions/images/_index.md new file mode 100644 index 000000000..13542ea73 --- /dev/null +++ b/docs/content/en/functions/images/_index.md @@ -0,0 +1,12 @@ +--- +title: Image functions +linkTitle: images +description: Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. diff --git a/docs/content/en/functions/inflect/Humanize.md b/docs/content/en/functions/inflect/Humanize.md index 74d24f310..41d61a4e5 100644 --- a/docs/content/en/functions/inflect/Humanize.md +++ b/docs/content/en/functions/inflect/Humanize.md @@ -1,29 +1,26 @@ --- title: inflect.Humanize -linkTitle: humanize -description: Returns the humanized version of an argument with the first letter capitalized. -categories: [functions] +description: Returns the humanized version of the input with the first letter capitalized. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [humanize] + related: + - functions/inflect/Pluralize + - functions/inflect/Singularize returnType: string signatures: [inflect.Humanize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/humanize] --- -If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended. +```go-html-template +{{ humanize "my-first-post" }} → My first post +{{ humanize "myCamelPost" }} → My camel post +``` +If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended. ```go-html-template -{{ humanize "my-first-post" }} → "My first post" -{{ humanize "myCamelPost" }} → "My camel post" -{{ humanize "52" }} → "52nd" -{{ humanize 103 }} → "103rd" +{{ humanize "52" }} → 52nd +{{ humanize 103 }} → 103rd ``` diff --git a/docs/content/en/functions/inflect/Pluralize.md b/docs/content/en/functions/inflect/Pluralize.md index 5bb444114..c25f89617 100644 --- a/docs/content/en/functions/inflect/Pluralize.md +++ b/docs/content/en/functions/inflect/Pluralize.md @@ -1,23 +1,18 @@ --- title: inflect.Pluralize -linkTitle: pluralize -description: Pluralizes the given word according to a set of common English pluralization rules -categories: [functions] +description: Pluralizes the given word according to a set of common English pluralization rules. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [pluralize] + related: + - functions/inflect/Humanize + - functions/inflect/Singularize returnType: string signatures: [inflect.Pluralize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/pluralize] --- ```go-html-template -{{ "cat" | pluralize }} → "cats" +{{ "cat" | pluralize }} → cats ``` diff --git a/docs/content/en/functions/inflect/Singularize.md b/docs/content/en/functions/inflect/Singularize.md index 5aba4e4ee..29b543257 100644 --- a/docs/content/en/functions/inflect/Singularize.md +++ b/docs/content/en/functions/inflect/Singularize.md @@ -1,25 +1,20 @@ --- title: inflect.Singularize -linkTitle: singularize -description: Converts a word according to a set of common English singularization rules. -categories: [functions] +description: Singularizes the given word according to a set of common English singularization rules. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [singularize] + related: + - functions/inflect/Humanize + - functions/inflect/Pluralize returnType: string signatures: [inflect.Singularize INPUT] -relatedFunctions: - - inflect.Humanize - - inflect.Pluralize - - inflect.Singularize aliases: [/functions/singularize] --- ```go-html-template -{{ "cats" | singularize }} → "cat" +{{ "cats" | singularize }} → cat ``` See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names. diff --git a/docs/content/en/functions/inflect/_index.md b/docs/content/en/functions/inflect/_index.md new file mode 100644 index 000000000..601b409e6 --- /dev/null +++ b/docs/content/en/functions/inflect/_index.md @@ -0,0 +1,12 @@ +--- +title: Inflect functions +linkTitle: inflect +description: Template functions to inflect English nouns. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +These functions provide word inflection features such as singularization and pluralization of English nouns. diff --git a/docs/content/en/functions/js/Build.md b/docs/content/en/functions/js/Build.md new file mode 100644 index 000000000..835785486 --- /dev/null +++ b/docs/content/en/functions/js/Build.md @@ -0,0 +1,184 @@ +--- +title: js.Build +description: Bundles, transpiles, tree shakes, and minifies JavaScript resources. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Babel + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['js.Build [OPTIONS] RESOURCE'] +toc: true +--- + +The `js.Build` function uses the [evanw/esbuild] package to: + +- Bundle +- Transpile (TypeScript and JSX) +- Tree shake +- Minify +- Create source maps + +[evanw/esbuild]: https://github.com/evanw/esbuild + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ if hugo.IsDevelopment }} + {{ with . | js.Build }} + <script src="{{ .RelPermalink }}"></script> + {{ end }} + {{ else }} + {{ $opts := dict "minify" true }} + {{ with . | js.Build $opts | fingerprint }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ end }} + {{ end }} +{{ end }} +``` + +## Options + +targetPath +: (`string`) If not set, the source path will be used as the base target path. +Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. + +params +: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g. + +```go-html-template +{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} +``` +And then in your JS file: + +```js +import * as params from '@params'; +``` + +Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly. + +minify +: (`bool`)Let `js.Build` handle the minification. + +inject +: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject + +shims +: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: + +```go-html-template +{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} +{{ $js = $js | js.Build dict "shims" $shims }} +``` + +The _shim_ files may look like these: + +```js +// js/shims/react.js +module.exports = window.React; +``` + +```js +// js/shims/react-dom.js +module.exports = window.ReactDOM; +``` + +With the above, these imports should work in both scenarios: + +```js +import * as React from 'react' +import * as ReactDOM from 'react-dom'; +``` + +target +: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`. + +externals +: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external + +defines +: (`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. + +```go-html-template +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} +``` + +format +: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag. + +sourceMap +: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created. + +### Import JS code from /assets + +`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this: + +```js +import { hello } from 'my/module'; +``` + +And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system. + +```js +import { hello3 } from 'my/module/hello3'; +``` + +Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`. + +Any imports starting with `.` is resolved relative to the current file: + +```js +import { hello4 } from './lib'; +``` + +For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g: + +```js +import * as data from 'my/module/data.json'; +``` + +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. + +Also note the new `params` option that can be passed from template to your JS files, e.g.: + +```go-html-template +{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} +``` +And then in your JS file: + +```js +import * as params from '@params'; +``` + +Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build). + +## Node.js dependencies + +Use the `js.Build` function to include Node.js dependencies. + +Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. + +The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder. + +{{% note %}} +If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. +{{% /note %}} + +## Examples + +```go-html-template +{{ $built := resources.Get "js/index.js" | js.Build "main.js" }} +``` + +Or with options: + +```go-html-template +{{ $externals := slice "react" "react-dom" }} +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} + +{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }} +{{ $built := resources.Get "scripts/main.js" | js.Build $opts }} +<script src="{{ $built.RelPermalink }}" defer></script> +``` diff --git a/docs/content/en/functions/js/_index.md b/docs/content/en/functions/js/_index.md new file mode 100644 index 000000000..3356e7c7b --- /dev/null +++ b/docs/content/en/functions/js/_index.md @@ -0,0 +1,12 @@ +--- +title: JavaScript functions +linkTitle: js +description: Template functions to work with JavaScript and TypeScript files. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with JavaScript and TypeScript files. diff --git a/docs/content/en/functions/lang/FormatAccounting.md b/docs/content/en/functions/lang/FormatAccounting.md index 974dc4a1a..70365c216 100644 --- a/docs/content/en/functions/lang/FormatAccounting.md +++ b/docs/content/en/functions/lang/FormatAccounting.md @@ -1,27 +1,21 @@ --- title: lang.FormatAccounting -description: Returns a currency representation of a number for the given currency and precision for the current language in accounting notation. -categories: [functions] +description: Returns a currency representation of a number for the given currency and precision for the current language and region in accounting notation. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatAccounting 2 "NOK" }} → NOK512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatCurrency.md b/docs/content/en/functions/lang/FormatCurrency.md index b29a807fe..bd83c2ec5 100644 --- a/docs/content/en/functions/lang/FormatCurrency.md +++ b/docs/content/en/functions/lang/FormatCurrency.md @@ -1,27 +1,21 @@ --- title: lang.FormatCurrency -description: Returns a currency representation of a number for the given currency and precision for the current language. -categories: [functions] +description: Returns a currency representation of a number for the given currency and precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string - signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent + signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatCurrency 2 "USD" }} → $512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatNumber.md b/docs/content/en/functions/lang/FormatNumber.md index dd878fdef..597df742a 100644 --- a/docs/content/en/functions/lang/FormatNumber.md +++ b/docs/content/en/functions/lang/FormatNumber.md @@ -1,27 +1,21 @@ --- title: lang.FormatNumber -description: Returns a numeric representation of a number with the given precision for the current language. -categories: [functions] +description: Returns a numeric representation of a number with the given precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumberCustom + - functions/lang/FormatPercent returnType: string signatures: [lang.FormatNumber PRECISION NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatNumber 2 }} → 512.50 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatNumberCustom.md b/docs/content/en/functions/lang/FormatNumberCustom.md index 97b022567..0b72f4983 100644 --- a/docs/content/en/functions/lang/FormatNumberCustom.md +++ b/docs/content/en/functions/lang/FormatNumberCustom.md @@ -1,31 +1,26 @@ --- title: lang.FormatNumberCustom description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatPercent returnType: string signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent aliases: ['/functions/numfmt/'] --- This function formats a number with the given precision. The first options parameter is a space-delimited string of characters to represent negativity, the decimal point, and grouping. The default value is `- . ,`. The second options parameter defines an alternate delimiting character. -Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1. +Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1. For a simpler function that adapts to the current language, see [`lang.FormatNumber`]. - ```go-html-template {{ lang.FormatNumberCustom 2 12345.6789 }} → 12,345.68 {{ lang.FormatNumberCustom 2 12345.6789 "- , ." }} → 12.345,68 @@ -34,8 +29,6 @@ For a simpler function that adapts to the current language, see [`lang.FormatNum {{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346 ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} [`lang.FormatNumber`]: /functions/lang/formatnumber diff --git a/docs/content/en/functions/lang/FormatPercent.md b/docs/content/en/functions/lang/FormatPercent.md index dd2042490..529ada67b 100644 --- a/docs/content/en/functions/lang/FormatPercent.md +++ b/docs/content/en/functions/lang/FormatPercent.md @@ -1,27 +1,21 @@ --- title: lang.FormatPercent -description: Returns a percentage representation of a number with the given precision for the current language. -categories: [functions] +description: Returns a percentage representation of a number with the given precision for the current language and region. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/lang/FormatAccounting + - functions/lang/FormatCurrency + - functions/lang/FormatNumber + - functions/lang/FormatNumberCustom returnType: string signatures: [lang.FormatPercent PRECISION NUMBER] -relatedFunctions: - - lang.FormatAccounting - - lang.FormatCurrency - - lang.FormatNumber - - lang.FormatNumberCustom - - lang.FormatPercent --- ```go-html-template {{ 512.5032 | lang.FormatPercent 2 }} → 512.50% ``` -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} +{{% include "functions/_common/locales.md" %}} diff --git a/docs/content/en/functions/lang/Merge.md b/docs/content/en/functions/lang/Merge.md index b3d21cd7a..75f5cdf01 100644 --- a/docs/content/en/functions/lang/Merge.md +++ b/docs/content/en/functions/lang/Merge.md @@ -1,31 +1,27 @@ --- title: lang.Merge description: Merge missing translations from other languages. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: any signatures: [lang.Merge FROM TO] -relatedFunctions: [] aliases: [/functions/lang.merge] --- As an example: -```bash +```sh {{ $pages := .Site.RegularPages | lang.Merge $frSite.RegularPages | lang.Merge $enSite.RegularPages }} ``` Will "fill in the gaps" in the current site with, from left to right, content from the French site, and lastly the English. - A more practical example is to fill in the missing translations from the other languages: -```bash +```sh {{ $pages := .Site.RegularPages }} {{ range .Site.Home.Translations }} {{ $pages = $pages | lang.Merge .Site.RegularPages }} diff --git a/docs/content/en/functions/lang/Translate.md b/docs/content/en/functions/lang/Translate.md index 718d8cfb2..630098a96 100644 --- a/docs/content/en/functions/lang/Translate.md +++ b/docs/content/en/functions/lang/Translate.md @@ -1,23 +1,19 @@ --- title: lang.Translate -linkTitle: i18n description: Translates a string using the translation tables in the i18n directory. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [i18n,T] +action: + aliases: [T, i18n] + related: [] returnType: string signatures: ['lang.Translate KEY [CONTEXT]'] -relatedFunctions: [] aliases: [/functions/i18n] --- Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory. -``` +```text i18n/ ├── en.toml └── pl.toml @@ -34,12 +30,10 @@ The Unicode [CLDR Plural Rules chart] describes the pluralization categories for The English translation table: -{{< code-toggle file=i18n/en copy=false >}} -# simple translations +{{< code-toggle file=i18n/en >}} privacy = 'privacy' security = 'security' -# translations with pluralization [day] one = 'day' other = 'days' @@ -51,12 +45,10 @@ other = '{{ . }} days' The Polish translation table: -{{< code-toggle file=i18n/pl copy=false >}} -# simple translations +{{< code-toggle file=i18n/pl >}} privacy = 'prywatność' security = 'bezpieczeństwo' -# translations with pluralization [day] one = 'miesiąc' few = 'miesiące' @@ -108,17 +100,17 @@ When viewing the Polish language site: {{ T "day_with_count" 5 }} → 5 miesięcy ``` -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. +In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization. Translation table: -{{< code-toggle file=i18n/en copy=false >}} +{{< code-toggle file=i18n/en >}} [age] one = '{{ .name }} is {{ .count }} year old.' other = '{{ .name }} is {{ .count }} years old.' {{< /code-toggle >}} -Template: +Template code: ```go-html-template {{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old. diff --git a/docs/content/en/functions/lang/_index.md b/docs/content/en/functions/lang/_index.md new file mode 100644 index 000000000..934d97bff --- /dev/null +++ b/docs/content/en/functions/lang/_index.md @@ -0,0 +1,12 @@ +--- +title: Lang functions +linkTitle: lang +description: Template functions to adapt your site to meet language and regional requirements. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to adapt your site to meet language and regional requirements. diff --git a/docs/content/en/functions/math/Abs.md b/docs/content/en/functions/math/Abs.md new file mode 100644 index 000000000..682b8426f --- /dev/null +++ b/docs/content/en/functions/math/Abs.md @@ -0,0 +1,17 @@ +--- +title: math.Abs +description: Returns the absolute value of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: float64 + signatures: [math.Abs VALUE] +--- + +{{< new-in 0.112.0 >}} + +```go-html-template +{{ math.Abs -2.1 }} → 2.1 +``` diff --git a/docs/content/en/functions/math/Add.md b/docs/content/en/functions/math/Add.md new file mode 100644 index 000000000..afa8d48aa --- /dev/null +++ b/docs/content/en/functions/math/Add.md @@ -0,0 +1,24 @@ +--- +title: math.Add +description: Adds two or more numbers. +categories: [] +keywords: [] +action: + aliases: [add] + related: + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Add VALUE VALUE...] +--- + +If one of the numbers is a [`float`], the result is a `float`. + +```go-html-template +{{ add 12 3 2 }} → 17 +``` + +[`float`]: /getting-started/glossary/#float diff --git a/docs/content/en/functions/math/Ceil.md b/docs/content/en/functions/math/Ceil.md new file mode 100644 index 000000000..9f74991c3 --- /dev/null +++ b/docs/content/en/functions/math/Ceil.md @@ -0,0 +1,17 @@ +--- +title: math.Ceil +description: Returns the least integer value greater than or equal to the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Floor + - functions/math/Round + returnType: float64 + signatures: [math.Ceil VALUE] +--- + +```go-html-template +{{ math.Ceil 2.1 }} → 3 +``` diff --git a/docs/content/en/functions/math/Counter.md b/docs/content/en/functions/math/Counter.md new file mode 100644 index 000000000..7f53bdd0c --- /dev/null +++ b/docs/content/en/functions/math/Counter.md @@ -0,0 +1,35 @@ +--- +title: math.Counter +description: Increments and returns a global counter. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: uint64 + signatures: [math.Counter] +--- + +The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1. + +```go-html-template +{{ warnf "single.html called %d times" math.Counter }} +``` + +```sh +WARN single.html called 1 times +WARN single.html called 2 times +WARN single.html called 3 times +``` + +Use this function to: + +- Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages +- Create unique target paths for the `resources.FromString` function where the target path is also the cache key + +[`warnf`]: /functions/fmt/warnf +[`resources.FromString`]: /functions/resources/fromstring + +{{% note %}} +Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. +{{% /note %}} diff --git a/docs/content/en/functions/math/Div.md b/docs/content/en/functions/math/Div.md new file mode 100644 index 000000000..530474a78 --- /dev/null +++ b/docs/content/en/functions/math/Div.md @@ -0,0 +1,24 @@ +--- +title: math.Div +description: Divides the first number by one or more numbers. +categories: [] +keywords: [] +action: + aliases: [div] + related: + - functions/math/Add + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Div VALUE VALUE...] +--- + +If one of the numbers is a [`float`], the result is a `float`. + +```go-html-template +{{ div 12 3 2 }} → 2 +``` + +[`float`]: /getting-started/glossary/#float diff --git a/docs/content/en/functions/math/Floor.md b/docs/content/en/functions/math/Floor.md new file mode 100644 index 000000000..10ad758b6 --- /dev/null +++ b/docs/content/en/functions/math/Floor.md @@ -0,0 +1,17 @@ +--- +title: math.Floor +description: Returns the greatest integer value less than or equal to the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Ceil + - functions/math/Round + returnType: float64 + signatures: [math.Floor VALUE] +--- + +```go-html-template +{{ math.Floor 1.9 }} → 1 +``` diff --git a/docs/content/en/functions/math/Log.md b/docs/content/en/functions/math/Log.md new file mode 100644 index 000000000..84edcb288 --- /dev/null +++ b/docs/content/en/functions/math/Log.md @@ -0,0 +1,15 @@ +--- +title: math.Log +description: Returns the natural logarithm of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: float64 + signatures: [math.Log VALUE] +--- + +```go-html-template +{{ math.Log 42 }} → 3.737 +``` diff --git a/docs/content/en/functions/math/Max.md b/docs/content/en/functions/math/Max.md new file mode 100644 index 000000000..9beff5630 --- /dev/null +++ b/docs/content/en/functions/math/Max.md @@ -0,0 +1,16 @@ +--- +title: math.Max +description: Returns the greater of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Min + returnType: float64 + signatures: [math.Max VALUE...] +--- + +```go-html-template +{{ math.Max 1 (slice 2 3) 4 }} → 4 +``` diff --git a/docs/content/en/functions/math/Min.md b/docs/content/en/functions/math/Min.md new file mode 100644 index 000000000..79e464c74 --- /dev/null +++ b/docs/content/en/functions/math/Min.md @@ -0,0 +1,16 @@ +--- +title: math.Min +description: Returns the smaller of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Max + returnType: float64 + signatures: [math.Min VALUE...] +--- + +```go-html-template +{{ math.Min 1 (slice 2 3) 4 }} → 1 +``` diff --git a/docs/content/en/functions/math/Mod.md b/docs/content/en/functions/math/Mod.md new file mode 100644 index 000000000..d312730c5 --- /dev/null +++ b/docs/content/en/functions/math/Mod.md @@ -0,0 +1,16 @@ +--- +title: math.Mod +description: Returns the modulus of two integers. +categories: [] +keywords: [] +action: + aliases: [mod] + related: + - functions/math/ModBool + returnType: int64 + signatures: [math.Mod VALUE1 VALUE2] +--- + +```go-html-template +{{ mod 15 3 }} → 0 +``` diff --git a/docs/content/en/functions/math/ModBool.md b/docs/content/en/functions/math/ModBool.md new file mode 100644 index 000000000..d915ff614 --- /dev/null +++ b/docs/content/en/functions/math/ModBool.md @@ -0,0 +1,16 @@ +--- +title: math.ModBool +description: Reports whether the modulus of two integers equals 0. +categories: [] +keywords: [] +action: + aliases: [modBool] + related: + - functions/math/Mod + returnType: bool + signatures: [math.ModBool VALUE1 VALUE2] +--- + +```go-html-template +{{ modBool 15 3 }} → true +``` diff --git a/docs/content/en/functions/math/Mul.md b/docs/content/en/functions/math/Mul.md new file mode 100644 index 000000000..6824599e3 --- /dev/null +++ b/docs/content/en/functions/math/Mul.md @@ -0,0 +1,24 @@ +--- +title: math.Mul +description: Multiplies two or more numbers. +categories: [] +keywords: [] +action: + aliases: [mul] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Product + - functions/math/Sub + - functions/math/Sum + returnType: any + signatures: [math.Mul VALUE VALUE...] +--- + +If one of the numbers is a [`float`], the result is a `float`. + +```go-html-template +{{ mul 12 3 2 }} → 72 +``` + +[`float`]: /getting-started/glossary/#float diff --git a/docs/content/en/functions/math/Pow.md b/docs/content/en/functions/math/Pow.md new file mode 100644 index 000000000..5a1482d73 --- /dev/null +++ b/docs/content/en/functions/math/Pow.md @@ -0,0 +1,16 @@ +--- +title: math.Pow +description: Returns the first number raised to the power of the second number. +categories: [] +keywords: [] +action: + aliases: [pow] + related: + - functions/math/Sqrt + returnType: float64 + signatures: [math.Pow VALUE1 VALUE2] +--- + +```go-html-template +{{ math.Pow 2 3 }} → 8 +``` diff --git a/docs/content/en/functions/math/Product.md b/docs/content/en/functions/math/Product.md new file mode 100644 index 000000000..d94df4f1b --- /dev/null +++ b/docs/content/en/functions/math/Product.md @@ -0,0 +1,22 @@ +--- +title: math.Product +description: Returns the product of all numbers. Accepts scalars, slices, or both. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Sub + - functions/math/Sum + returnType: float64 + signatures: [math.Product VALUE...] +--- + +{{< new-in 0.114.0 >}} + +```go-html-template +{{ math.Product 1 (slice 2 3) 4 }} → 24 +``` diff --git a/docs/content/en/functions/math/Round.md b/docs/content/en/functions/math/Round.md new file mode 100644 index 000000000..e0678eb78 --- /dev/null +++ b/docs/content/en/functions/math/Round.md @@ -0,0 +1,17 @@ +--- +title: math.Round +description: Returns the nearest integer, rounding half away from zero. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Ceil + - functions/math/Floor + returnType: float64 + signatures: [math.Round VALUE] +--- + +```go-html-template +{{ math.Round 1.5 }} → 2 +``` diff --git a/docs/content/en/functions/math/Sqrt.md b/docs/content/en/functions/math/Sqrt.md new file mode 100644 index 000000000..436cb31c3 --- /dev/null +++ b/docs/content/en/functions/math/Sqrt.md @@ -0,0 +1,16 @@ +--- +title: math.Sqrt +description: Returns the square root of the given number. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/math/Pow + returnType: float64 + signatures: [math.Sqrt VALUE] +--- + +```go-html-template +{{ math.Sqrt 81 }} → 9 +``` diff --git a/docs/content/en/functions/math/Sub.md b/docs/content/en/functions/math/Sub.md new file mode 100644 index 000000000..2865ac191 --- /dev/null +++ b/docs/content/en/functions/math/Sub.md @@ -0,0 +1,23 @@ +--- +title: math.Sub +description: Subtracts one or more numbers from the first number. +categories: [] +action: + aliases: [sub] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sum + returnType: any + signatures: [math.Sub VALUE VALUE...] +--- + +If one of the numbers is a [`float`], the result is a `float`. + +```go-html-template +{{ sub 12 3 2 }} → 7 +``` + +[`float`]: /getting-started/glossary/#float diff --git a/docs/content/en/functions/math/Sum.md b/docs/content/en/functions/math/Sum.md new file mode 100644 index 000000000..eba03f72d --- /dev/null +++ b/docs/content/en/functions/math/Sum.md @@ -0,0 +1,21 @@ +--- +title: math.Sum +description: Returns the sum of all numbers. Accepts scalars, slices, or both. +categories: [] +action: + aliases: [] + related: + - functions/math/Add + - functions/math/Div + - functions/math/Mul + - functions/math/Product + - functions/math/Sub + returnType: float64 + signatures: [math.Sum VALUE...] +--- + +{{< new-in 0.114.0 >}} + +```go-html-template +{{ math.Sum 1 (slice 2 3) 4 }} → 10 +``` diff --git a/docs/content/en/functions/math/_index.md b/docs/content/en/functions/math/_index.md new file mode 100644 index 000000000..76713bc99 --- /dev/null +++ b/docs/content/en/functions/math/_index.md @@ -0,0 +1,11 @@ +--- +title: Math functions +linkTitle: math +description: Template functions to perform mathematical operations. +categories: [] +menu: + docs: + parent: functions +--- + +Use these functions to perform mathematical operations. diff --git a/docs/content/en/functions/math/index.md b/docs/content/en/functions/math/index.md deleted file mode 100644 index fd4d10a31..000000000 --- a/docs/content/en/functions/math/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: math -description: Hugo provides mathematical operators in templates. -categories: [functions] -keywords: [] - -menu: - docs: - parent: functions -function: - aliases: [] - returnType: - signatures: [] -relatedFunctions: [] ---- - -| Function | Description | Example | -|-----------------|-----------------------------------------------------------------------------|---------------------------------------------------| -| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` → `17` | -| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` → `3.1` | -| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` → `7` | -| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` → `0.5` | -| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` → `72` | -| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` → `6.2` | -| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` → `2` | -| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` → `1.5` | -| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` → `0` | -| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` → `true` | -| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` → `2.1` | -| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` → `3` | -| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` → `1` | -| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` → `3.737` | -| `math.Max` | Returns the greater of all numbers. Accepts scalars, slices, or both. | `{{ math.Max 1 (slice 2 3) 4 }}` → `4` | -| `math.Min` | Returns the smaller of all numbers. Accepts scalars, slices, or both. | `{{ math.Min 1 (slice 2 3) 4 }}` → `1` | -| `math.Product` | Returns the product of all numbers. Accepts scalars, slices, or both. | `{{ math.Product 1 (slice 2 3) 4 }}` → `24` | -| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` → `8` | -| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` → `2` | -| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` → `9` | -| `math.Sum` | Returns the sum of all numbers. Accepts scalars, slices, or both. | `{{ math.Sum 1 (slice 2 3) 4 }}` → `10` | diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md new file mode 100644 index 000000000..50c793685 --- /dev/null +++ b/docs/content/en/functions/openapi3/Unmarshal.md @@ -0,0 +1,76 @@ +--- +title: openapi3.Unmarshal +description: Unmarshals the given resource into an OpenAPI 3 document. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: openapi3.OpenAPIDocument + signatures: ['openapi3.Unmarshal RESOURCE'] +--- + +Use the `openapi3.Unmarshal` function with [global], [page], or [remote] resources. + +[global]: /getting-started/glossary/#global-resource +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource +[OpenAPI]: https://www.openapis.org/ + +For example, to work with a remote [OpenAPI] defintion: + +```go-html-template +{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }} +{{ $api := "" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $api = . | openapi3.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +To inspect the data structure: + +```go-html-template +<pre>{{ debug.Dump $api }}</pre> +``` + +To list the GET and POST operations for each of the API paths: + +```go-html-template +{{ range $path, $details := $api.Paths }} + <p>{{ $path }}</p> + <dl> + {{ with $details.Get }} + <dt>GET</dt> + <dd>{{ .Summary }}</dd> + {{ end }} + {{ with $details.Post }} + <dt>POST</dt> + <dd>{{ .Summary }}</dd> + {{ end }} + </dl> +{{ end }} +``` + +Hugo renders this to: + + +```html +<p>/pets</p> +<dl> + <dt>GET</dt> + <dd>List all pets</dd> + <dt>POST</dt> + <dd>Create a pet</dd> +</dl> +<p>/pets/{petId}</p> +<dl> + <dt>GET</dt> + <dd>Info for a specific pet</dd> +</dl> +``` diff --git a/docs/content/en/functions/openapi3/_index.md b/docs/content/en/functions/openapi3/_index.md new file mode 100644 index 000000000..9b6aa9584 --- /dev/null +++ b/docs/content/en/functions/openapi3/_index.md @@ -0,0 +1,12 @@ +--- +title: OpenAPI functions +linkTitle: openapi3 +description: Template functions to work with OpenAPI 3 definitions. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with OpenAPI 3 definitions. diff --git a/docs/content/en/functions/os/FileExists.md b/docs/content/en/functions/os/FileExists.md index 52cfe32c8..b8104a066 100644 --- a/docs/content/en/functions/os/FileExists.md +++ b/docs/content/en/functions/os/FileExists.md @@ -1,22 +1,17 @@ --- title: os.FileExists -linkTitle: fileExists description: Reports whether the file or directory exists. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [fileExists] + related: + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/ReadFile + - functions/os/Stat returnType: bool signatures: [os.FileExists PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/fileexists] --- @@ -36,11 +31,11 @@ content/ The function returns these values: ```go-html-template -{{ os.FileExists "content" }} → true -{{ os.FileExists "content/news" }} → true -{{ os.FileExists "content/news/article-1" }} → false -{{ os.FileExists "content/news/article-1.md" }} → true -{{ os.FileExists "news" }} → true -{{ os.FileExists "news/article-1" }} → false -{{ os.FileExists "news/article-1.md" }} → true +{{ fileExists "content" }} → true +{{ fileExists "content/news" }} → true +{{ fileExists "content/news/article-1" }} → false +{{ fileExists "content/news/article-1.md" }} → true +{{ fileExists "news" }} → true +{{ fileExists "news/article-1" }} → false +{{ fileExists "news/article-1.md" }} → true ``` diff --git a/docs/content/en/functions/os/Getenv.md b/docs/content/en/functions/os/Getenv.md index 16f73f5aa..084d498ce 100644 --- a/docs/content/en/functions/os/Getenv.md +++ b/docs/content/en/functions/os/Getenv.md @@ -1,35 +1,49 @@ --- title: os.Getenv -linkTitle: getenv description: Returns the value of an environment variable, or an empty string if the environment variable is not set. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [getenv] + related: + - functions/os/FileExists + - functions/os/ReadDir + - functions/os/ReadFile + - functions/os/Stat returnType: string signatures: [os.Getenv VARIABLE] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/getenv] +toc: true --- -Examples: +## Security + +By default, when using the `os.Getenv` function Hugo allows access to: + +- The `CI` environment variable +- Any environment variable beginning with `HUGO_` + +To access other environment variables, adjust your site configuration. For example, to allow access to the `HOME` and `USER` environment variables: + +{{< code-toggle file=hugo >}} +[security.funcs] +getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$'] +{{< /code-toggle >}} + +Read more about Hugo's [security policy]. + +[security policy]: /about/security-model/#security-policy + +## Examples ```go-html-template -{{ os.Getenv "HOME" }} → /home/victor -{{ os.Getenv "USER" }} → victor +{{ getenv "HOME" }} → /home/victor +{{ getenv "USER" }} → victor ``` You can pass values when building your site: -```bash +```sh MY_VAR1=foo MY_VAR2=bar hugo OR @@ -42,8 +56,6 @@ hugo And then retrieve the values within a template: ```go-html-template -{{ os.Getenv "MY_VAR1" }} → foo -{{ os.Getenv "MY_VAR2" }} → bar +{{ getenv "MY_VAR1" }} → foo +{{ getenv "MY_VAR2" }} → bar ``` - -With Hugo v0.91.0 and later, you must explicitly allow access to environment variables. For details, review [Hugo's Security Policy](/about/security-model/#security-policy). By default, environment variables beginning with `HUGO_` are allowed when using the `os.Getenv` function. diff --git a/docs/content/en/functions/os/ReadDir.md b/docs/content/en/functions/os/ReadDir.md index d0ed87bdf..63af850b7 100644 --- a/docs/content/en/functions/os/ReadDir.md +++ b/docs/content/en/functions/os/ReadDir.md @@ -1,22 +1,17 @@ --- title: os.ReadDir -linkTitle: readDir description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [readDir] - returnType: FileInfo + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadFile + - functions/os/Stat + returnType: os.FileInfo signatures: [os.ReadDir PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/readdir] --- @@ -36,7 +31,7 @@ content/ This template code: ```go-html-template -{{ range os.ReadDir "content" }} +{{ range readDir "content" }} {{ .Name }} → {{ .IsDir }} {{ end }} ``` diff --git a/docs/content/en/functions/os/ReadFile.md b/docs/content/en/functions/os/ReadFile.md index 30f2b3056..654e300ac 100644 --- a/docs/content/en/functions/os/ReadFile.md +++ b/docs/content/en/functions/os/ReadFile.md @@ -1,22 +1,17 @@ --- title: os.ReadFile -linkTitle: readFile description: Returns the contents of a file. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [readFile] + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/Stat returnType: string signatures: [os.ReadFile PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/readfile] --- @@ -31,7 +26,7 @@ This is **bold** text. This template code: ```go-html-template -{{ os.ReadFile "README.md" }} +{{ readFile "README.md" }} ``` Produces: diff --git a/docs/content/en/functions/os/Stat.md b/docs/content/en/functions/os/Stat.md index dfef3c815..6b6f668de 100644 --- a/docs/content/en/functions/os/Stat.md +++ b/docs/content/en/functions/os/Stat.md @@ -1,21 +1,17 @@ --- title: os.Stat description: Returns a FileInfo structure describing a file or directory. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: FileInfo + related: + - functions/os/FileExists + - functions/os/Getenv + - functions/os/ReadDir + - functions/os/ReadFile + returnType: os.FileInfo signatures: [os.Stat PATH] -relatedFunctions: - - os.FileExists - - os.Getenv - - os.ReadDir - - os.ReadFile - - os.Stat aliases: [/functions/os.stat] --- diff --git a/docs/content/en/functions/os/_index.md b/docs/content/en/functions/os/_index.md new file mode 100644 index 000000000..c080d0092 --- /dev/null +++ b/docs/content/en/functions/os/_index.md @@ -0,0 +1,12 @@ +--- +title: OS functions +linkTitle: os +description: Template functions to interact with the operating system. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to interact with the operating system. diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md index ea9dfb31a..859f6665b 100644 --- a/docs/content/en/functions/partials/Include.md +++ b/docs/content/en/functions/partials/Include.md @@ -1,22 +1,24 @@ --- title: partials.Include -linkTitle: partial -description: Executes the named partial template. If the partial contains a return statement, returns that value, else returns the rendered output. -categories: [functions] +description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partial] + related: + - functions/go-template/return + - functions/partials/IncludeCached + - functions/go-template/template + - methods/page/Render returnType: any - signatures: ['partials.Include LAYOUT [CONTEXT]'] -relatedFunctions: - - partials.Include - - partials.IncludeCached + signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- +Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type. + +[`return`]: /functions/go-template/return + In this example we have three partial templates: ```text @@ -63,5 +65,21 @@ Then, within the partial template: <p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p> ``` +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. + +[`return`]: /functions/go-template/return [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants +[details]: /functions/go-template/return diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md index ab9a77835..db275fa9e 100644 --- a/docs/content/en/functions/partials/IncludeCached.md +++ b/docs/content/en/functions/partials/IncludeCached.md @@ -1,30 +1,32 @@ --- title: partials.IncludeCached -linkTitle: partialCached -description: Allows for caching of partials that do not need to be re-rendered on every invocation. -categories: [functions] +description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [partialCached] + related: + - functions/go-template/return + - functions/partials/Include + - functions/go-template/template + - methods/page/Render returnType: any signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] -relatedFunctions: - - partials.Include - - partials.IncludeCached signatures: - - partials.IncludeCached LAYOUT CONTEXT [VARIANT...] - - partialCached LAYOUT CONTEXT [VARIANT...] + - partials.IncludeCached NAME CONTEXT [VARIANT...] + - partialCached NAME CONTEXT [VARIANT...] aliases: [/functions/partialcached] --- -The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. +Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type. -**Note:** Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. +The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. -**Note**: Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. +{{% note %}} +Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. + +Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. +{{% /note %}} Here is the simplest usage: @@ -32,18 +34,32 @@ Here is the simplest usage: {{ partialCached "footer.html" . }} ``` -You can also pass additional arguments to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section: +Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section: -{{< code file="partial-cached-example.html" >}} +{{< code file=partial-cached-example.html >}} {{ partialCached "footer.html" . .Section }} {{< /code >}} -If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need: +Pass additional arguments, of any data type, as needed to create unique variants: ```go-html-template {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings. +The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. + +To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: + +```go-html-template +{{ $result := false }} +{{ if math.ModBool . 2 }} + {{ $result = "even" }} +{{ else }} + {{ $result = "odd" }} +{{ end }} +{{ return $result }} +``` + +See [details][`return`]. -See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/). +[`return`]: /functions/go-template/return diff --git a/docs/content/en/functions/partials/_index.md b/docs/content/en/functions/partials/_index.md new file mode 100644 index 000000000..0a7d4d6d0 --- /dev/null +++ b/docs/content/en/functions/partials/_index.md @@ -0,0 +1,12 @@ +--- +title: Partial functions +linkTitle: partials +description: Template functions to call partial templates. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to call partial templates. diff --git a/docs/content/en/functions/path/Base.md b/docs/content/en/functions/path/Base.md index c00873524..2071f8bea 100644 --- a/docs/content/en/functions/path/Base.md +++ b/docs/content/en/functions/path/Base.md @@ -1,35 +1,26 @@ --- title: path.Base -description: Base returns the last element of a path. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the last element of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Base PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.base] --- -`path.Base` returns the last element of `PATH`. - -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. - ```go-html-template -{{ path.Base "a/news.html" }} → "news.html" -{{ path.Base "news.html" }} → "news.html" -{{ path.Base "a/b/c" }} → "c" -{{ path.Base "/x/y/z/" }} → "z" +{{ path.Base "a/news.html" }} → news.html +{{ path.Base "news.html" }} → news.html +{{ path.Base "a/b/c" }} → c +{{ path.Base "/x/y/z/" }} → z +{{ path.Base "" }} → . ``` diff --git a/docs/content/en/functions/path/BaseName.md b/docs/content/en/functions/path/BaseName.md index a357ed403..4c4340a09 100644 --- a/docs/content/en/functions/path/BaseName.md +++ b/docs/content/en/functions/path/BaseName.md @@ -1,33 +1,28 @@ --- title: path.BaseName -description: BaseName returns the last element of a path, removing the extension if present. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the last element of the given path, removing the extension if present. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.BaseName PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.basename] --- -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. +{{< new-in 0.101.0 >}} ```go-html-template -{{ path.BaseName "a/news.html" }} → "news" -{{ path.BaseName "news.html" }} → "news" -{{ path.BaseName "a/b/c" }} → "c" -{{ path.BaseName "/x/y/z/" }} → "z" +{{ path.BaseName "a/news.html" }} → news +{{ path.BaseName "news.html" }} → news +{{ path.BaseName "a/b/c" }} → c +{{ path.BaseName "/x/y/z/" }} → z +{{ path.BaseName "" }} → . ``` diff --git a/docs/content/en/functions/path/Clean.md b/docs/content/en/functions/path/Clean.md index 98160c568..57a665c03 100644 --- a/docs/content/en/functions/path/Clean.md +++ b/docs/content/en/functions/path/Clean.md @@ -1,35 +1,33 @@ --- title: path.Clean -description: Replaces path separators with slashes (`/`) and removes extraneous separators. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the shortest path name equivalent to the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Clean PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.clean] --- -`path.Clean` replaces path separators with slashes (`/`) and removes extraneous separators, including trailing separators. +See Go's [`path.Clean`] documentation for details. -```go-html-template -{{ path.Clean "foo//bar" }} → "foo/bar" -{{ path.Clean "/foo/bar/" }} → "/foo/bar" -``` - -On a Windows system, if `.File.Path` is `foo\bar.md`, then: +[`path.Clean`]: https://pkg.go.dev/path#Clean ```go-html-template -{{ path.Clean .File.Path }} → "foo/bar.md" +{{ path.Clean "foo/bar" }} → foo/bar +{{ path.Clean "/foo/bar" }} → /foo/bar +{{ path.Clean "/foo/bar/" }} → /foo/bar +{{ path.Clean "/foo//bar/" }} → /foo/bar +{{ path.Clean "/foo/./bar/" }} → /foo/bar +{{ path.Clean "/foo/../bar/" }} → /bar +{{ path.Clean "/../foo/../bar/" }} → /bar +{{ path.Clean "" }} → . ``` diff --git a/docs/content/en/functions/path/Dir.md b/docs/content/en/functions/path/Dir.md index 0a2928696..6d5e5c975 100644 --- a/docs/content/en/functions/path/Dir.md +++ b/docs/content/en/functions/path/Dir.md @@ -1,36 +1,27 @@ --- title: path.Dir -description: Dir returns all but the last element of a path. -categories: [functions] +description: Replaces path separators with slashes (/) and returns all but the last element of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Ext + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Dir PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.dir] --- -`path.Dir` returns all but the last element of `PATH`, typically `PATH`'s directory. - -The returned path will never end in a slash. -If `PATH` is empty, `.` is returned. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. - ```go-html-template -{{ path.Dir "a/news.html" }} → "a" -{{ path.Dir "news.html" }} → "." -{{ path.Dir "a/b/c" }} → "a/b" -{{ path.Dir "/x/y/z" }} → "/x/y" +{{ path.Dir "a/news.html" }} → a +{{ path.Dir "news.html" }} → . +{{ path.Dir "a/b/c" }} → a/b +{{ path.Dir "/a/b/c" }} → /a/b +{{ path.Dir "/a/b/c/" }} → /a/b/c +{{ path.Dir "" }} → . ``` diff --git a/docs/content/en/functions/path/Ext.md b/docs/content/en/functions/path/Ext.md index 6b5685948..f3e47aecd 100644 --- a/docs/content/en/functions/path/Ext.md +++ b/docs/content/en/functions/path/Ext.md @@ -1,33 +1,24 @@ --- title: path.Ext -description: Ext returns the file name extension of a path. -categories: [functions] +description: Replaces path separators with slashes (`/`) and returns the file name extension of the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Join + - functions/path/Split returnType: string signatures: [path.Ext PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.ext] --- -`path.Ext` returns the file name extension `PATH`. - -The extension is the suffix beginning at the final dot in the final slash-separated element `PATH`; -it is empty if there is no dot. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. +The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot. ```go-html-template -{{ path.Ext "a/b/c/news.html" }} → ".html" +{{ path.Ext "a/b/c/news.html" }} → .html ``` diff --git a/docs/content/en/functions/path/Join.md b/docs/content/en/functions/path/Join.md index 4f5c51c0f..dc701b731 100644 --- a/docs/content/en/functions/path/Join.md +++ b/docs/content/en/functions/path/Join.md @@ -1,34 +1,36 @@ --- title: path.Join -description: Join path elements into a single path. -categories: [functions] +description: Replaces path separators with slashes (`/`), joins the given path elements into a single path, and returns the shortest path name equivalent to the result. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Split + - functions/urls/JoinPath returnType: string signatures: [path.Join ELEMENT...] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split - - urls.JoinPath aliases: [/functions/path.join] --- -`path.Join` joins path elements into a single path, adding a separating slash if necessary. -All empty strings are ignored. +See Go's [`path.Join`] and [`path.Clean`] documentation for details. + +[`path.Clean`]: https://pkg.go.dev/path#Clean +[`path.Join`]: https://pkg.go.dev/path#Join -**Note:** All path elements on Windows are converted to slash ('/') separators. ```go-html-template -{{ path.Join "partial" "news.html" }} → "partial/news.html" -{{ path.Join "partial/" "news.html" }} → "partial/news.html" -{{ path.Join "foo/baz" "bar" }} → "foo/baz/bar" +{{ path.Join "partial" "news.html" }} → partial/news.html +{{ path.Join "partial/" "news.html" }} → partial/news.html +{{ path.Join "foo/bar" "baz" }} → foo/bar/baz +{{ path.Join "foo" "bar" "baz" }} → foo/bar/baz +{{ path.Join "foo" "" "baz" }} → foo/baz +{{ path.Join "foo" "." "baz" }} → foo/baz +{{ path.Join "foo" ".." "baz" }} → baz +{{ path.Join "/.." "foo" ".." "baz" }} → baz ``` diff --git a/docs/content/en/functions/path/Split.md b/docs/content/en/functions/path/Split.md index bde412743..329d73954 100644 --- a/docs/content/en/functions/path/Split.md +++ b/docs/content/en/functions/path/Split.md @@ -1,43 +1,34 @@ --- title: path.Split -description: Split path immediately following the final slash. -categories: [functions] +description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: DirFile + related: + - functions/path/Base + - functions/path/BaseName + - functions/path/Clean + - functions/path/Dir + - functions/path/Ext + - functions/path/Join + returnType: paths.DirFile signatures: [path.Split PATH] -relatedFunctions: - - path.Base - - path.BaseName - - path.Clean - - path.Dir - - path.Ext - - path.Join - - path.Split aliases: [/functions/path.split] --- -`path.Split` splits `PATH` immediately following the final slash, separating it into a directory and a base component. - -The returned values have the property that `PATH` = `DIR`+`BASE`. -If there is no slash in `PATH`, it returns an empty directory and the base is set to `PATH`. - -**Note:** On Windows, `PATH` is converted to slash (`/`) separators. +If there is no slash in the given path, `path.Split` returns an empty directory, and file set to path. The returned values have the property that path = dir+file. ```go-html-template {{ $dirFile := path.Split "a/news.html" }} -{{ $dirFile.Dir }} → "a/" -{{ $dirFile.File }} → "news.html" +{{ $dirFile.Dir }} → a/ +{{ $dirFile.File }} → news.html {{ $dirFile := path.Split "news.html" }} -{{ $dirFile.Dir }} → "" -{{ $dirFile.File }} → "news.html" +{{ $dirFile.Dir }} → "" (empty string) +{{ $dirFile.File }} → news.html {{ $dirFile := path.Split "a/b/c" }} -{{ $dirFile.Dir }} → "a/b/" -{{ $dirFile.File }} → "c" +{{ $dirFile.Dir }} → a/b/ +{{ $dirFile.File }} → c ``` diff --git a/docs/content/en/functions/path/_index.md b/docs/content/en/functions/path/_index.md new file mode 100644 index 000000000..2d7ce8e90 --- /dev/null +++ b/docs/content/en/functions/path/_index.md @@ -0,0 +1,12 @@ +--- +title: Path functions +linkTitle: path +description: Template functions to work with file paths. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with file paths. diff --git a/docs/content/en/functions/reflect/IsMap.md b/docs/content/en/functions/reflect/IsMap.md index 7d89bb38a..ada5a221d 100644 --- a/docs/content/en/functions/reflect/IsMap.md +++ b/docs/content/en/functions/reflect/IsMap.md @@ -1,19 +1,14 @@ --- title: reflect.IsMap -description: Reports whether the value is a map. -categories: [functions] +description: Reports whether the given value is a map. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/reflect/IsSlice returnType: bool signatures: [reflect.IsMap INPUT] -namespace: reflect -relatedFunctions: - - reflect.IsMap - - reflect.IsSlice aliases: [/functions/reflect.ismap] --- diff --git a/docs/content/en/functions/reflect/IsSlice.md b/docs/content/en/functions/reflect/IsSlice.md index 09bab7127..cda24a5e1 100644 --- a/docs/content/en/functions/reflect/IsSlice.md +++ b/docs/content/en/functions/reflect/IsSlice.md @@ -1,19 +1,14 @@ --- title: reflect.IsSlice -description: Reports whether the value is a slice. -categories: [functions] +description: Reports whether the given value is a slice. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/reflect/IsMap returnType: bool signatures: [reflect.IsSlice INPUT] -namespace: reflect -relatedFunctions: - - reflect.IsMap - - reflect.IsSlice aliases: [/functions/reflect.isslice] --- diff --git a/docs/content/en/functions/reflect/_index.md b/docs/content/en/functions/reflect/_index.md new file mode 100644 index 000000000..711908ee2 --- /dev/null +++ b/docs/content/en/functions/reflect/_index.md @@ -0,0 +1,12 @@ +--- +title: Reflect functions +linkTitle: reflect +description: Template functions to determine a value's data type. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to determine a value's data type. diff --git a/docs/content/en/functions/resources/Babel.md b/docs/content/en/functions/resources/Babel.md new file mode 100644 index 000000000..57ddb7d23 --- /dev/null +++ b/docs/content/en/functions/resources/Babel.md @@ -0,0 +1,88 @@ +--- +title: resources.Babel +description: Compiles the given JavaScript resource with Babel. +categories: [] +keywords: [] +action: + aliases: [babel] + related: + - functions/js/Build + - functions/resources/Fingerprint + - functions/resources/Minify + returnType: resource.Resource + signatures: ['resources.Babel [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ if hugo.IsDevelopment }} + {{ with . | babel }} + <script src="{{ .RelPermalink }}"></script> + {{ end }} + {{ else }} + {{ $opts := dict "minified" true }} + {{ with . | babel $opts | fingerprint }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ end }} + {{ end }} +{{ end }} +``` + +## Setup + +Step 1 +: Install [Node.js](https://nodejs.org/en/download) + +Step 2 +: Install the required Node.js packages in the root of your project. + +```sh +npm install --save-dev @babel/core @babel/cli +``` + +Step 3 +: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: + +{{< code-toggle file=hugo >}} +[security.exec] + allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$'] +{{< /code-toggle >}} + +## Configuration + +We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.: + +```js +module.exports = { + presets: [ + [ + require("@babel/preset-env"), + { + useBuiltIns: "entry", + corejs: 3, + }, + ], + ], +}; +``` + +## Options + +config +: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` in your project. More information on these configuration files can be found here: [babel configuration](https://babeljs.io/docs/en/configuration). + +minified +: (`bool`) Save as many bytes as possible when printing + +noComments +: (`bool`) Write comments to generated output (true by default) + +compact +: (`bool`) Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set. + +verbose +: (`bool`) Log everything + +sourceMap +: (`string`) Output `inline` or `external` sourcemap from the babel compile. External sourcemaps will be written to the target with the output file name + ".map". Input sourcemaps can be read from js.Build and node modules and combined into the output sourcemaps. diff --git a/docs/content/en/functions/resources/ByType.md b/docs/content/en/functions/resources/ByType.md new file mode 100644 index 000000000..a5df3befb --- /dev/null +++ b/docs/content/en/functions/resources/ByType.md @@ -0,0 +1,34 @@ +--- +title: resources.ByType +description: Returns a collection of global resources of the given media type, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resources + signatures: [resources.ByType MEDIATYPE] +--- + +The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`. + +```go-html-template +{{ range resources.ByType "image" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.ByType`] method on the Page object. + +[`Resources.ByType`]: /methods/page/resources +{{% /note %}} + +[media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/docs/content/en/functions/resources/Concat.md b/docs/content/en/functions/resources/Concat.md new file mode 100644 index 000000000..3bdf975bf --- /dev/null +++ b/docs/content/en/functions/resources/Concat.md @@ -0,0 +1,21 @@ +--- +title: resources.Concat +description: Concatenates a slice of resources. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: resource.Resource + signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] +--- + +```go-html-template +{{ $plugins := resources.Get "js/plugins.js" }} +{{ $global := resources.Get "js/global.js" }} +{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }} +``` + +Asset files of the same [media type] can be bundled into one resource using the `resources.Concat` function which takes two arguments, the target path for the created resource bundle and a slice of resource objects to be concatenated. + +[media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/docs/content/en/functions/resources/Copy.md b/docs/content/en/functions/resources/Copy.md new file mode 100644 index 000000000..f8e962aee --- /dev/null +++ b/docs/content/en/functions/resources/Copy.md @@ -0,0 +1,32 @@ +--- +title: resources.Copy +description: Copies the given resource to the target path. +categories: [] +action: + aliases: [] + related: [] + returnType: resource.Resource + signatures: [resources.Copy TARGETPATH RESOURCE] +--- + +{{< new-in 0.100.0 >}} + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with resources.Copy "img/new-image-name.jpg" . }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +The relative URL of the new published resource will be: + +```text +/img/new-image-name.jpg +``` + +The target path must be different than the source path, as shown in the example above. + +{{% note %}} +Use the `resources.Copy` function with global, page, and remote resources. +{{% /note %}} diff --git a/docs/content/en/functions/resources/ExecuteAsTemplate.md b/docs/content/en/functions/resources/ExecuteAsTemplate.md new file mode 100644 index 000000000..d17f0580c --- /dev/null +++ b/docs/content/en/functions/resources/ExecuteAsTemplate.md @@ -0,0 +1,56 @@ +--- +title: resources.ExecuteAsTemplate +description: Creates a resource from a Go template, parsed and executed with the given context. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/FromString + returnType: resource.Resource + signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] +--- + +Hugo publishes the resource to the target path when you call its`.Publish`, `.Permalink`, or `.RelPermalink` method. The resource is cached, using the target path as the cache key. + +Let's say you have a CSS file that you wish to populate with values from your site configuration: + +{{< code file=assets/css/template.css lang=go-html-template >}} +body { + background-color: {{ site.Params.style.bg_color }}; + color: {{ site.Params.style.text_color }}; +} +{{< /code >}} + +And your site configuration contains: + +{{< code-toggle file=hugo >}} +[params.style] +bg_color = '#fefefe' +text_color = '#222' +{{< /code-toggle >}} + +Place this in your baseof.html template: + +```go-html-template +{{ with resources.Get "css/template.css" }} + {{ with resources.ExecuteAsTemplate "css/main.css" $ . }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ end }} +{{ end }} +``` + +The example above: + +1. Captures the template as a resource +2. Executes the resource as a template, passing the current page in context +3. Publishes the resource to css/main.css + +The result is: + +{{< code file=public/css/main.css >}} +body { + background-color: #fefefe; + color: #222; +} +{{< /code >}} diff --git a/docs/content/en/functions/resources/Fingerprint.md b/docs/content/en/functions/resources/Fingerprint.md new file mode 100644 index 000000000..685214f96 --- /dev/null +++ b/docs/content/en/functions/resources/Fingerprint.md @@ -0,0 +1,42 @@ +--- +title: resources.Fingerprint +description: Cryptographically hashes the content of the given resource. +categories: [] +keywords: [] +action: + aliases: [fingerprint] + related: + - functions/js/Build + - functions/resources/Babel + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/PostProcess + - functions/resources/ToCSS + returnType: resource.Resource + signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] +--- + +```go-html-template +{{ with resources.Get "js/main.js" }} + {{ with . | fingerprint "sha256" }} + <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> + {{ end }} +{{ end }} +``` + +Hugo renders this to something like: + +```html +<script src="/js/main.62e...df1.js" integrity="sha256-Yuh...rfE=" crossorigin="anonymous"></script> +``` + +Although most commonly used with CSS and JavaScript resources, you can use the `resources.Fingerprint` function with any resource type. + +The hash algorithm may be one of `md5`, `sha256` (default), `sha384`, or `sha512`. + +After cryptographically hashing the resource content: + +1. The values returned by the `.Permalink` and `.RelPermalink` methods include the hash sum +2. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum + +[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md new file mode 100644 index 000000000..6c22b5310 --- /dev/null +++ b/docs/content/en/functions/resources/FromString.md @@ -0,0 +1,71 @@ +--- +title: resources.FromString +description: Creates a resource from a string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ExecuteAsTemplate + returnType: resource.Resource + signatures: [resources.FromString TARGETPATH STRING] +--- + +Hugo publishes the resource to the target path when you call its`.Publish`, `.Permalink`, or `.RelPermalink` method. The resource is cached, using the target path as the cache key. + +Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example: + +```json +{ + "build_date": "2023-10-03T10:50:40-07:00", + "hugo_version": "0.120.0", + "last_modified": "2023-10-02T15:21:27-07:00" +} +``` + +Place this in your baseof.html template: + +```go-html-template +{{ if .IsHome }} + {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }} + {{ $m := dict + "hugo_version" hugo.Version + "build_date" (now.Format $rfc3339) + "last_modified" (site.LastChange.Format $rfc3339) + }} + {{ $json := jsonify $m }} + {{ $r := resources.FromString "site.json" $json }} + {{ $r.Publish }} +{{ end }} +``` + +The example above: + +1. Creates a map with the relevant key/value pairs using the [`dict`] function +2. Encodes the map as a JSON string using the [`jsonify`] function +3. Creates a resource from the JSON string using the `resources.FromString` function +4. Publishes the file to the root of the public directory using the resource's `.Publish` method + +Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above: + +```go-html-template +{{ if .IsHome }} + {{ $string := ` + {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }} + {{ $m := dict + "hugo_version" hugo.Version + "build_date" (now.Format $rfc3339) + "last_modified" (site.LastChange.Format $rfc3339) + }} + {{ $json := jsonify $m }} + ` + }} + {{ $r := resources.FromString "" $string }} + {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }} + {{ $r.Publish }} +{{ end }} +``` + +[`dict`]: /functions/collections/dictionary +[`jsonify`]: /functions/encoding/jsonify +[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate diff --git a/docs/content/en/functions/resources/Get.md b/docs/content/en/functions/resources/Get.md new file mode 100644 index 000000000..a8b75d52b --- /dev/null +++ b/docs/content/en/functions/resources/Get.md @@ -0,0 +1,30 @@ +--- +title: resources.Get +description: Returns a global resource from the given path, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/GetMatch + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: [resources.Get PATH] +--- + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.Get`] method on the Page object. + +[`Resources.Get`]: /methods/page/resources +{{% /note %}} diff --git a/docs/content/en/functions/resources/GetMatch.md b/docs/content/en/functions/resources/GetMatch.md new file mode 100644 index 000000000..fde26c09d --- /dev/null +++ b/docs/content/en/functions/resources/GetMatch.md @@ -0,0 +1,36 @@ +--- +title: resources.GetMatch +description: Returns the first global resource from paths matching the given glob pattern, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetRemote + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: [resources.GetMatch PATTERN] +--- + +```go-html-template +{{ with resources.GetMatch "images/*.jpg" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.GetMatch`] method on the Page object. + +[`Resources.GetMatch`]: /methods/page/resources +{{% /note %}} + +Hugo determines a match using a case-insensitive [glob pattern]. + +{{% include "functions/_common/glob-patterns.md" %}} + +[glob pattern]: https://github.com/gobwas/glob#example diff --git a/docs/content/en/functions/resources/GetRemote.md b/docs/content/en/functions/resources/GetRemote.md new file mode 100644 index 000000000..0e6b91b64 --- /dev/null +++ b/docs/content/en/functions/resources/GetRemote.md @@ -0,0 +1,177 @@ +--- +title: resources.GetRemote +description: Returns a remote resource from the given URL, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/data/GetCSV + - functions/data/GetJSON + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/Match + - methods/page/Resources + returnType: resource.Resource + signatures: ['resources.GetRemote URL [OPTIONS]'] +toc: true +--- + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## Options + +The `resources.GetRemote` function takes an optional map of options. + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "headers" (dict "Authorization" "Bearer abcd") +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +If you need multiple values for the same header key, use a slice: + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "headers" (dict "X-List" (slice "a" "b" "c")) +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +You can also change the request method and set the request body: + +```go-html-template +{{ $url := "https://example.org/api" }} +{{ $opts := dict + "method" "post" + "body" `{"complete": true}` + "headers" (dict "Content-Type" "application/json") +}} +{{ $resource := resources.GetRemote $url $opts }} +``` + +## Remote data + +When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal] the response. + +[`transform.Unmarshal`]: /functions/transform/unmarshal +[unmarshal]: /getting-started/glossary/#unmarshal + +```go-html-template +{{ $data := "" }} +{{ $url := "https://example.org/books.json" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $data = . | transform.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## Error handling + +The [`Err`] method on a resource returned by the `resources.GetRemote` function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. + +[`Err`]: /methods/resource/err + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +To log an error as a warning instead of an error: + +```go-html-template +{{ $url := "https://broken-example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ warnf "%s" . }} + {{ else }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +## HTTP response + +The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response. + +[`Data`]: /methods/resource/data + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ with .Data }} + {{ .ContentLength }} → 42764 + {{ .ContentType }} → image/jpeg + {{ .Status }} → 200 OK + {{ .StatusCode }} → 200 + {{ .TransferEncoding }} → [] + {{ end }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +ContentLength +: (`int`) The content length in bytes. + +ContentType +: (`string`) The content type. + +Status +: (`string`) The HTTP status text. + +StatusCode +: (`int`) The HTTP status code. + +TransferEncoding +: (`string`) The transfer encoding. + +## Caching + +Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details. + +By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any. + +Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. + +```go-html-template +{{ $url := "https://example.org/images/a.jpg" }} +{{ $cacheKey := print $url (now.Format "2006-01-02") }} +{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }} +``` + +[configure file caches]: /getting-started/configuration/#configure-file-caches diff --git a/docs/content/en/functions/resources/Match.md b/docs/content/en/functions/resources/Match.md new file mode 100644 index 000000000..0044351f1 --- /dev/null +++ b/docs/content/en/functions/resources/Match.md @@ -0,0 +1,36 @@ +--- +title: resources.Match +description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/ByType + - functions/resources/Get + - functions/resources/GetMatch + - functions/resources/GetRemote + - methods/page/Resources + returnType: resource.Resources + signatures: [resources.Match PATTERN] +--- + +```go-html-template +{{ range resources.Match "images/*.jpg" }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> +{{ end }} +``` + +{{% note %}} +This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +For page resources, use the [`Resources.Match`] method on the Page object. + +[`Resources.Match`]: /methods/page/resources +{{% /note %}} + +Hugo determines a match using a case-insensitive [glob pattern]. + +{{% include "functions/_common/glob-patterns.md" %}} + +[glob pattern]: https://github.com/gobwas/glob#example diff --git a/docs/content/en/functions/resources/Minify.md b/docs/content/en/functions/resources/Minify.md new file mode 100644 index 000000000..44f5f990b --- /dev/null +++ b/docs/content/en/functions/resources/Minify.md @@ -0,0 +1,23 @@ +--- +title: resources.Minify +description: Minifies the given resource. +categories: [] +keywords: [] +action: + aliases: [minify] + related: + - functions/js/Build + - functions/resources/Babel + - functions/resources/Fingerprint + - functions/resources/PostCSS + - functions/resources/ToCSS + returnType: resource.Resource + signatures: [resources.Minify RESOURCE] +--- + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $style := $css | minify }} +``` + +Any CSS, JS, JSON, HTML, SVG or XML resource can be minified using resources.Minify which takes for argument the resource object. diff --git a/docs/content/en/functions/resources/PostCSS.md b/docs/content/en/functions/resources/PostCSS.md new file mode 100644 index 000000000..a9f9ed3c8 --- /dev/null +++ b/docs/content/en/functions/resources/PostCSS.md @@ -0,0 +1,129 @@ +--- +title: resources.PostCSS +description: Processes the given resource with PostCSS using any PostCSS plugin. +categories: [] +keywords: [] +action: + aliases: [postCSS] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostProcess + - functions/resources/ToCSS + returnType: resource.Resource + signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "css/main.css" | postCSS }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ end }} +``` + +## Setup + +Follow the steps below to transform CSS using any of the available [PostCSS plugins]. + +Step 1 +: Install [Node.js]. + +Step 2 +: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: + +```sh +npm i -D postcss postcss-cli autoprefixer +``` + +Step 3 +: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example: + +```js +module.exports = { + plugins: [ + require('autoprefixer') + ] +}; +``` + +{{% note %}} +{{% include "functions/resources/_common/postcss-windows-warning.md" %}} +{{% /note %}} + +Step 4 +: Place your CSS file within the `assets/css` directory. + +Step 5 +: Process the resource with PostCSS: + +```go-html-template +{{ with resources.Get "css/main.css" | postCSS }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ end }} +``` + +## Options + +The `resources.PostCSS` method takes an optional map of options. + +config +: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory. + +noMap +: (`bool`) Default is `false`. If `true`, disables inline sourcemaps. + +inlineImports +: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. + +skipInlineImportsNotFound +: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. + +```go-html-template +{{ $opts := dict "config" "config-directory" "noMap" true }} +{{ with resources.Get "css/main.css" | postCSS $opts }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ end }} +``` + +## No configuration file + +To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map. + +use +: (`string`) A space-delimited list of PostCSS plugins to use. + +parser +: (`string`) A custom PostCSS parser. + +stringifier +: (`string`) A custom PostCSS stringifier. + +syntax +: (`string`) Custom postcss syntax. + +```go-html-template +{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }} +{{ with resources.Get "css/main.css" | postCSS $opts }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> +{{ end }} +``` + +## Check environment + +The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this: + +```js +const autoprefixer = require('autoprefixer'); +const purgecss = require('@fullhuman/postcss-purgecss'); +module.exports = { + plugins: [ + autoprefixer, + process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null + ] +} +``` + +[node.js]: https://nodejs.org/en/download +[postcss plugins]: https://www.postcss.parts/ +[supported file name]: https://github.com/postcss/postcss-load-config#usage +[transpile to CSS]: /functions/resources/tocss.md diff --git a/docs/content/en/functions/resources/PostProcess.md b/docs/content/en/functions/resources/PostProcess.md new file mode 100644 index 000000000..f765ea9af --- /dev/null +++ b/docs/content/en/functions/resources/PostProcess.md @@ -0,0 +1,160 @@ +--- +title: resources.PostProcess +description: Processes the given resource after the build. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/ToCSS + returnType: postpub.PostPublishedResource + signatures: [resources.PostProcess RESOURCE] +toc: true +--- + +```go-html-template +{{ with resources.Get "css/main.css" }} + {{ if hugo.IsDevelopment }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ end }} + {{ end }} +{{ end }} +``` + +Marking a resource with `resources.PostProcess` postpones transformations until the build has finished. + +Call `resources.PostProcess` when one or more of the steps in the transformation chain depends on the result of the build. + +A prime use case for this is purging unused CSS rules using the [PurgeCSS] plugin for the PostCSS Node.js package. + +## CSS Purging + +{{% note %}} +There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for examples. +{{% /note %}} + +Step 1 +: Install [Node.js]. + +Step 2 +: Install the required Node.js packages in the root of your project: + +```sh +npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss +``` + +Step 3 +: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example: + +```js +const autoprefixer = require('autoprefixer'); +const purgecss = require('@fullhuman/postcss-purgecss')({ + content: ['./hugo_stats.json'], + defaultExtractor: content => { + const els = JSON.parse(content).htmlElements; + return [ + ...(els.tags || []), + ...(els.classes || []), + ...(els.ids || []), + ]; + }, + // https://purgecss.com/safelisting.html + safelist: [] +}); + +module.exports = { + plugins: [ + autoprefixer, + process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null + ] +}; +``` + +{{% note %}} +{{% include "functions/resources/_common/postcss-windows-warning.md" %}} +{{% /note %}} + +Step 4 +: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [config/production]. + +{{< code-toggle file=hugo >}} +[build.buildStats] +enable = true +{{< /code-toggle >}} + +See the [configure build] documentation for details and options. + +Step 5 +: Place your CSS file within the `assets/css` directory. + +Step 6 +: If the current environment is not `development`, process the resource with PostCSS: + +```go-html-template +{{ with resources.Get "css/main.css" }} + {{ if hugo.IsDevelopment }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ end }} + {{ end }} +{{ end }} +``` + +## Environment variables + +Hugo passes these environment variables to PostCSS, which allows you to do something like: + +```js +process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : [] +``` + +PWD +: The absolute path to the project working directory. + +HUGO_ENVIRONMENT +: The current Hugo environment, set with the `--environment` command line flag. +Default is `production` for `hugo` and `development` for `hugo server`. + +HUGO_PUBLISHDIR +: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags: + +```sh +hugo server --renderToDisk +hugo server --renderStaticToDisk +``` + +Also, Hugo will add environment variables for all files mounted below `assets/_jsconfig`. A default mount will be set up with files in the project root matching this regexp: `(babel|postcss|tailwind)\.config\.js`. + +These will get environment variables named on the form `HUGO_FILE_:filename:` where `:filename:` is all upper case with periods replaced with underscore. This allows you to do something like: + +```js +let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js'; +``` + +## Limitations + +Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not "development". + +The `resources.PostProcess` function only works within templates that produce HTML files. + +You cannot manipulate the values returned from the resource’s methods. For example, the `strings.ToUpper` function in this example will not work as expected: + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }} +{{ $css.RelPermalink | strings.ToUpper }} +``` + +[node.js]: https://nodejs.org/en/download +[supported file name]: https://github.com/postcss/postcss-load-config#usage +[config/production]: /getting-started/configuration/#configuration-directory +[configure build]: /getting-started/configuration/#configure-build +[purgecss]: https://github.com/FullHuman/purgecss#readme diff --git a/docs/content/en/functions/resources/ToCSS.md b/docs/content/en/functions/resources/ToCSS.md new file mode 100644 index 000000000..872bf996b --- /dev/null +++ b/docs/content/en/functions/resources/ToCSS.md @@ -0,0 +1,224 @@ +--- +title: resources.ToCSS +description: Transpiles Sass to CSS. +categories: [] +keywords: [] +action: + aliases: [toCSS] + related: + - functions/resources/Fingerprint + - functions/resources/Minify + - functions/resources/PostCSS + - functions/resources/PostProcess + returnType: resource.Resource + signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] +toc: true +--- + +```go-html-template +{{ with resources.Get "sass/main.scss" }} + {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} + {{ with . | toCSS $opts }} + {{ if hugo.IsDevelopment }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | minify | fingerprint }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ end }} + {{ end }} + {{ end }} +{{ end }} +``` + +Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language. + +Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both. + +[scss]: https://sass-lang.com/documentation/syntax#scss +[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax + +## Options + +transpiler +: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below. + +targetPath +: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`. + +vars +: (`map`) A map of key/value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/). + +```scss +// LibSass +@import "hugo:vars"; + +// Dart Sass +@use "hugo:vars" as v; +``` + +outputStyle +: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`. + +precision +: (`int`) Precision of floating point math. Not applicable to Dart Sass. + +enableSourceMap +: (`bool`) If `true`, generates a source map. + +sourceMapIncludeSources +: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass. + +includePaths +: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements. + +```go-html-template +{{ $opts := dict + "transpiler" "dartsass" + "targetPath" "css/style.css" + "vars" site.Params.styles + "enableSourceMap" (not hugo.IsProduction) + "includePaths" (slice "node_modules/bootstrap/scss") +}} +{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> +{{ end }} +``` + +## Dart Sass + +The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass]. + +Use the latest features of the Sass language by installing Dart Sass in your development and production environments. + +### Installation overview + +Dart Sass is compatible with Hugo v0.114.0 and later. + +If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass. + +If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass. + +[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. + +### Installing in a development environment + +When you install Dart Sass somewhere in your PATH, Hugo will find it. + +OS|Package manager|Site|Installation +:--|:--|:--|:-- +Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass` +Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass` +macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass` +Windows|Chocolatey|[chocolatey.org]|`choco install sass` +Windows|Scoop|[scoop.sh]|`scoop install sass` + +You may also install [prebuilt binaries] for Linux, macOS, and Windows. + +Run `hugo env` to list the active transpilers. + +### Installing in a production environment + +For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. + +[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository. + +#### GitHub Pages + +To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file: + +```yaml +- name: Install Dart Sass + run: sudo snap install dart-sass +``` + +If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started. + +#### GitLab Pages + +To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this: + +```yaml +variables: + HUGO_VERSION: 0.115.1 + DART_SASS_VERSION: 1.63.6 + GIT_DEPTH: 0 + GIT_STRATEGY: clone + GIT_SUBMODULE_STRATEGY: recursive + TZ: America/Los_Angeles +image: + name: golang:1.20-buster +pages: + script: + # Install Dart Sass + - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz + - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz + - cp -r dart-sass/* /usr/local/bin + - rm -rf dart-sass* + # Install Hugo + - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb + - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb + - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb + # Build + - hugo --gc --minify + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + +#### Netlify + +To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this: + +```toml +[build.environment] +HUGO_VERSION = "0.115.1" +DART_SASS_VERSION = "1.63.6" +TZ = "America/Los_Angeles" + +[build] +publish = "public" +command = """\ + curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \ + export PATH=/opt/build/repo/dart-sass:$PATH && \ + hugo --gc --minify \ + """ +``` + +### Example + +To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: + +```go-html-template +{{ with resources.Get "sass/main.scss" }} + {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} + {{ with . | toCSS $opts }} + {{ if hugo.IsDevelopment }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} + {{ with . | minify | fingerprint }} + <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> + {{ end }} + {{ end }} + {{ end }} +{{ end }} +``` + +### Miscellaneous + +If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model. + +[brew.sh]: https://brew.sh/ +[chocolatey.org]: https://community.chocolatey.org/packages/sass +[ci/cd]: https://en.wikipedia.org/wiki/CI/CD +[dart sass]: https://sass-lang.com/dart-sass +[libsass]: https://sass-lang.com/libsass +[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest +[scoop.sh]: https://scoop.sh/#/apps?q=sass +[site configuration]: /getting-started/configuration/#configure-build +[snap package]: /installation/linux/#snap +[snapcraft.io]: https://snapcraft.io/dart-sass +[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml diff --git a/docs/content/en/functions/resources/_common/_index.md b/docs/content/en/functions/resources/_common/_index.md new file mode 100644 index 000000000..b57b688b3 --- /dev/null +++ b/docs/content/en/functions/resources/_common/_index.md @@ -0,0 +1,12 @@ +--- +_build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/resources/_common/postcss-windows-warning.md b/docs/content/en/functions/resources/_common/postcss-windows-warning.md new file mode 100644 index 000000000..1b72e74db --- /dev/null +++ b/docs/content/en/functions/resources/_common/postcss-windows-warning.md @@ -0,0 +1,8 @@ +--- +# Do not remove front matter. +--- + +If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. + +[this example]: https://github.com/postcss/postcss-load-config#packagejson +[#7333]: https://github.com/gohugoio/hugo/issues/7333 diff --git a/docs/content/en/functions/resources/_index.md b/docs/content/en/functions/resources/_index.md new file mode 100644 index 000000000..364b9448d --- /dev/null +++ b/docs/content/en/functions/resources/_index.md @@ -0,0 +1,12 @@ +--- +title: Resource functions +linkTitle: resources +description: Template functions to work with resources. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with resources. diff --git a/docs/content/en/functions/safe/CSS.md b/docs/content/en/functions/safe/CSS.md index d5dcdfb66..08307fb15 100644 --- a/docs/content/en/functions/safe/CSS.md +++ b/docs/content/en/functions/safe/CSS.md @@ -1,23 +1,18 @@ --- title: safe.CSS -linkTitle: safeCSS -description: Declares the provided string as a known "safe" CSS string. -categories: [functions] +description: Declares the given string as safe CSS string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeCSS] + related: + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.CSS signatures: [safe.CSS INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safecss] --- @@ -30,9 +25,9 @@ In this context, *safe* means CSS content that matches any of the following: Example: Given `style = "color: red;"` defined in the front matter of your `.md` file: -* <span class="good">`<p style="{{ .Params.style | safeCSS }}">…</p>` → `<p style="color: red;">…</p>`</span> -* <span class="bad">`<p style="{{ .Params.style }}">…</p>` → `<p style="ZgotmplZ">…</p>`</span> +* `<p style="{{ .Params.style | safeCSS }}">…</p>` → `<p style="color: red;">…</p>` +* `<p style="{{ .Params.style }}">…</p>` → `<p style="ZgotmplZ">…</p>` {{% note %}} -"ZgotmplZ" is a special value that indicates that unsafe content reached a CSS or URL context. +`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context. {{% /note %}} diff --git a/docs/content/en/functions/safe/HTML.md b/docs/content/en/functions/safe/HTML.md index ea3afe8f3..ecc4f1346 100644 --- a/docs/content/en/functions/safe/HTML.md +++ b/docs/content/en/functions/safe/HTML.md @@ -1,23 +1,18 @@ --- title: safe.HTML -linkTitle: safeHTML -description: Declares a provided string as a "safe" HTML document to avoid escaping by Go templates. -categories: [functions] +description: Declares the given string as a safeHTML string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeHTML] + related: + - functions/safe/CSS + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.HTML signatures: [safe.HTML INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safehtml] --- @@ -25,7 +20,7 @@ It should not be used for HTML from a third-party, or HTML with unclosed tags or Given a site-wide [`hugo.toml`][config] with the following `copyright` value: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} copyright = "© 2015 Jane Doe. <a href=\"https://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>." {{< /code-toggle >}} diff --git a/docs/content/en/functions/safe/HTMLAttr.md b/docs/content/en/functions/safe/HTMLAttr.md index 7d1b06c47..6e1fd2af7 100644 --- a/docs/content/en/functions/safe/HTMLAttr.md +++ b/docs/content/en/functions/safe/HTMLAttr.md @@ -1,29 +1,24 @@ --- title: safe.HTMLAttr -linkTitle: safeHTMLAttr -description: Declares the provided string as a safe HTML attribute. -categories: [functions] +description: Declares the given key/value pair as a safe HTML attribute. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeHTMLAttr] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/JS + - functions/safe/JSStr + - functions/safe/URL returnType: template.HTMLAttr signatures: [safe.HTMLAttr INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safehtmlattr] --- Given a site configuration that contains this menu entry: -{{< code-toggle file="hugo" >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = "IRC" url = "irc://irc.freenode.net/#golang" @@ -35,7 +30,7 @@ Attempting to use the `url` value directly in an attribute: {{ range site.Menus.main }} <a href="{{ .URL }}">{{ .Name }}</a> {{ end }} -``` +``` Will produce: diff --git a/docs/content/en/functions/safe/JS.md b/docs/content/en/functions/safe/JS.md index e679b5f85..65279b89b 100644 --- a/docs/content/en/functions/safe/JS.md +++ b/docs/content/en/functions/safe/JS.md @@ -1,23 +1,18 @@ --- title: safe.JS -linkTitle: safeJS -description: Declares the provided string as a known safe JavaScript string. -categories: [functions] +description: Declares the given string as a safe JavaScript expression. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeJS] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JSStr + - functions/safe/URL returnType: template.JS signatures: [safe.JS INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safejs] --- @@ -27,5 +22,5 @@ Template authors are responsible for ensuring that typed expressions do not brea Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file: -* <span class="good">`<script>var form_{{ .Params.hash | safeJS }};…</script>` → `<script>var form_619c16f;…</script>`</span> -* <span class="bad">`<script>var form_{{ .Params.hash }};…</script>` → `<script>var form_"619c16f";…</script>`</span> +* `<script>var form_{{ .Params.hash | safeJS }};…</script>` → `<script>var form_619c16f;…</script>` +* `<script>var form_{{ .Params.hash }};…</script>` → `<script>var form_"619c16f";…</script>` diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md index 790de3a73..36d2b36fa 100644 --- a/docs/content/en/functions/safe/JSStr.md +++ b/docs/content/en/functions/safe/JSStr.md @@ -1,23 +1,18 @@ --- title: safe.JSStr -linkTitle: safeJSStr -description: Declares the provided string as a known safe JavaScript string. -categories: [functions] +description: Declares the given string as a safe JavaScript string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeJSStr] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/URL returnType: template.JSStr signatures: [safe.JSStr INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safejsstr] --- @@ -34,7 +29,6 @@ Without declaring a variable to be a safe JavaScript string: Rendered: - ```html <script> const a = "Title: " + "Lilo \u0026 Stitch"; diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md index edc62ff9d..2ae67bd7f 100644 --- a/docs/content/en/functions/safe/URL.md +++ b/docs/content/en/functions/safe/URL.md @@ -1,23 +1,18 @@ --- title: safe.URL -linkTitle: safeURL -description: Declares the provided string as a safe URL or URL substring. -categories: [functions] +description: Declares the given string as a safe URL or URL substring. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [safeURL] + related: + - functions/safe/CSS + - functions/safe/HTML + - functions/safe/HTMLAttr + - functions/safe/JS + - functions/safe/JSStr returnType: template.URL signatures: [safe.URL INPUT] -relatedFunctions: - - safe.CSS - - safe.HTML - - safe.HTMLAttr - - safe.JS - - safe.JSStr - - safe.URL aliases: [/functions/safeurl] --- @@ -27,7 +22,7 @@ Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are cons The following examples use a [site `hugo.toml`][configuration] with the following [menu entry][menus]: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [[menu.main]] name = "IRC: #golang at freenode" url = "irc://irc.freenode.net/#golang" @@ -35,7 +30,7 @@ url = "irc://irc.freenode.net/#golang" The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example: -{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy=false >}} +{{< code file=layouts/partials/bad-url-sidebar-menu.html >}} <!-- This unordered list may be part of a sidebar menu --> <ul> {{ range .Site.Menus.main }} @@ -55,7 +50,7 @@ This partial would produce the following HTML output: The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable: -{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy=false >}} +{{< code file=layouts/partials/correct-url-sidebar-menu.html >}} <!-- This unordered list may be part of a sidebar menu --> <ul> <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li> diff --git a/docs/content/en/functions/safe/_index.md b/docs/content/en/functions/safe/_index.md new file mode 100644 index 000000000..f80a2cff4 --- /dev/null +++ b/docs/content/en/functions/safe/_index.md @@ -0,0 +1,14 @@ +--- +title: Safe functions +linkTitle: safe +description: Template functions to declare a value as safe in the context of Go's html/template package. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to declare a value as safe in the context of Go's [html/template] package. + +[html/template]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/strings/Chomp.md b/docs/content/en/functions/strings/Chomp.md index 22e2b546b..349f1e9b7 100644 --- a/docs/content/en/functions/strings/Chomp.md +++ b/docs/content/en/functions/strings/Chomp.md @@ -1,31 +1,27 @@ --- -title: chomp -linkTitle: chomp -description: Removes any trailing newline characters. -categories: [functions] +title: strings.Chomp +description: Returns the given string, removing all trailing newline characters and carriage returns. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [chomp] + related: + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: any signatures: [strings.Chomp STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/chomp] --- -If the argument is of type template.HTML, returns template.HTML, else returns a string. - - -Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/transform/markdownify)). +If the argument is of type `template.HTML`, returns `template.HTML`, else returns a `string`. ```go-html-template -{{ chomp "<p>Blockhead</p>\n" }} → "<p>Blockhead</p>" +{{ chomp | "foo\n" }} → foo +{{ chomp | "foo\n\n" }} → foo + +{{ chomp | "foo\r\n" }} → foo +{{ chomp | "foo\r\n\r\n" }} → foo ``` diff --git a/docs/content/en/functions/strings/Contains.md b/docs/content/en/functions/strings/Contains.md index 66a90aeea..0344b2981 100644 --- a/docs/content/en/functions/strings/Contains.md +++ b/docs/content/en/functions/strings/Contains.md @@ -1,28 +1,26 @@ --- title: strings.Contains -description: Reports whether the string contains a substring. -categories: [functions] +description: Reports whether the given string contains the given substring. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.Contains STRING SUBSTRING] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/strings.contains] --- ```go-html-template {{ strings.Contains "Hugo" "go" }} → true ``` -The check is case sensitive: + +The check is case sensitive: ```go-html-template {{ strings.Contains "Hugo" "Go" }} → false diff --git a/docs/content/en/functions/strings/ContainsAny.md b/docs/content/en/functions/strings/ContainsAny.md index 4f324358a..f331d09f7 100644 --- a/docs/content/en/functions/strings/ContainsAny.md +++ b/docs/content/en/functions/strings/ContainsAny.md @@ -1,21 +1,18 @@ --- title: strings.ContainsAny -description: Reports whether a string contains any character from a given string. -categories: [functions] +description: Reports whether the given string contains any character within the given set. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool - signatures: [strings.ContainsAny STRING CHARACTERS] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix + signatures: [strings.ContainsAny STRING SET] aliases: [/functions/strings.containsany] --- @@ -23,7 +20,7 @@ aliases: [/functions/strings.containsany] {{ strings.ContainsAny "Hugo" "gm" }} → true ``` -The check is case sensitive: +The check is case sensitive: ```go-html-template {{ strings.ContainsAny "Hugo" "Gm" }} → false diff --git a/docs/content/en/functions/strings/ContainsNonSpace.md b/docs/content/en/functions/strings/ContainsNonSpace.md index d2e6114b3..188aa14ba 100644 --- a/docs/content/en/functions/strings/ContainsNonSpace.md +++ b/docs/content/en/functions/strings/ContainsNonSpace.md @@ -1,27 +1,26 @@ --- title: strings.ContainsNonSpace -description: Reports whether a string contains any non-space characters as defined by Unicode’s White Space property. -categories: [functions] +description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.ContainsNonSpace STRING] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/strings.containsnonspace] --- +{{< new-in 0.111.0 >}} + ```go-html-template -{{ strings.ContainsNonSpace "\n" }} → false -{{ strings.ContainsNonSpace " " }} → false +{{ strings.ContainsNonSpace "\n" }} → false +{{ strings.ContainsNonSpace " " }} → false {{ strings.ContainsNonSpace "\n abc" }} → true ``` diff --git a/docs/content/en/functions/strings/Count.md b/docs/content/en/functions/strings/Count.md index 25ea58967..43b5baeff 100644 --- a/docs/content/en/functions/strings/Count.md +++ b/docs/content/en/functions/strings/Count.md @@ -1,21 +1,17 @@ --- title: strings.Count -description: Returns the number of non-overlapping instances of a substring within a string. -categories: [functions] +description: Returns the number of non-overlapping instances of the given substring within the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/len + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int signatures: [strings.Count SUBSTR STRING] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/strings.count] --- diff --git a/docs/content/en/functions/strings/CountRunes.md b/docs/content/en/functions/strings/CountRunes.md index 4a17d04ab..10788e174 100644 --- a/docs/content/en/functions/strings/CountRunes.md +++ b/docs/content/en/functions/strings/CountRunes.md @@ -1,22 +1,17 @@ --- title: strings.CountRunes -linkTitle: countrunes -description: Returns the number of runes in a string excluding whitespace. -categories: [functions] +description: Returns the number of runes in the given string excluding whitespace. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [countrunes] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int signatures: [strings.CountRunes INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/countrunes] --- diff --git a/docs/content/en/functions/strings/CountWords.md b/docs/content/en/functions/strings/CountWords.md index e6915e6cd..3e4ec0465 100644 --- a/docs/content/en/functions/strings/CountWords.md +++ b/docs/content/en/functions/strings/CountWords.md @@ -1,31 +1,20 @@ --- title: strings.CountWords -linkTitle: countwords -description: Counts the number of words in a string. -categories: [functions] +description: Returns the number of words in the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [countwords] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/RuneCount returnType: int signatures: [strings.CountWords INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/countwords] --- -The template function works similar to the [.WordCount page variable][pagevars]. - ```go-html-template -{{ "Hugo is a static site generator." | countwords }} -<!-- outputs a content length of 6 words. --> +{{ "Hugo is a static site generator." | countwords }} → 6 ``` - - -[pagevars]: /variables/page/ diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md index 5a0410fdb..029cb323e 100644 --- a/docs/content/en/functions/strings/FindRESubmatch.md +++ b/docs/content/en/functions/strings/FindRESubmatch.md @@ -1,27 +1,22 @@ --- title: strings.FindRESubmatch -linkTitle: findRESubmatch description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [findRESubmatch] + related: + - functions/strings/FindRE + - functions/strings/Replace + - functions/strings/ReplaceRE returnType: '[]string' signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/findresubmatch] --- 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. -{{% readfile file="/functions/_common/regular-expressions.md" %}} +{{% include "functions/_common/regular-expressions.md" %}} ## Demonstrative examples diff --git a/docs/content/en/functions/strings/FindRe.md b/docs/content/en/functions/strings/FindRe.md index 4a7811f3d..d26bae4a3 100644 --- a/docs/content/en/functions/strings/FindRe.md +++ b/docs/content/en/functions/strings/FindRe.md @@ -1,26 +1,21 @@ --- title: strings.FindRE -linkTitle: findRE description: Returns a slice of strings that match the regular expression. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [findRE] + related: + - functions/strings/FindRESubmatch + - functions/strings/Replace + - functions/strings/ReplaceRE returnType: string signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/findre] --- By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. -{{% readfile file="/functions/_common/regular-expressions.md" %}} +{{% include "functions/_common/regular-expressions.md" %}} This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: diff --git a/docs/content/en/functions/strings/FirstUpper.md b/docs/content/en/functions/strings/FirstUpper.md index 320f01eda..8826b4f18 100644 --- a/docs/content/en/functions/strings/FirstUpper.md +++ b/docs/content/en/functions/strings/FirstUpper.md @@ -1,23 +1,19 @@ --- title: strings.FirstUpper -description: Capitalizes the first character of a given string. -categories: [functions] +description: Returns the given string, capitalizing the first character. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Title + - functions/strings/ToLower + - functions/strings/ToUpper returnType: string signatures: [strings.FirstUpper STRING] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/strings.firstupper] --- ```go-html-template -{{ strings.FirstUpper "foo" }} → "Foo" +{{ strings.FirstUpper "foo" }} → Foo ``` diff --git a/docs/content/en/functions/strings/HasPrefix.md b/docs/content/en/functions/strings/HasPrefix.md index 88a79a935..455de0586 100644 --- a/docs/content/en/functions/strings/HasPrefix.md +++ b/docs/content/en/functions/strings/HasPrefix.md @@ -1,21 +1,18 @@ --- title: strings.HasPrefix -description: Reports whether a string begins with prefix. -categories: [functions] +description: Reports whether the given string begins with the given prefix. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hasPrefix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasSuffix + - functions/collections/In returnType: bool signatures: [strings.HasPrefix STRING PREFIX] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/hasprefix,/functions/strings.hasprefix] --- diff --git a/docs/content/en/functions/strings/HasSuffix.md b/docs/content/en/functions/strings/HasSuffix.md index d11f3e8cf..e7f253ce9 100644 --- a/docs/content/en/functions/strings/HasSuffix.md +++ b/docs/content/en/functions/strings/HasSuffix.md @@ -1,21 +1,18 @@ --- title: strings.HasSuffix -description: Reports whether a string ends with suffix. -categories: [functions] +description: Reports whether the given string begins with the given suffix. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [hasSuffix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/collections/In returnType: bool signatures: [strings.HasSuffix STRING SUFFIX] -relatedFunctions: - - strings.Contains - - strings.ContainsAny - - strings.ContainsNonSpace - - strings.HasPrefix - - strings.HasSuffix aliases: [/functions/hassuffix,/functions/strings/hassuffix] --- diff --git a/docs/content/en/functions/strings/Repeat.md b/docs/content/en/functions/strings/Repeat.md index 718f24984..530b0d14b 100644 --- a/docs/content/en/functions/strings/Repeat.md +++ b/docs/content/en/functions/strings/Repeat.md @@ -1,20 +1,16 @@ --- title: strings.Repeat description: Returns a new string consisting of zero or more copies of another string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: string signatures: [strings.Repeat COUNT INPUT] -relatedFunctions: [] aliases: [/functions/strings.repeat] --- ```go-html-template -{{ strings.Repeat 3 "yo" }} → "yoyoyo" -{{ "yo" | strings.Repeat 3 }} → "yoyoyo" +{{ strings.Repeat 3 "yo" }} → yoyoyo ``` diff --git a/docs/content/en/functions/strings/Replace.md b/docs/content/en/functions/strings/Replace.md index 8d5e54859..9add6e12b 100644 --- a/docs/content/en/functions/strings/Replace.md +++ b/docs/content/en/functions/strings/Replace.md @@ -1,30 +1,26 @@ --- title: strings.Replace -linkTitle: replace -description: Replaces all occurrences of the search string with the replacement string. -categories: [functions] +description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [replace] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/ReplaceRE returnType: string signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/replace] --- -Replace returns a copy of `INPUT` with all occurrences of `OLD` replaced with `NEW`. -The number of replacements can be limited with an optional `LIMIT` argument. - +```go-html-template +{{ $s := "Batman and Robin" }} +{{ replace $s "Robin" "Catwoman" }} → Batman and Catwoman ``` -{{ replace "Batman and Robin" "Robin" "Catwoman" }} -→ "Batman and Catwoman" -{{ replace "aabbaabb" "a" "z" 2 }} → "zzbbaabb" +Limit the number of replacements using the `LIMIT` argument: + +```go-html-template +{{ replace "aabbaabb" "a" "z" 2 }} → zzbbaabb ``` diff --git a/docs/content/en/functions/strings/ReplaceRE.md b/docs/content/en/functions/strings/ReplaceRE.md index 247595877..1c32c34fb 100644 --- a/docs/content/en/functions/strings/ReplaceRE.md +++ b/docs/content/en/functions/strings/ReplaceRE.md @@ -1,42 +1,34 @@ --- title: strings.ReplaceRE -linkTitle: replaceRE -description: Returns a string, replacing all occurrences of a regular expression with a replacement pattern. -categories: [functions] +description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [replaceRE] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/Replace returnType: string signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] -relatedFunctions: - - strings.FindRE - - strings.FindRESubmatch - - strings.Replace - - strings.ReplaceRE aliases: [/functions/replacere] --- -By default, `replaceRE` replaces all matches. You can limit the number of matches with an optional LIMIT argument. -{{% readfile file="/functions/_common/regular-expressions.md" %}} - -This example replaces two or more consecutive hyphens with a single hyphen: +{{% include "functions/_common/regular-expressions.md" %}} ```go-html-template {{ $s := "a-b--c---d" }} {{ replaceRE `(-{2,})` "-" $s }} → a-b-c-d ``` -To limit the number of replacements to one: +Limit the number of replacements using the LIMIT argument: ```go-html-template {{ $s := "a-b--c---d" }} {{ replaceRE `(-{2,})` "-" $s 1 }} → a-b-c---d ``` -You can use `$1`, `$2`, etc. within the replacement string to insert the groups captured within the regular expression: +Use `$1`, `$2`, etc. within the replacement string to insert the content of each capturing group within the regular expression: ```go-html-template {{ $s := "http://gohugo.io/docs" }} diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md index a4d5a8dbe..46fedf01f 100644 --- a/docs/content/en/functions/strings/RuneCount.md +++ b/docs/content/en/functions/strings/RuneCount.md @@ -1,21 +1,17 @@ --- title: strings.RuneCount -description: Returns the number of runes in a string. -categories: [functions] +description: Returns the number of runes in the given string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords returnType: int signatures: [strings.RuneCount INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount aliases: [/functions/strings.runecount] --- diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md index 8d26d76e4..2f33f8f65 100644 --- a/docs/content/en/functions/strings/SliceString.md +++ b/docs/content/en/functions/strings/SliceString.md @@ -1,24 +1,20 @@ --- title: strings.SliceString -linkTitle: slicestr description: Creates a slice of a half-open range, including start and end indices. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [slicestr] + related: [] returnType: string signatures: ['strings.SliceString STRING START [END]'] -relatedFunctions: [] aliases: [/functions/slicestr] --- -For example, 1 and 4 creates a slice including elements 1 through 3. +For example, 1 and 4 creates a slice including elements 1 through 3. The `end` index can be omitted; it defaults to the string's length. ```go-html-template -{{ slicestr "BatMan" 3 }}` → "Man" -{{ slicestr "BatMan" 0 3 }}` → "Bat" +{{ slicestr "BatMan" 3 }}` → Man +{{ slicestr "BatMan" 0 3 }}` → Bat ``` diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md index 7d15704b2..a9973ea63 100644 --- a/docs/content/en/functions/strings/Split.md +++ b/docs/content/en/functions/strings/Split.md @@ -1,19 +1,14 @@ --- title: strings.Split -linkTitle: split -description: Returns a slice of strings by splitting STRING by DELIM. -categories: [functions] +description: Returns a slice of strings by splitting the given string by a delimiter. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [split] + related: + - functions/collections/Delimit returnType: string signatures: [strings.Split STRING DELIM] -relatedFunctions: - - collections.Delimit - - strings.Split aliases: [/functions/split] --- @@ -24,7 +19,8 @@ Examples: {{ split "abc" "" }} → ["a", "b", "c"] ``` - {{% note %}} -`split` essentially does the opposite of [delimit](/functions/collections/delimit). While `split` creates a slice from a string, `delimit` creates a string from a slice. +The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. + +[`collections.Delimit`]: /functions/collections/delimit {{% /note %}} diff --git a/docs/content/en/functions/strings/Substr.md b/docs/content/en/functions/strings/Substr.md index 9dafa0737..6c1852f58 100644 --- a/docs/content/en/functions/strings/Substr.md +++ b/docs/content/en/functions/strings/Substr.md @@ -1,17 +1,13 @@ --- title: strings.Substr -linkTitle: substr description: Extracts parts of a string from a specified character's position and returns the specified number of characters. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [substr] + related: [] returnType: string signatures: ['strings.Substr STRING START [LENGTH]'] -relatedFunctions: [] aliases: [/functions/substr] --- @@ -22,21 +18,21 @@ To extract characters from the end of the string, use a negative start number. If `length` is given and is negative, that number of characters will be omitted from the end of string. ```go-html-template -{{ substr "abcdef" 0 }} → "abcdef" -{{ substr "abcdef" 1 }} → "bcdef" +{{ substr "abcdef" 0 }} → abcdef +{{ substr "abcdef" 1 }} → bcdef -{{ substr "abcdef" 0 1 }} → "a" -{{ substr "abcdef" 1 1 }} → "b" +{{ substr "abcdef" 0 1 }} → a +{{ substr "abcdef" 1 1 }} → b -{{ substr "abcdef" 0 -1 }} → "abcde" -{{ substr "abcdef" 1 -1 }} → "bcde" +{{ substr "abcdef" 0 -1 }} → abcde +{{ substr "abcdef" 1 -1 }} → bcde -{{ substr "abcdef" -1 }} → "f" -{{ substr "abcdef" -2 }} → "ef" +{{ substr "abcdef" -1 }} → f +{{ substr "abcdef" -2 }} → ef -{{ substr "abcdef" -1 1 }} → "f" -{{ substr "abcdef" -2 1 }} → "e" +{{ substr "abcdef" -1 1 }} → f +{{ substr "abcdef" -2 1 }} → e -{{ substr "abcdef" -3 -1 }} → "de" -{{ substr "abcdef" -3 -2 }} → "d" +{{ substr "abcdef" -3 -1 }} → de +{{ substr "abcdef" -3 -2 }} → d ``` diff --git a/docs/content/en/functions/strings/Title.md b/docs/content/en/functions/strings/Title.md index 1e20d1f59..b7f1f9e5c 100644 --- a/docs/content/en/functions/strings/Title.md +++ b/docs/content/en/functions/strings/Title.md @@ -1,30 +1,32 @@ --- title: strings.Title -linkTitle: title -description: Converts the provided string to title case. -categories: [functions] +description: Returns the given string, converting it to title case. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [title] + related: + - functions/strings/FirstUpper + - functions/strings/ToLower + - functions/strings/ToUpper returnType: string signatures: [strings.Title STRING] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/title] --- ```go-html-template -{{ title "table of contents (TOC)" }} → "Table of Contents (TOC)" +{{ title "table of contents (TOC)" }} → Table of Contents (TOC) ``` -By default, Hugo adheres to the capitalization rules in the [Associated Press (AP) Stylebook]. Change your [site configuration] if you would prefer to follow the [Chicago Manual of Style], or to use Go's convention of capitalizing every word. +By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [site configuration] if you would prefer to: -[Associated Press (AP) Stylebook]: https://www.apstylebook.com/ +- Follow the capitalization rules published in the [Chicago Manual of Style] +- Capitalize the first letter of every word +- Capitalize the first letter of the first word +- Disable the effects of the `title` function + +The last option is useful if your theme uses the `title` function, and you would prefer to manually capitalize strings as needed. + +[Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html [site configuration]: /getting-started/configuration/#configure-title-case diff --git a/docs/content/en/functions/strings/ToLower.md b/docs/content/en/functions/strings/ToLower.md index cb76462ea..3da047ae4 100644 --- a/docs/content/en/functions/strings/ToLower.md +++ b/docs/content/en/functions/strings/ToLower.md @@ -1,28 +1,19 @@ --- title: strings.ToLower -linkTitle: lower -description: Converts all characters in the provided string to lowercase. -categories: [functions] +description: Returns the given string, converting all characters to lowercase. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [lower] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToUpper returnType: string signatures: [strings.ToLower INPUT] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/lower] --- - -Note that `lower` can be applied in your templates in more than one way: - ```go-html-template -{{ lower "BatMan" }} → "batman" -{{ "BatMan" | lower }} → "batman" +{{ lower "BatMan" }} → batman ``` diff --git a/docs/content/en/functions/strings/ToUpper.md b/docs/content/en/functions/strings/ToUpper.md index d46491637..617e1e68a 100644 --- a/docs/content/en/functions/strings/ToUpper.md +++ b/docs/content/en/functions/strings/ToUpper.md @@ -1,27 +1,19 @@ --- title: strings.ToUpper -linkTitle: upper -description: Converts all characters in a string to uppercase -categories: [functions] +description: Returns the given string, converting all characters to uppercase. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [upper] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToLower returnType: string signatures: [strings.ToUpper INPUT] -relatedFunctions: - - strings.FirstUpper - - strings.Title - - strings.ToLower - - strings.ToUpper aliases: [/functions/upper] --- -Note that `upper` can be applied in your templates in more than one way: - ```go-html-template -{{ upper "BatMan" }} → "BATMAN" -{{ "BatMan" | upper }} → "BATMAN" +{{ upper "BatMan" }} → BATMAN ``` diff --git a/docs/content/en/functions/strings/Trim.md b/docs/content/en/functions/strings/Trim.md index 9eae9ee45..6dfac024b 100644 --- a/docs/content/en/functions/strings/Trim.md +++ b/docs/content/en/functions/strings/Trim.md @@ -1,45 +1,59 @@ --- title: strings.Trim -linkTitle: trim -description: Returns a slice of a passed string with all leading and trailing characters from cutset removed. -categories: [functions] +description: Returns the given string, removing leading and trailing characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: - aliases: [title] +action: + aliases: [trim] + related: + - functions/strings/Chomp + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.Trim INPUT CUTSET] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/trim] --- ```go-html-template -{{ trim "++Batman--" "+-" }} → "Batman" +{{ trim "++foo--" "+-" }} → foo ``` -`trim` *requires* the second argument, which tells the function specifically what to remove from the first argument. There is no default value for the second argument, so **the following usage will not work**: +To remove leading and trailing newline characters and carriage returns: ```go-html-template -{{ trim .Inner }} +{{ trim "\nfoo\n" "\n\r" }} → foo +{{ trim "\n\nfoo\n\n" "\n\r" }} → foo + +{{ trim "\r\nfoo\r\n" "\n\r" }} → foo +{{ trim "\r\n\r\nfoo\r\n\r\n" "\n\r" }} → foo ``` -Instead, the following example tells `trim` to remove extra new lines from the content contained in the [shortcode `.Inner` variable][shortcodevars]: +The `strings.Trim` function is commonly used in shortcodes to remove leading and trailing newlines characters and carriage returns from the content within the opening and closing shortcode tags. -```go-html-template -{{ trim .Inner "\n" }} +For example, with this markdown: + +```text +{{</* my-shortcode */>}} +Able was I ere I saw Elba. +{{</* /my-shortcode */>}} +``` + +The value of `.Inner` in the shortcode template is: + +```text +\nAble was I ere I saw Elba.\n ``` -{{% note %}} -Go templates also provide a simple [method for trimming whitespace](/templates/introduction/#whitespace) from either side of a Go tag by including a hyphen (`-`). -{{% /note %}} +If authored on a Windows system the value of `.Inner` might, depending on the editor configuration, be: + +```text +\r\nAble was I ere I saw Elba.\r\n +``` +This construct is common in shortcode templates: -[shortcodevars]: /variables/shortcodes/ +```go-html-template +{{ trim .Inner "\n\r" }} +``` diff --git a/docs/content/en/functions/strings/TrimLeft.md b/docs/content/en/functions/strings/TrimLeft.md index 3924e492f..07cdf0064 100644 --- a/docs/content/en/functions/strings/TrimLeft.md +++ b/docs/content/en/functions/strings/TrimLeft.md @@ -1,33 +1,28 @@ --- title: strings.TrimLeft -description: Returns a slice of a given string with all leading characters contained in the cutset removed. -categories: [functions] +description: Returns the given string, removing leading characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimLeft CUTSET STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimleft] --- -Given the string `"abba"`, leading `"a"`'s can be removed a follows: - ```go-html-template -{{ strings.TrimLeft "a" "abba" }} → "bba" +{{ strings.TrimLeft "a" "abba" }} → bba ``` -Numbers can be handled as well: +The `strings.TrimLeft` function converts the arguments to strings if possible: ```go-html-template -{{ strings.TrimLeft 12 1221341221 }} → "341221" +{{ strings.TrimLeft 21 12345 }} → 345 (string) +{{ strings.TrimLeft "rt" true }} → ue ``` diff --git a/docs/content/en/functions/strings/TrimPrefix.md b/docs/content/en/functions/strings/TrimPrefix.md index 37657732d..917cf06f5 100644 --- a/docs/content/en/functions/strings/TrimPrefix.md +++ b/docs/content/en/functions/strings/TrimPrefix.md @@ -1,29 +1,23 @@ --- title: strings.TrimPrefix -description: Returns a given string s without the provided leading prefix string. If s doesn't start with prefix, s is returned unchanged. -categories: [functions] +description: Returns the given string, removing the prefix from the beginning of the string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimRight + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimPrefix PREFIX STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimprefix] --- -Given the string `"aabbaa"`, the specified prefix is only removed if `"aabbaa"` starts with it: - ```go-html-template -{{ strings.TrimPrefix "a" "aabbaa" }} → "abbaa" -{{ strings.TrimPrefix "aa" "aabbaa" }} → "bbaa" -{{ strings.TrimPrefix "aaa" "aabbaa" }} → "aabbaa" +{{ strings.TrimPrefix "a" "aabbaa" }} → abbaa +{{ strings.TrimPrefix "aa" "aabbaa" }} → bbaa +{{ strings.TrimPrefix "aaa" "aabbaa" }} → aabbaa ``` diff --git a/docs/content/en/functions/strings/TrimRight.md b/docs/content/en/functions/strings/TrimRight.md index fa538b605..b244925ef 100644 --- a/docs/content/en/functions/strings/TrimRight.md +++ b/docs/content/en/functions/strings/TrimRight.md @@ -1,33 +1,28 @@ --- title: strings.TrimRight -description: Returns a slice of a given string with all trailing characters contained in the cutset removed. -categories: [functions] +description: Returns the given string, removing trailing characters specified in the cutset. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimSuffix returnType: string signatures: [strings.TrimRight CUTSET STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimright] --- -Given the string `"abba"`, trailing `"a"`'s can be removed a follows: - ```go-html-template -{{ strings.TrimRight "a" "abba" }} → "abb" +{{ strings.TrimRight "a" "abba" }} → abb ``` -Numbers can be handled as well: +The `strings.TrimRight` function converts the arguments to strings if possible: ```go-html-template -{{ strings.TrimRight 12 1221341221 }} → "122134" +{{ strings.TrimRight 54 12345 }} → 123 (string) +{{ strings.TrimRight "eu" true }} → tr ``` diff --git a/docs/content/en/functions/strings/TrimSuffix.md b/docs/content/en/functions/strings/TrimSuffix.md index 6dc9becfc..704bbd2d2 100644 --- a/docs/content/en/functions/strings/TrimSuffix.md +++ b/docs/content/en/functions/strings/TrimSuffix.md @@ -1,29 +1,23 @@ --- title: strings.TrimSuffix -description: Returns a given string s without the provided trailing suffix string. If s doesn't end with suffix, s is returned unchanged. -categories: [functions] +description: Returns the given string, removing the suffix from the end of the string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight returnType: string signatures: [strings.TrimSuffix SUFFIX STRING] -relatedFunctions: - - strings.Chomp - - strings.Trim - - strings.TrimLeft - - strings.TrimPrefix - - strings.TrimRight - - strings.TrimSuffix aliases: [/functions/strings.trimsuffix] --- -Given the string `"aabbaa"`, the specified suffix is only removed if `"aabbaa"` ends with it: - ```go-html-template -{{ strings.TrimSuffix "a" "aabbaa" }} → "aabba" -{{ strings.TrimSuffix "aa" "aabbaa" }} → "aabb" -{{ strings.TrimSuffix "aaa" "aabbaa" }} → "aabbaa" +{{ strings.TrimSuffix "a" "aabbaa" }} → aabba +{{ strings.TrimSuffix "aa" "aabbaa" }} → aabb +{{ strings.TrimSuffix "aaa" "aabbaa" }} → aabbaa ``` diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md index 0bd78d840..17ae0afc6 100644 --- a/docs/content/en/functions/strings/Truncate.md +++ b/docs/content/en/functions/strings/Truncate.md @@ -1,17 +1,13 @@ --- title: strings.Truncate -linkTitle: truncate -description: Truncates a text to a max length without cutting words or leaving unclosed HTML tags. -categories: [functions] +description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [truncate] + related: [] returnType: template.HTML signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] -relatedFunctions: [] aliases: [/functions/truncate] --- @@ -22,5 +18,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s ``` {{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML` template function](/functions/safe/html) before sending the value to truncate. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. +If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. + +[`safeHTML`]: /functions/safe/html {{% /note %}} diff --git a/docs/content/en/functions/strings/_index.md b/docs/content/en/functions/strings/_index.md new file mode 100644 index 000000000..364522a3a --- /dev/null +++ b/docs/content/en/functions/strings/_index.md @@ -0,0 +1,12 @@ +--- +title: String functions +linkTitle: strings +description: Template functions to work with strings. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with strings. diff --git a/docs/content/en/functions/templates/Exists.md b/docs/content/en/functions/templates/Exists.md index d4a8fab76..e57610488 100644 --- a/docs/content/en/functions/templates/Exists.md +++ b/docs/content/en/functions/templates/Exists.md @@ -1,23 +1,19 @@ --- title: templates.Exists -description: Reports whether a template file exists under the given path relative to the `layouts` directory. -categories: [functions] +description: Reports whether a template file exists under the given path relative to the layouts directory. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: [] returnType: bool signatures: [templates.Exists PATH] -namespace: templates -relatedFunctions: [] aliases: [/functions/templates.exists] --- -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. +A template file is any file within the `layouts` directory of either the project or any of its theme components. -The function is particularly handy with dynamic path. The following example ensures the build will not break on a `.Type` missing its dedicated `header` partial. +Use the `templates.Exists` function with dynamic template paths: ```go-html-template {{ $partialPath := printf "headers/%s.html" .Type }} @@ -27,3 +23,5 @@ The function is particularly handy with dynamic path. The following example ensu {{ partial "headers/default.html" . }} {{ end }} ``` + +In the example above, if a "headers" partial does not exist for the given content type, Hugo falls back to a default template. diff --git a/docs/content/en/functions/templates/_index.md b/docs/content/en/functions/templates/_index.md new file mode 100644 index 000000000..89da6c38f --- /dev/null +++ b/docs/content/en/functions/templates/_index.md @@ -0,0 +1,13 @@ +--- +title: Template functions +linkTitle: templates +description: +categories: [] +keywords: [] +menu: + docs: + identifier: templates-functions + parent: functions +--- + +Use these functions to query the template system. diff --git a/docs/content/en/functions/time/AsTime.md b/docs/content/en/functions/time/AsTime.md index 1244eeb5c..23e5304a5 100644 --- a/docs/content/en/functions/time/AsTime.md +++ b/docs/content/en/functions/time/AsTime.md @@ -1,64 +1,61 @@ --- title: time.AsTime -linkTitle: time -description: Converts a timestamp string into a `time.Time` structure. -categories: [functions] +description: Returns the given string representation of a date/time value as a time.Time value. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [time] + related: + - functions/time/Duration + - functions/time/Format + - functions/time/Now + - functions/time/ParseDuration returnType: time.Time signatures: ['time.AsTime INPUT [TIMEZONE]'] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/time] +toc: true --- +## Overview -`time` converts a timestamp string with an optional default location into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields: +Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function. ```go-html-template -{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z" -{{ (time "2016-05-28").YearDay }} → 149 -{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds +{{ $t := "2023-10-15T14:20:28-07:00" }} +{{ time.AsTime $t }} → 2023-10-15 14:20:28 -0700 PDT (time.Time) ``` -## Using locations +## Parsable strings -The optional `TIMEZONE` argument is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` argument. +As shown above, the first argument must be a *parsable* string representation of a date/time value. For example: -The list of valid locations may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). +{{% include "functions/time/_common/parsable-date-time-strings.md" %}} -If no `TIMEZONE` is set, the `timeZone` from site configuration will be used. +## Time zones -```go-html-template -{{ time "2020-10-20" }} → 2020-10-20 00:00:00 +0000 UTC -{{ time "2020-10-20" "America/Los_Angeles" }} → 2020-10-20 00:00:00 -0700 PDT -{{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST -``` +When the parsable string does not contain a time zone offset, you can do either of the following to assign a time zone other than Etc/UTC: + +- Provide a second argument to the `time.AsTime` function + + ```go-html-template + {{ time.AsTime "15 Oct 2023" "America/Chicago" }} + ``` -## Example: Using `time` to get month index +- Set the default time zone in your site configuration -The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index. + {{< code-toggle file=hugo >}} + timeZone = 'America/New_York' + {{< /code-toggle >}} -The following example may be useful when setting up [multilingual sites][multilingual]: +The order of precedence for determining the time zone is: -{{< code file="unix-to-month-integer.html" >}} -{{ $time := time (int .Params.addDate)}} -=> $time = 1489276800 -{{ $time.Month }} -=> "March" -{{ $monthindex := printf "%d" $time.Month }} -=> $monthindex = 3 -{{< /code >}} +1. The time zone offset in the date/time string +2. The time zone provide as the second argument to the `time.AsTime` function +3. The time zone specified in your site configuration +The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database]. -[int]: /functions/cast/toint -[multilingual]: /content-management/multilingual/ -[`printf`]: /functions/fmt/printf +[`time.Time`]: https://pkg.go.dev/time#Time +[functions]: /functions/time/ +[iana time zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +[methods]: /methods/time/ diff --git a/docs/content/en/functions/time/Duration.md b/docs/content/en/functions/time/Duration.md index 921f25a96..f9c26d294 100644 --- a/docs/content/en/functions/time/Duration.md +++ b/docs/content/en/functions/time/Duration.md @@ -1,40 +1,37 @@ --- title: time.Duration -linkTitle: duration -description: Returns a `time.Duration` structure, using the given time unit and duration number. -categories: [functions] +description: Returns a time.Duration value using the given time unit and number. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [duration] + related: + - functions/time/AsTime + - functions/time/Format + - functions/time/Now + - functions/time/ParseDuration returnType: time.Duration - signatures: [time.Duration TIME_UNIT DURATION_NUMBER] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration + signatures: [time.Duration TIME_UNIT NUMBER] aliases: [/functions/duration] --- -`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: +The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods]. + +This template: ```go-html-template -{{ printf "There are %.0f seconds in one day." (duration "hour" 24).Seconds }} -<!-- Output: There are 86400 seconds in one day. --> +{{ $duration := time.Duration "hour" 24 }} +{{ printf "There are %.0f seconds in one day." $duration.Seconds }} ``` -Make your code simpler to understand by using a [chained pipeline](https://pkg.go.dev/text/template#hdr-Pipelines): +Is rendered to: -```go-html-template -{{ mul 7.75 60 | duration "minute" }} → 7h45m0s -{{ mul 120 60 | mul 1000 | duration "millisecond" }} → 2h0m0s +```text +There are 86400 seconds in one day. ``` -You have to specify a time unit for the number given to the function. Valid time units are: +The time unit must be one of the following: + Duration|Valid time units :--|:-- @@ -44,3 +41,6 @@ seconds|`second`, `s` milliseconds|`millisecond`, `ms` microseconds|`microsecond`, `us`, `µs` nanoseconds|`nanosecond`, `ns` + +[`time.Duration`]: https://pkg.go.dev/time#Duration +[methods]: /methods/duration diff --git a/docs/content/en/functions/time/Format.md b/docs/content/en/functions/time/Format.md index 3a0b1eb2a..74384959b 100644 --- a/docs/content/en/functions/time/Format.md +++ b/docs/content/en/functions/time/Format.md @@ -1,51 +1,52 @@ --- title: time.Format -description: Returns a formatted and localized time.Time value. -categories: [functions] +description: Returns the given date/time as a formatted and localized string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [dateFormat] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Now + - functions/time/ParseDuration returnType: string signatures: [time.Format LAYOUT INPUT] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/dateformat] toc: true --- -```go-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $format := "2 Jan 2006" }} +Use the `time.Format` function with `time.Time` values: -{{ $t | time.Format $format }} → 27 Jan 2023 +```go-html-template +{{ $t := time.AsTime "2023-02-27T23:44:58-08:00" }} +{{ time.Format "2 Jan 2006" $t }} → 27 Feb 2023 +``` + +Or use `time.Format` with a *parsable* string representation of a date/time value: -{{ $t = time.AsTime $t }} -{{ $t | time.Format $format }} → 27 Jan 2023 +```go-html-template +{{ $t := "27 Feb 2023" }} +{{ time.Format "January 2, 2006" $t }} → February 27, 2023 ``` +Examples of parsable string representations: + +{{% include "functions/time/_common/parsable-date-time-strings.md" %}} + ## Layout string -{{% readfile file="/functions/_common/time-layout-string.md" %}} +{{% include "functions/_common/time-layout-string.md" %}} ## Localization Use the `time.Format` function to localize `time.Time` values for the current language and region. -{{% note %}} -{{% readfile file="/functions/_common/locales.md" %}} -{{% /note %}} - +{{% include "functions/_common/locales.md" %}} Use the layout string as described above, or one of the tokens below. For example: -```go-template +```go-html-template {{ .Date | time.Format ":date_medium" }} → Jan 27, 2023 ``` diff --git a/docs/content/en/functions/time/Now.md b/docs/content/en/functions/time/Now.md index 74b01ecc5..60e45a91c 100644 --- a/docs/content/en/functions/time/Now.md +++ b/docs/content/en/functions/time/Now.md @@ -1,51 +1,48 @@ --- title: time.Now -linkTitle: now -description: Returns the current local time -categories: [functions] +description: Returns the current local time. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [now] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Format + - functions/time/ParseDuration returnType: time.Time signatures: [time.Now] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/now] --- -See [`time.Time`](https://godoc.org/time#Time). - -For example, building your site on June 24, 2017, with the following templating: +For example, when building a site on October 15, 2023 in the America/Los_Angeles time zone: ```go-html-template -<div> - <small>© {{ now.Format "2006" }}</small> -</div> +{{ time.Now }} ``` -would produce the following: +This produces a `time.Time` value, with a string representation such as: -```html -<div> - <small>© 2017</small> -</div> +```text +2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605 ``` -The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Go's layout string. +To format and [localize] the value, pass it through the [`time.Format`] function: + +```go-html-template +{{ time.Now | time.Format "Jan 2006" }} → Oct 2023 +``` -{{% note %}} -Older Hugo themes may still be using the obsolete Page’s `.Now` (uppercase with leading dot), which causes build error that looks like the following: +The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example: - ERROR ... Error while rendering "..." in "...": ... - executing "..." at <.Now.Format>: - can't evaluate field Now in type *hugolib.PageOutput -Be sure to use `now` (lowercase with _**no**_ leading dot) in your templating. -{{% /note %}} +```go-html-template +{{ time.Now.Year }} → 2023 (int) +{{ time.Now.Weekday.String }} → Sunday +{{ time.Now.Month.String }} → October +{{ time.Now.Unix }} → 1697400955 (int64) +``` + +[`time.Format`]: /functions/time/format +[localize]: /getting-started/glossary/#localization +[time methods]: /methods/time/ diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md index e3abc7c15..091914132 100644 --- a/docs/content/en/functions/time/ParseDuration.md +++ b/docs/content/en/functions/time/ParseDuration.md @@ -1,30 +1,37 @@ --- title: time.ParseDuration -description: Parses a given duration string into a `time.Duration` structure. -categories: [functions] +description: Returns a time.Duration value by parsing the given duration string. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/time/AsTime + - functions/time/Duration + - functions/time/Format + - functions/time/Now returnType: time.Duration signatures: [time.ParseDuration DURATION] -relatedFunctions: - - time.AsTime - - time.Duration - - time.Format - - time.Now - - time.ParseDuration aliases: [/functions/time.parseduration] --- -`time.ParseDuration` parses a duration string into a [`time.Duration`](https://pkg.go.dev/time#Duration) structure so you can access its fields. +The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods]. + + A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. -You can perform [time operations](https://pkg.go.dev/time#Duration) on the returned `time.Duration` value: +This template: ```go-html-template -{{ printf "There are %.0f seconds in one day." (time.ParseDuration "24h").Seconds }} -<!-- Output: There are 86400 seconds in one day. --> +{{ $duration := time.ParseDuration "24h" }} +{{ printf "There are %.0f seconds in one day." $duration.Seconds }} +``` + +Is rendered to: + +```text +There are 86400 seconds in one day. ``` + +[`time.Duration`]: https://pkg.go.dev/time#Duration +[methods]: /methods/duration diff --git a/docs/content/en/functions/time/_common/_index.md b/docs/content/en/functions/time/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/time/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/time/_common/parsable-date-time-strings.md b/docs/content/en/functions/time/_common/parsable-date-time-strings.md new file mode 100644 index 000000000..a38b9983e --- /dev/null +++ b/docs/content/en/functions/time/_common/parsable-date-time-strings.md @@ -0,0 +1,14 @@ +--- +# Do not remove front matter. +--- + +String representation|Time zone +:--|:-- +2023-10-15T14:20:28-07:00|America/Los_Angeles +2023-10-15T13:18:50-0700|America/Los_Angeles +2023-10-15T13:18:50Z|Etc/UTC +2023-10-15T13:18:50|Etc/UTC +2023-10-15|Etc/UTC +15 Oct 2023|Etc/UTC + +The last four examples are not fully qualified. Without a time zone offset, the time zone is set to Etc/UTC (Coordinated Universal Time). diff --git a/docs/content/en/functions/time/_index.md b/docs/content/en/functions/time/_index.md new file mode 100644 index 000000000..7e0b82f91 --- /dev/null +++ b/docs/content/en/functions/time/_index.md @@ -0,0 +1,12 @@ +--- +title: Time functions +linkTitle: time +description: Template functions to work with time values. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with time values. diff --git a/docs/content/en/functions/transform/CanHighlight.md b/docs/content/en/functions/transform/CanHighlight.md index eabef933b..039cb12b7 100644 --- a/docs/content/en/functions/transform/CanHighlight.md +++ b/docs/content/en/functions/transform/CanHighlight.md @@ -1,19 +1,15 @@ --- title: transform.CanHighlight description: Reports whether the given code language is supported by the Chroma highlighter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/transform/Highlight + - functions/transform/HighlightCodeBlock returnType: bool signatures: [transform.CanHighlight LANGUAGE] -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock --- ```go-html-template diff --git a/docs/content/en/functions/transform/Emojify.md b/docs/content/en/functions/transform/Emojify.md index 324c41851..d9f0adf67 100644 --- a/docs/content/en/functions/transform/Emojify.md +++ b/docs/content/en/functions/transform/Emojify.md @@ -1,31 +1,30 @@ --- title: transform.Emojify -linkTitle: emojify description: Runs a string through the Emoji emoticons processor. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [emojify] + related: [] returnType: template.HTML signatures: [transform.Emojify INPUT] -namespace: transform -relatedFunctions: [] aliases: [/functions/emojify] --- `emojify` runs a passed string through the Emoji emoticons processor. -See the [Emoji cheat sheet][emojis] for available emoticons. +See the list of [emoji shortcodes] for available emoticons. -The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>: +The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files; + +```text I :heart: Hugo! +``` +I :heart: Hugo! [configuration]: /getting-started/configuration/ -[emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/ +[emoji shortcodes]: /quick-reference/emojis/ [sc]: /templates/shortcode-templates/ [scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes diff --git a/docs/content/en/functions/transform/HTMLEscape.md b/docs/content/en/functions/transform/HTMLEscape.md index 62249367b..bb522769c 100644 --- a/docs/content/en/functions/transform/HTMLEscape.md +++ b/docs/content/en/functions/transform/HTMLEscape.md @@ -1,24 +1,30 @@ --- title: transform.HTMLEscape -linkTitle: htmlEscape -description: Returns the given string with the reserved HTML codes escaped. -categories: [functions] +description: Returns the given string, escaping special characters by replacing them with HTML entities. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [htmlEscape] + related: + - functions/transform/HTMLUnescape returnType: string signatures: [transform.HTMLEscape INPUT] -relatedFunctions: - - transform.HTMLEscape - - transform.HTMLUnescape aliases: [/functions/htmlescape] --- -In the result `&` becomes `&` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`. +The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities]: + +- `&` → `&` +- `<` → `<` +- `>` → `>` +- `'` → `'` +- `"` → `"` + +For example: ```go-html-template -{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache" +{{ htmlEscape "Lilo & Stitch" }} → Lilo & Stitch +{{ htmlEscape "7 > 6" }} → 7 > 6 ``` + +[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity diff --git a/docs/content/en/functions/transform/HTMLUnescape.md b/docs/content/en/functions/transform/HTMLUnescape.md index c0774232f..180318077 100644 --- a/docs/content/en/functions/transform/HTMLUnescape.md +++ b/docs/content/en/functions/transform/HTMLUnescape.md @@ -1,24 +1,30 @@ --- title: transform.HTMLUnescape -linkTitle: htmlUnescape -description: Returns the given string with HTML escape codes un-escaped. -categories: [functions] +description: Returns the given string, replacing each HTML entity with its corresponding character. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [htmlUnescape] + related: + - functions/transform/HTMLEscape returnType: string signatures: [transform.HTMLUnescape INPUT] -relatedFunctions: - - transform.HTMLEscape - - transform.HTMLUnescape aliases: [/functions/htmlunescape] --- -Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal. +The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters. ```go-html-template -{{ htmlUnescape "Hugo & Caddy > WordPress & Apache" }} → "Hugo & Caddy > WordPress & Apache" +{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch +{{ htmlUnescape "7 > 6" }} → 7 > 6 ``` + +In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function. + +```go-html-template +{{ htmlUnescape "Lilo & Stitch" | safeHTML }} +``` + +[`safehtml`]: /functions/safe/html +[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity +[html/template]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/transform/Highlight.md b/docs/content/en/functions/transform/Highlight.md index 93043b4a1..29d0efdef 100644 --- a/docs/content/en/functions/transform/Highlight.md +++ b/docs/content/en/functions/transform/Highlight.md @@ -1,21 +1,15 @@ --- title: transform.Highlight -linkTitle: highlight description: Renders code with a syntax highlighter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [highlight] + related: + - functions/transform/CanHighlight + - functions/transform/HighlightCodeBlock returnType: template.HTML signatures: ['transform.Highlight INPUT LANG [OPTIONS]'] -namespace: transform -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock aliases: [/functions/highlight] toc: true --- @@ -31,7 +25,7 @@ LANG : The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive. OPTIONS -: An optional, comma-separated list of zero or more [options]. Set default values in [site configuration]. +: A map, or comma-separated list, of zero or more [options]. Set default values in [site configuration]. ## Options @@ -57,7 +51,7 @@ The number to display at the beginning of the first line. Irrelevant if `lineNos hl_Lines : String. Default is `""`.\ -A space-separated list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. +A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option. hl_inline : Boolean. Default is `false`.\ @@ -82,10 +76,10 @@ If the `LANG` argument is blank or an unrecognized language, auto-detect the lan {{% note %}} Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: -`lineNos=inline` +lineNos=inline : equivalent to `lineNos=true` and `lineNumbersInTable=false` -`lineNos=table` +lineNos=table : equivalent to `lineNos=true` and `lineNumbersInTable=true` {{% /note %}} @@ -101,8 +95,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f {{ $input := `echo "Hello World!"` }} {{ $lang := "bash" }} -{{ $options := dict "lineNos" "table" "style" "dracula" }} -{{ transform.Highlight $input $lang $options }} +{{ $opts := dict "lineNos" "table" "style" "dracula" }} +{{ transform.Highlight $input $lang $opts }} ``` [Chroma]: https://github.com/alecthomas/chroma diff --git a/docs/content/en/functions/transform/HighlightCodeBlock.md b/docs/content/en/functions/transform/HighlightCodeBlock.md index fa7045641..dc396bad0 100644 --- a/docs/content/en/functions/transform/HighlightCodeBlock.md +++ b/docs/content/en/functions/transform/HighlightCodeBlock.md @@ -1,19 +1,15 @@ --- title: transform.HighlightCodeBlock description: Highlights code received in context within a code block render hook. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/transform/CanHighlight + - functions/transform/Highlight returnType: highlight.HighlightResult signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] -relatedFunctions: - - transform.CanHighlight - - transform.Highlight - - transform.HighlightCodeBlock --- This function is only useful within a code block render hook. @@ -26,7 +22,6 @@ Given the context passed into a code block render hook, `transform.HighlightCode .Inner : (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper. - ```go-html-template {{ $result := transform.HighlightCodeBlock . }} {{ $result.Wrapped }} @@ -35,8 +30,8 @@ Given the context passed into a code block render hook, `transform.HighlightCode To override the default [highlighting options]: ```go-html-template -{{ $options := merge .Options (dict "linenos" true) }} -{{ $result := transform.HighlightCodeBlock . $options }} +{{ $opts := merge .Options (dict "linenos" true) }} +{{ $result := transform.HighlightCodeBlock . $opts }} {{ $result.Wrapped }} ``` diff --git a/docs/content/en/functions/transform/Markdownify.md b/docs/content/en/functions/transform/Markdownify.md index b0be902ce..8fb1e48ce 100644 --- a/docs/content/en/functions/transform/Markdownify.md +++ b/docs/content/en/functions/transform/Markdownify.md @@ -1,34 +1,30 @@ --- title: transform.Markdownify -linkTitle: markdownify description: Renders markdown to HTML. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [markdownify] + related: + - methods/page/RenderString + - methods/page/RenderShortcodes returnType: template.HTML signatures: [transform.Markdownify INPUT] -relatedFunctions: [] aliases: [/functions/markdownify] --- ```go-html-template -{{ .Title | markdownify }} +<h2>{{ .Title | markdownify }}</h2> ``` If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above. -To keep the wrapping `p` tags for a single paragraph, use the [`.Page.RenderString`] method, setting the `display` option to `block`. +To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`. -If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place. - -[`.Page.RenderString`]: /functions/renderstring/ +[`RenderString`]: /methods/page/renderstring/ {{% note %}} -Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `.Page.RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. +Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. [markdown render hooks]: /templates/render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 diff --git a/docs/content/en/functions/transform/Plainify.md b/docs/content/en/functions/transform/Plainify.md index 163233d4a..040145170 100644 --- a/docs/content/en/functions/transform/Plainify.md +++ b/docs/content/en/functions/transform/Plainify.md @@ -1,24 +1,16 @@ --- title: transform.Plainify -linkTitle: plainify description: Returns a string with all HTML tags removed. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [plainify] + related: [] returnType: string signatures: [transform.Plainify INPUT] -relatedFunctions: [] aliases: [/functions/plainify] --- ```go-html-template -{{ "<b>BatMan</b>" | plainify }} → "BatMan" +{{ "<b>BatMan</b>" | plainify }} → BatMan ``` - -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. - -[pagevars]: /variables/page/ diff --git a/docs/content/en/functions/transform/Remarshal.md b/docs/content/en/functions/transform/Remarshal.md index 8f6e58247..24ef4381d 100644 --- a/docs/content/en/functions/transform/Remarshal.md +++ b/docs/content/en/functions/transform/Remarshal.md @@ -1,23 +1,19 @@ --- title: transform.Remarshal description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/encoding/Jsonify + - functions/transform/Unmarshal returnType: string signatures: [transform.Remarshal FORMAT INPUT] -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal aliases: [/functions/transform.remarshal] --- -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. +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. {{% note %}} This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md index ab32d13de..02524509b 100644 --- a/docs/content/en/functions/transform/Unmarshal.md +++ b/docs/content/en/functions/transform/Unmarshal.md @@ -1,83 +1,289 @@ --- title: transform.Unmarshal -description: Parses the input and converts it into a map or an array. Supported formats are JSON, TOML, YAML, XML and CSV. -categories: [functions] +description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [unmarshal] + related: + - functions/transform/Remarshal + - functions/resources/Get + - functions/resources/GetRemote + - functions/encoding/Jsonify returnType: any - signatures: - - RESOURCE or STRING | transform.Unmarshal [OPTIONS] - - RESOURCE or STRING | unmarshal [OPTIONS] -relatedFunctions: - - encoding.Jsonify - - transform.Remarshal - - transform.Unmarshal + signatures: ['transform.Unmarshal [OPTIONS] INPUT'] +toc: true aliases: [/functions/transform.unmarshal] --- -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: +The input can be a string or a [resource]. + +## Unmarshal a string + +```go-html-template +{{ $string := ` +title: Les Misérables +author: Victor Hugo +`}} + +{{ $book := unmarshal $string }} +{{ $book.title }} → Les Misérables +{{ $book.author }} → Victor Hugo +``` + +## Unmarshal a resource + +Use the `transform.Unmarshal` function with global, page, and remote resources. + +### Global resource + +A global resource is a file within the assets directory, or within any directory mounted to the assets directory. + +```text +assets/ +└── data/ + └── books.json +``` ```go-html-template -{{ $greetings := "hello = \"Hello Hugo\"" | transform.Unmarshal }}` +{{ $data := "" }} +{{ $path := "data/books.json" }} +{{ with resources.Get $path }} + {{ with unmarshal . }} + {{ $data = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get global resource %q" $path }} +{{ end }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} +``` + +### Page resource + +A page resource is a file within a [page bundle]. + +```text +content/ +├── post/ +│ └── book-reviews/ +│ ├── books.json +│ └── index.md +└── _index.md ``` ```go-html-template -{{ $greetings := "hello = \"Hello Hugo\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }} +{{ $data := "" }} +{{ $path := "books.json" }} +{{ with .Resources.Get $path }} + {{ with unmarshal . }} + {{ $data = . }} + {{ end }} +{{ else }} + {{ errorf "Unable to get page resource %q" $path }} +{{ end }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} ``` -In both the above examples, you get a map you can work with: +### Remote resource + +A remote resource is a file on a remote server, accessible via HTTP or HTTPS. ```go-html-template -{{ $greetings.hello }} +{{ $data := "" }} +{{ $url := "https://example.org/books.json" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $data = . | transform.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} + +{{ range where $data "author" "Victor Hugo" }} + {{ .title }} → Les Misérables +{{ end }} ``` -The above prints `Hello Hugo`. +[resource]: /getting-started/glossary/#resource +[page bundle]: /content-management/page-bundles -## CSV options +## Options -Unmarshal with CSV as input has some options you can set: +When unmarshaling a CSV file, provide an optional map of options. delimiter -: The delimiter used, default is `,`. +: (`string`) The delimiter used, default is `,`. comment -: The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.: - -Example: +: (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored. ```go-html-template {{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }} ``` -## XML data - -As a convenience, Hugo allows you to access XML data in the same way that you access JSON, TOML, and YAML: you do not need to specify the root node when accessing the data. +## Working with XML -To get the contents of `<title>` in the document below, you use `{{ .message.title }}`: +When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`. ```xml -<root> - <message> - <title>Hugo rocks!</title> - <description>Thanks for using Hugo</description> - </message> -</root> +<?xml version="1.0" encoding="utf-8" standalone="yes"?> +<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <title>Books on Example Site</title> + <link>https://example.org/books/</link> + <description>Recent content in Books on Example Site</description> + <language>en-US</language> + <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" /> + <item> + <title>The Hunchback of Notre Dame</title> + <description>Written by Victor Hugo</description> + <link>https://example.org/books/the-hunchback-of-notre-dame/</link> + <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate> + <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid> + </item> + <item> + <title>Les Misérables</title> + <description>Written by Victor Hugo</description> + <link>https://example.org/books/les-miserables/</link> + <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate> + <guid>https://example.org/books/les-miserables/</guid> + </item> + </channel> +</rss> ``` -The following example lists the items of an RSS feed: +Get the remote data: ```go-html-template -{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }} - {{ range .channel.item }} - <strong>{{ .title | plainify | htmlUnescape }}</strong><br> - <p>{{ .description | plainify | htmlUnescape }}</p> - {{ $link := .link | plainify | htmlUnescape }} - <a href="{{ $link }}">{{ $link }}</a><br> - <hr> +{{ $data := "" }} +{{ $url := "https://example.org/books/index.xml" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $data = . | transform.Unmarshal }} {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} {{ end }} ``` + +Inspect the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") $data }}</pre> +``` + +List the book titles: + +```go-html-template +{{ with $data.channel.item }} + <ul> + {{ range . }} + <li>{{ .title }}</li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders this to: + +```html +<ul> + <li>The Hunchback of Notre Dame</li> + <li>Les Misérables</li> +</ul> +``` + +### XML attributes and namespaces + +Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number: + +```xml +<?xml version="1.0" encoding="utf-8" standalone="yes"?> +<rss version="2.0" + xmlns:atom="http://www.w3.org/2005/Atom" + xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd" +> + <channel> + <title>Books on Example Site</title> + <link>https://example.org/books/</link> + <description>Recent content in Books on Example Site</description> + <language>en-US</language> + <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" /> + <item> + <title lang="fr">The Hunchback of Notre Dame</title> + <description>Written by Victor Hugo</description> + <isbn:number>9780140443530</isbn:number> + <link>https://example.org/books/the-hunchback-of-notre-dame/</link> + <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate> + <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid> + </item> + <item> + <title lang="en">Les Misérables</title> + <description>Written by Victor Hugo</description> + <isbn:number>9780451419439</isbn:number> + <link>https://example.org/books/les-miserables/</link> + <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate> + <guid>https://example.org/books/les-miserables/</guid> + </item> + </channel> +</rss> +``` + +After retrieving the remote data, inspect the data structure: + +```go-html-template +<pre>{{ jsonify (dict "indent" " ") $data }}</pre> +``` + +Each item node looks like this: + +```json +{ + "description": "Written by Victor Hugo", + "guid": "https://example.org/books/the-hunchback-of-notre-dame/", + "link": "https://example.org/books/the-hunchback-of-notre-dame/", + "number": "9780140443530", + "pubDate": "Mon, 09 Oct 2023 09:27:12 -0700", + "title": { + "#text": "The Hunchback of Notre Dame", + "-lang": "fr" + } +} +``` + +The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values: + +```go-html-template +{{ with $data.channel.item }} + <ul> + {{ range . }} + {{ $title := index .title "#text" }} + {{ $lang := index .title "-lang" }} + {{ $ISBN := .number }} + <li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li> + {{ end }} + </ul> +{{ end }} +``` + +Hugo renders this to: + +```html +<ul> + <li>The Hunchback of Notre Dame (fr) 9780140443530</li> + <li>Les Misérables (en) 9780451419439</li> +</ul> +``` + +[`index`]: /functions/collections/indexfunction +[identifiers]: https://go.dev/ref/spec#Identifiers diff --git a/docs/content/en/functions/transform/_index.md b/docs/content/en/functions/transform/_index.md new file mode 100644 index 000000000..70e286b24 --- /dev/null +++ b/docs/content/en/functions/transform/_index.md @@ -0,0 +1,12 @@ +--- +title: Transform functions +linkTitle: transform +description: Template functions to transform values from one format to another. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to transform values from one format to another. diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md index ad73bbff0..876552bb7 100644 --- a/docs/content/en/functions/urls/AbsLangURL.md +++ b/docs/content/en/functions/urls/AbsLangURL.md @@ -1,21 +1,16 @@ --- title: urls.AbsLangURL -linkTitle: absLangURL description: Returns an absolute URL with a language prefix, if any. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [absLangURL] - returnType: template.HTML + related: + - functions/urls/AbsURL + - functions/urls/RelLangURL + - functions/urls/RelURL + returnType: string signatures: [urls.AbsLangURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/abslangurl] --- diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md index bb6816f57..5b027ae84 100644 --- a/docs/content/en/functions/urls/AbsURL.md +++ b/docs/content/en/functions/urls/AbsURL.md @@ -1,25 +1,20 @@ --- title: urls.AbsURL -linkTitle: absURL description: Returns an absolute URL. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [absURL] - returnType: template.html + related: + - functions/urls/AbsLangURL + - functions/urls/RelLangURL + - functions/urls/RelURL + returnType: string signatures: [urls.AbsURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/absurl] --- -With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on: +With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on: - Whether the input begins with a slash - The `baseURL` in site configuration diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md index 15efe9a5e..72b3d54a9 100644 --- a/docs/content/en/functions/urls/Anchorize.md +++ b/docs/content/en/functions/urls/Anchorize.md @@ -1,31 +1,37 @@ --- title: urls.Anchorize -linkTitle: anchorize -description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#default-configuration) does for markdown headers. -categories: [functions] +description: Returns the given string, sanitized for usage in an HTML id attribute. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [anchorize] + related: + - functions/urls/URLize returnType: string signatures: [urls.Anchorize INPUT] -relatedFunctions: - - urls.Anchorize - - urls.URLize aliases: [/functions/anchorize] --- -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). +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags. +## Sanitizing logic -```go-html-template -{{ anchorize "This is a header" }} → "this-is-a-header" -{{ anchorize "This is also a header" }} → "this-is-also----a-header" -{{ anchorize "main.go" }} → "maingo" -{{ anchorize "Article 123" }} → "article-123" -{{ anchorize "<- Let's try this, shall we?" }} → "--lets-try-this-shall-we" -{{ anchorize "Hello, 世界" }} → "hello-世界" -``` +With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +autoHeadingIDType = 'github' +{{< /code-toggle >}} + +This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML. + +Set `autoHeadingIDType` to one of: + +github +: Compatible with GitHub. This is the default, and strongly recommended. + +github-ascii +: Similar to the "github" setting, but removes non-ASCII characters. + +blackfriday +: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release. diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md index 41adf7ee7..7acecb506 100644 --- a/docs/content/en/functions/urls/JoinPath.md +++ b/docs/content/en/functions/urls/JoinPath.md @@ -1,30 +1,28 @@ --- title: urls.JoinPath description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/path/Join returnType: string signatures: [urls.JoinPath ELEMENT...] -relatedFunctions: - - path.Join - - urls.JoinPath aliases: [/functions/urls.joinpath] --- +{{< new-in 0.112.0 >}} + ```go-html-template -{{ urls.JoinPath }} → "" -{{ urls.JoinPath "" }} → "/" -{{ urls.JoinPath "a" }} → "a" -{{ urls.JoinPath "a" "b" }} → "a/b" -{{ urls.JoinPath "/a" "b" }} → "/a/b" -{{ urls.JoinPath "https://example.org" "b" }} → "https://example.org/b" +{{ urls.JoinPath }} → "" (empty string) +{{ urls.JoinPath "" }} → / +{{ urls.JoinPath "a" }} → a +{{ urls.JoinPath "a" "b" }} → a/b +{{ urls.JoinPath "/a" "b" }} → /a/b +{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b -{{ urls.JoinPath (slice "a" "b") }} → "a/b" +{{ urls.JoinPath (slice "a" "b") }} → a/b ``` Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes. diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md index 17c924d51..2eb4eeadf 100644 --- a/docs/content/en/functions/urls/Parse.md +++ b/docs/content/en/functions/urls/Parse.md @@ -1,16 +1,13 @@ --- title: urls.Parse description: Parses a URL into a URL structure. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: URL + related: [] + returnType: url.URL signatures: [urls.Parse URL] -relatedFunctions: [] aliases: [/functions/urls.parse] --- @@ -18,7 +15,6 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/ [scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1 - ```go-html-template {{ $url := "https://example.org:123/foo?a=6&b=7#bar" }} {{ $u := urls.Parse $url }} diff --git a/docs/content/en/functions/urls/Ref.md b/docs/content/en/functions/urls/Ref.md index 908fd6ca8..6cd97f030 100644 --- a/docs/content/en/functions/urls/Ref.md +++ b/docs/content/en/functions/urls/Ref.md @@ -1,26 +1,24 @@ --- title: urls.Ref -linkTitle: ref -description: Returns the absolute permalink to a page. -categories: [functions] +description: Returns the absolute permalink to a page at the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [ref] - returnType: template.HTML - signatures: [urls.Ref . PAGE] -relatedFunctions: - - urls.Ref - - urls.RelRef + related: + - functions/urls/RelRef + - methods/page/Ref + - methods/page/RelRef + returnType: string + signatures: + - urls.Ref PAGE PATH + - urls.Ref PAGE OPTIONS aliases: [/functions/ref] --- -This function takes two arguments: +The first argument is the context of the page from which to resolve relative paths, typically the current page. -- The context of the page from which to resolve relative paths, typically the current page (`.`) -- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. +The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. ```go-html-template {{ ref . "about" }} @@ -32,6 +30,19 @@ This function takes two arguments: {{ ref . "/blog/my-post.md" }} ``` +## Options + +Instead of specifying a path, you can also provide an options map: + +path +: (`string`) The path to the page, relative to the content directory. Required. + +lang +: (`string`) The language (site) to search for the page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format to search for the page. Default is the current output format. Optional. + To return the absolute permalink to another language version of a page: ```go-html-template @@ -44,6 +55,9 @@ To return the absolute permalink to another Output Format of a page: {{ ref . (dict "path" "about.md" "outputFormat" "rss") }} ``` -Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. -This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md index b8850c71d..2c1037038 100644 --- a/docs/content/en/functions/urls/RelLangURL.md +++ b/docs/content/en/functions/urls/RelLangURL.md @@ -1,21 +1,16 @@ --- title: urls.RelLangURL -linkTitle: relLangURL description: Returns a relative URL with a language prefix, if any. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relLangURL] - returnType: template.HTML + related: + - functions/urls/AbsLangURL + - functions/urls/AbsURL + - functions/urls/RelURL + returnType: string signatures: [urls.RelLangURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/rellangurl] --- @@ -37,7 +32,7 @@ With `baseURL = https://example.org/` {{ relLangURL "" }} → /en/ {{ relLangURL "articles" }} → /en/articles {{ relLangURL "style.css" }} → /en/style.css -``` +``` With `baseURL = https://example.org/docs/` @@ -57,7 +52,7 @@ With `baseURL = https://example.org/` {{ relLangURL "/" }} → /en/ {{ relLangURL "/articles" }} → /en/articles {{ relLangURL "/style.css" }} → /en/style.css -``` +``` With `baseURL = https://example.org/docs/` diff --git a/docs/content/en/functions/urls/RelRef.md b/docs/content/en/functions/urls/RelRef.md index 1ff213b70..6b45b2131 100644 --- a/docs/content/en/functions/urls/RelRef.md +++ b/docs/content/en/functions/urls/RelRef.md @@ -1,27 +1,25 @@ --- title: urls.RelRef -linkTitle: relref -description: Returns the relative permalink to a page. -categories: [functions] +description: Returns the relative permalink to a page at the given path. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relref] - returnType: template.HTML - signatures: [urls.RelRef . PAGE] -relatedFunctions: - - urls.Ref - - urls.RelRef + related: + - functions/urls/Ref + - methods/page/Ref + - methods/page/RelRef + returnType: string + signatures: + - urls.RelRef PAGE PATH + - urls.RelRef PAGE OPTIONS aliases: [/functions/relref] --- -This function takes two arguments: - -- The context of the page from which to resolve relative paths, typically the current page (`.`) -- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. +The first argument is the context of the page from which to resolve relative paths, typically the current page. +The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. +. ```go-html-template {{ relref . "about" }} {{ relref . "about#anchor" }} @@ -36,8 +34,21 @@ The permalink returned is relative to the protocol+host portion of the baseURL s Code|baseURL|Permalink :--|:--|:-- -`{{ relref . "/about" }}`|`http://example.org/`|`/about/` -`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/` +`{{ relref . "/about" }}`|`https://example.org/`|`/about/` +`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/` + +## Options + +Instead of specifying a path, you can also provide an options map: + +path +: (`string`) The path to the page, relative to the content directory. Required. + +lang +: (`string`) The language (site) to search for the page. Default is the current language. Optional. + +outputFormat +: (`string`) The output format to search for the page. Default is the current output format. Optional. To return the relative permalink to another language version of a page: @@ -51,6 +62,9 @@ To return the relative permalink to another Output Format of a page: {{ relref . (dict "path" "about.md" "outputFormat" "rss") }} ``` -Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). +By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. -This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). +{{< code-toggle file=hugo >}} +refLinksErrorLevel = 'warning' +refLinksNotFoundURL = '/some/other/url' +{{< /code-toggle >}} diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md index fa1f9af73..9320c2827 100644 --- a/docs/content/en/functions/urls/RelURL.md +++ b/docs/content/en/functions/urls/RelURL.md @@ -1,21 +1,16 @@ --- title: urls.RelURL -linkTitle: relURL description: Returns a relative URL. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [relURL] - returnType: template.HTML + related: + - functions/urls/AbsLangURL + - functions/urls/AbsURL + - functions/urls/RelLangURL + returnType: string signatures: [urls.RelURL INPUT] -relatedFunctions: - - urls.AbsLangURL - - urls.AbsURL - - urls.RelLangURL - - urls.RelURL aliases: [/functions/relurl] --- diff --git a/docs/content/en/functions/urls/URLize.md b/docs/content/en/functions/urls/URLize.md index 3c80a92f8..bf44a82d1 100644 --- a/docs/content/en/functions/urls/URLize.md +++ b/docs/content/en/functions/urls/URLize.md @@ -1,69 +1,63 @@ --- title: urls.URLize -linkTitle: urlize -description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens. -categories: [functions] +description: Returns the given string, sanitized for usage in a URL. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [urlize] + related: + - functions/urls/Anchorize returnType: string signatures: [urls.URLize INPUT] -relatedFunctions: - - urls.Anchorize - - urls.URLize aliases: [/functions/urlize] --- -The following examples pull from a content file with the following front matter: +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -{{< code-toggle file="content/blog/greatest-city.md" fm=true copy=false >}} -title = "The World's Greatest City" -location = "Chicago IL" -tags = ["pizza","beer","hot dogs"] +## Example + +Use the `urlize` function to create a link to a [term] page. + +Consider this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +author = 'authors' +{{< /code-toggle >}} + +And this front matter: + +{{< code-toggle file=content/books/les-miserables.md fm=true >}} +title = 'Les Misérables' +authors = ['Victor Hugo'] {{< /code-toggle >}} -The following might be used as a partial within a [single page template][singletemplate]: +The published site will have this structure: -{{< code file="layouts/partials/content-header.html" >}} -<header> - <h1>{{ .Title }}</h1> - {{ with .Params.location }} - <div><a href="/locations/{{ . | urlize }}">{{ . }}</a></div> - {{ end }} - <!-- Creates a list of tags for the content and links to each of their pages --> - {{ with .Params.tags }} - <ul> - {{ range .}} - <li> - <a href="/tags/{{ . | urlize }}">{{ . }}</a> - </li> - {{ end }} - </ul> - {{ end }} -</header> -{{< /code >}} +```text +public/ +├── authors/ +│ ├── victor-hugo/ +│ │ └── index.html +│ └── index.html +├── books/ +│ ├── les-miserables/ +│ │ └── index.html +│ └── index.html +└── index.html +``` -The preceding partial would then output to the rendered page as follows: +To create a link to the term page: -```html -<header> - <h1>The World's Greatest City</h1> - <div><a href="/locations/chicago-il">Chicago IL</a></div> - <ul> - <li> - <a href="/tags/pizza">pizza</a> - </li> - <li> - <a href="/tags/beer">beer</a> - </li> - <li> - <a href="/tags/hot-dogs">hot dogs</a> - </li> - </ul> -</header> +```go-html-template +{{ $taxonomy := "authors" }} +{{ $term := "Victor Hugo" }} +{{ with index .Site.Taxonomies $taxonomy (urlize $term) }} + <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> +{{ end }} ``` -[singletemplate]: /templates/single-page-templates/ +To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object. + +[`GetTerms`]: /methods/page/getterms/ +[term]: /getting-started/glossary/#term diff --git a/docs/content/en/functions/urls/_common/_index.md b/docs/content/en/functions/urls/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/functions/urls/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md new file mode 100644 index 000000000..0f01bcf78 --- /dev/null +++ b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md @@ -0,0 +1,35 @@ +--- +# Do not remove front matter. +--- + +The [`anchorize`] and [`urlize`] functions are similar: + +[`anchorize`]: /functions/urls/anchorize +[`urlize`]: /functions/urls/urlize + +- Use the `anchorize` function to generate an HTML `id` attribute value +- Use the `urlize` function to sanitize a string for usage in a URL + +For example: + +```go-html-template +{{ $s := "A B C" }} +{{ $s | anchorize }} → a-b-c +{{ $s | urlize }} → a-b-c + +{{ $s := "a b c" }} +{{ $s | anchorize }} → a-b---c +{{ $s | urlize }} → a-b-c + +{{ $s := "< a, b, & c >" }} +{{ $s | anchorize }} → -a-b--c- +{{ $s | urlize }} → a-b-c + +{{ $s := "main.go" }} +{{ $s | anchorize }} → maingo +{{ $s | urlize }} → main.go + +{{ $s := "Hugö" }} +{{ $s | anchorize }} → hugö +{{ $s | urlize }} → hug%C3%B6 +``` diff --git a/docs/content/en/functions/urls/_index.md b/docs/content/en/functions/urls/_index.md new file mode 100644 index 000000000..5f16feeeb --- /dev/null +++ b/docs/content/en/functions/urls/_index.md @@ -0,0 +1,12 @@ +--- +title: URL functions +linkTitle: urls +description: Template functions to work with URLs. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with URLs. |