summaryrefslogtreecommitdiffstats
path: root/docs/content/en/functions/templates
diff options
context:
space:
mode:
Diffstat (limited to 'docs/content/en/functions/templates')
-rw-r--r--docs/content/en/functions/templates/Current.md22
-rw-r--r--docs/content/en/functions/templates/Defer.md71
-rw-r--r--docs/content/en/functions/templates/Exists.md2
3 files changed, 50 insertions, 45 deletions
diff --git a/docs/content/en/functions/templates/Current.md b/docs/content/en/functions/templates/Current.md
index 805aeec05..d2c2c9609 100644
--- a/docs/content/en/functions/templates/Current.md
+++ b/docs/content/en/functions/templates/Current.md
@@ -47,7 +47,7 @@ debug = true
To visually mark where a template begins and ends execution:
-```go-html-template {file="layouts/_default/single.html"}
+```go-html-template {file="layouts/page.html"}
{{ define "main" }}
{{ if site.Params.debug }}
<div class="debug">[entering {{ templates.Current.Filename }}]</div>
@@ -66,7 +66,7 @@ To visually mark where a template begins and ends execution:
To display the chain of templates that led to the current one, create a partial template that iterates through its ancestors:
-```go-html-template {file="layouts/partials/template-call-stack.html" copy=true}
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
{{ with templates.Current }}
<div class="debug">
{{ range .Ancestors }}
@@ -81,7 +81,7 @@ To display the chain of templates that led to the current one, create a partial
Then call the partial from any template:
-```go-html-template {file="layouts/partials/footer/copyright.html" copy=true}
+```go-html-template {file="layouts/_partials/footer/copyright.html" copy=true}
{{ if site.Params.debug }}
{{ partial "template-call-stack.html" . }}
{{ end }}
@@ -90,15 +90,15 @@ Then call the partial from any template:
The rendered template stack would look something like this:
```text
-/home/user/project/layouts/partials/footer/copyright.html
-/home/user/project/themes/foo/layouts/partials/footer.html
-/home/user/project/layouts/_default/single.html
-/home/user/project/themes/foo/layouts/_default/baseof.html
+/home/user/project/layouts/_partials/footer/copyright.html
+/home/user/project/themes/foo/layouts/_partials/footer.html
+/home/user/project/layouts/page.html
+/home/user/project/themes/foo/layouts/baseof.html
```
To reverse the order of the entries, chain the `Reverse` method to the `Ancestors` method:
-```go-html-template {file="layouts/partials/template-call-stack.html" copy=true}
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
{{ with templates.Current }}
<div class="debug">
{{ range .Ancestors.Reverse }}
@@ -115,7 +115,7 @@ To reverse the order of the entries, chain the `Reverse` method to the `Ancestor
To render links that, when clicked, will open the template in Microsoft Visual Studio Code, create a partial template with anchor elements that use the `vscode` URI scheme:
-```go-html-template {file="layouts/partials/template-open-in-vs-code.html" copy=true}
+```go-html-template {file="layouts/_partials/template-open-in-vs-code.html" copy=true}
{{ with templates.Current.Parent }}
<div class="debug">
<a href="vscode://file/{{ .Filename }}">{{ .Name }}</a>
@@ -128,7 +128,7 @@ To render links that, when clicked, will open the template in Microsoft Visual S
Then call the partial from any template:
-```go-html-template {file="layouts/_default/single.html" copy=true}
+```go-html-template {file="layouts/page.html" copy=true}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
@@ -141,7 +141,7 @@ Then call the partial from any template:
Use the same approach to render the entire call stack as links:
-```go-html-template {file="layouts/partials/template-call-stack.html" copy=true}
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
{{ with templates.Current }}
<div class="debug">
{{ range .Ancestors }}
diff --git a/docs/content/en/functions/templates/Defer.md b/docs/content/en/functions/templates/Defer.md
index 6a9ca56ae..16c32724e 100644
--- a/docs/content/en/functions/templates/Defer.md
+++ b/docs/content/en/functions/templates/Defer.md
@@ -14,33 +14,34 @@ aliases: [/functions/templates.defer]
{{< new-in 0.128.0 />}}
> [!note]
-> This feature is meant to be used in the main page layout files/templates, and has undefined behavior when used from shortcodes, partials or render hook templates. See [this issue](https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391) for more info.
+> This feature should only be used in the main page template, typically `layouts/baseof.html`. Using it in shortcodes, partials, or render hook templates may lead to unpredictable results. For further details, please refer to [this issue].
+
+[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
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](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output:
-```go-html-template
-{{ with (templates.Defer (dict "key" "global")) }}
- {{ $t := debug.Timer "tailwindcss" }}
- {{ with resources.Get "css/styles.css" }}
- {{ $opts := dict
- "inlineImports" true
- "optimize" hugo.IsProduction
- }}
- {{ with . | css.TailwindCSS $opts }}
- {{ if hugo.IsDevelopment }}
- <link rel="stylesheet" href="{{ .RelPermalink }}" />
- {{ else }}
- {{ with . | minify | fingerprint }}
- <link
- rel="stylesheet"
- href="{{ .RelPermalink }}"
- integrity="{{ .Data.Integrity }}"
- crossorigin="anonymous" />
- {{ end }}
+```go-html-template {file="layouts/baseof.html" copy=true}
+<head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+</head>
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
- {{ $t.Stop }}
{{ end }}
```
@@ -52,19 +53,23 @@ In some rare use cases, you may need to defer the execution of a template until
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 >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
[module]
-[[module.mounts]]
-source = "hugo_stats.json"
-target = "assets/notwatching/hugo_stats.json"
-disableWatch = true
-[build.buildStats]
-enable = true
-[[build.cachebusters]]
-source = "assets/notwatching/hugo_stats\\.json"
-target = "styles\\.css"
-[[build.cachebusters]]
-source = "(postcss|tailwind)\\.config\\.js"
-target = "css"
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
{{< /code-toggle >}}
## Options
diff --git a/docs/content/en/functions/templates/Exists.md b/docs/content/en/functions/templates/Exists.md
index 79fc561c8..a8d627ff7 100644
--- a/docs/content/en/functions/templates/Exists.md
+++ b/docs/content/en/functions/templates/Exists.md
@@ -17,7 +17,7 @@ Use the `templates.Exists` function with dynamic template paths:
```go-html-template
{{ $partialPath := printf "headers/%s.html" .Type }}
-{{ if templates.Exists ( printf "partials/%s" $partialPath ) }}
+{{ if templates.Exists ( printf "_partials/%s" $partialPath ) }}
{{ partial $partialPath . }}
{{ else }}
{{ partial "headers/default.html" . }}