diff options
Diffstat (limited to 'docs/content/en/functions/templates')
-rw-r--r-- | docs/content/en/functions/templates/Current.md | 22 | ||||
-rw-r--r-- | docs/content/en/functions/templates/Defer.md | 71 | ||||
-rw-r--r-- | docs/content/en/functions/templates/Exists.md | 2 |
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" . }} |