From 233c321b8db82382775d917c9603f9a58aef4dd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Fri, 21 Jun 2024 12:59:30 +0200 Subject: [PATCH 1/3] Document templates.Defer --- content/en/functions/templates/Defer.md | 81 +++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 content/en/functions/templates/Defer.md diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md new file mode 100644 index 0000000000..32f4b9b266 --- /dev/null +++ b/content/en/functions/templates/Defer.md @@ -0,0 +1,81 @@ +--- +title: templates.Defer +description: Defer execution of a template until after all sites and output formats have been rendered. +categories: [] +keywords: [] +toc: true +action: + aliases: [] + related: [] + returnType: string + signatures: [templates.Defer OPTIONS] +aliases: [/functions/templates.defer] +--- + +{{< new-in "0.128.0" >}} + +{{% note %}} +This function only works in combination with the `with` keyword. +{{% /note %}} + +In some rare use cases, you may need defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](https://github.com/bep/hugo-starter-tailwind-basic) using the output of [hugo_stats.json](https://gohugo.io/getting-started/configuration/#configure-build) to determine which classes and other HTML identifiers are being used in the final output: + +```go-html-template +{{ with (templates.Defer (dict "key" "styles" )) }} + {{ $options := dict "inlineImports" true }} + {{ $styles := resources.Get "css/styles.css" }} + {{ $styles = $styles | resources.PostCSS $options }} + {{ if hugo.IsProduction }} + {{ $styles = $styles | minify | fingerprint }} + {{ end }} + +{{ end }} +``` + + +{{% note %}} +Variables defined on the outside are not visible on the inside and vice versa. +{{% /note %}} + +For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this: + +{{< code-toggle file=hugo >}} +[module] +[[module.mounts]] +source = "hugo_stats.json" +target = "assets/notwatching/hugo_stats.json" +disableWatch = true +[build] +writeStats = true +[[build.cachebusters]] +source = "assets/notwatching/hugo_stats\\.json" +target = "styles\\.css" +[[build.cachebusters]] +source = "(postcss|tailwind)\\.config\\.js" +target = "css" +{{< /code-toggle >}} + +## Options + +The `templates.Defer` function takes a single argument, a map with the following optional keys: + +key (`string`) +: The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript. + +data (`map`) +: Optional map to pass as data the deferred template. This will be available in the deferred template as `.` or `$`. + + +```go-html-template +Language Outside: {{ site.Language.Lang }} +Page Outside: {{ .RelPermalink }} +I18n: {{ i18n "hello" }} +{{ $data := (dict "page" . )}} +{{ with (templates.Defer (dict "data" $data )) }} + Language Inside: {{ site.Language.Lang }} + Page Inside: {{ .page.RelPermalink }} + I18n: {{ i18n "hello" }} +{{ end }} +``` + +The [Output Format](/templates/output-formats/), [Site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same inside and outside the deferred template. From 1bfa4fd39f6e43666c1858f6700c4fa3dfd30312 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Fri, 21 Jun 2024 15:15:15 +0200 Subject: [PATCH 2/3] Update content/en/functions/templates/Defer.md Co-authored-by: Joe Mooring --- content/en/functions/templates/Defer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md index 32f4b9b266..ae71f7345f 100644 --- a/content/en/functions/templates/Defer.md +++ b/content/en/functions/templates/Defer.md @@ -45,7 +45,7 @@ For the above to work well when running the server (or `hugo -w`), you want to h source = "hugo_stats.json" target = "assets/notwatching/hugo_stats.json" disableWatch = true -[build] +[build.buildStats] writeStats = true [[build.cachebusters]] source = "assets/notwatching/hugo_stats\\.json" From 7fdd78a1ffd3d5ca300c40abf829d93809d0b9bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Fri, 21 Jun 2024 15:21:07 +0200 Subject: [PATCH 3/3] Update content/en/functions/templates/Defer.md Co-authored-by: Joe Mooring --- content/en/functions/templates/Defer.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md index ae71f7345f..eb69b86ee2 100644 --- a/content/en/functions/templates/Defer.md +++ b/content/en/functions/templates/Defer.md @@ -14,14 +14,10 @@ aliases: [/functions/templates.defer] {{< new-in "0.128.0" >}} -{{% note %}} -This function only works in combination with the `with` keyword. -{{% /note %}} - -In some rare use cases, you may need defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](https://github.com/bep/hugo-starter-tailwind-basic) using the output of [hugo_stats.json](https://gohugo.io/getting-started/configuration/#configure-build) to determine which classes and other HTML identifiers are being used in the final output: +In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](https://github.com/bep/hugo-starter-tailwind-basic) using the output of [hugo_stats.json](https://gohugo.io/getting-started/configuration/#configure-build) to determine which classes and other HTML identifiers are being used in the final output: ```go-html-template -{{ with (templates.Defer (dict "key" "styles" )) }} +{{ with (templates.Defer (dict "key" "global-styles" )) }} {{ $options := dict "inlineImports" true }} {{ $styles := resources.Get "css/styles.css" }} {{ $styles = $styles | resources.PostCSS $options }} @@ -32,9 +28,13 @@ In some rare use cases, you may need defer the execution of a template until aft {{ end }} ``` +{{% note %}} +This function only works in combination with the `with` keyword. +{{% /note %}} + {{% note %}} -Variables defined on the outside are not visible on the inside and vice versa. +Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options). {{% /note %}} For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this: @@ -46,7 +46,7 @@ source = "hugo_stats.json" target = "assets/notwatching/hugo_stats.json" disableWatch = true [build.buildStats] -writeStats = true +enable = true [[build.cachebusters]] source = "assets/notwatching/hugo_stats\\.json" target = "styles\\.css" @@ -69,13 +69,13 @@ data (`map`) ```go-html-template Language Outside: {{ site.Language.Lang }} Page Outside: {{ .RelPermalink }} -I18n: {{ i18n "hello" }} +I18n Outside: {{ i18n "hello" }} {{ $data := (dict "page" . )}} {{ with (templates.Defer (dict "data" $data )) }} Language Inside: {{ site.Language.Lang }} Page Inside: {{ .page.RelPermalink }} - I18n: {{ i18n "hello" }} + I18n Inside: {{ i18n "hello" }} {{ end }} ``` -The [Output Format](/templates/output-formats/), [Site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same inside and outside the deferred template. +The [Output Format](/templates/output-formats/), [Site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside the deferred template.