diff options
Diffstat (limited to 'docs/content/en/functions')
29 files changed, 264 insertions, 207 deletions
diff --git a/docs/content/en/functions/collections/Shuffle.md b/docs/content/en/functions/collections/Shuffle.md index 3a27c099a..60af0a1ba 100644 --- a/docs/content/en/functions/collections/Shuffle.md +++ b/docs/content/en/functions/collections/Shuffle.md @@ -12,8 +12,18 @@ aliases: [/functions/shuffle] --- ```go-html-template -{{ shuffle (seq 1 2 3) }} → [3 1 2] -{{ shuffle (slice "a" "b" "c") }} → [b a c] +{{ collections.Shuffle (slice "a" "b" "c") }} → [b a c] ``` The result will vary from one build to the next. + +To render an unordered list of 5 random pages from a page collection: + +```go-html-template +<ul> + {{ $p := site.RegularPages }} + {{ range $p | collections.Shuffle | first 5 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` diff --git a/docs/content/en/functions/css/Sass.md b/docs/content/en/functions/css/Sass.md index 03a4c7451..ae628a15f 100644 --- a/docs/content/en/functions/css/Sass.md +++ b/docs/content/en/functions/css/Sass.md @@ -66,20 +66,20 @@ vars ```go-html-template {copy=true} {{ with resources.Get "sass/main.scss" }} {{ $opts := dict - "enableSourceMap" (not hugo.IsProduction) - "outputStyle" (cond hugo.IsProduction "compressed" "expanded") + "enableSourceMap" hugo.IsDevelopment + "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed") "targetPath" "css/main.css" "transpiler" "dartsass" "vars" site.Params.styles "includePaths" (slice "node_modules/bootstrap/scss") }} {{ with . | toCSS $opts }} - {{ if hugo.IsProduction }} + {{ if hugo.IsDevelopment }} + <link rel="stylesheet" href="{{ .RelPermalink }}"> + {{ else }} {{ with . | fingerprint }} <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> {{ end }} - {{ else }} - <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} {{ end }} {{ end }} @@ -113,7 +113,7 @@ 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. +You may also install [prebuilt binaries] for Linux, macOS, and Windows. You must install the prebuilt binary outside of your project directory and ensure its path is included in your system's PATH environment variable. Run `hugo env` to list the active transpilers. @@ -141,8 +141,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file ```yaml variables: - HUGO_VERSION: 0.144.2 - DART_SASS_VERSION: 1.85.0 + HUGO_VERSION: 0.147.9 + DART_SASS_VERSION: 1.89.2 GIT_DEPTH: 0 GIT_STRATEGY: clone GIT_SUBMODULE_STRATEGY: recursive @@ -175,8 +175,8 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should ```toml [build.environment] -HUGO_VERSION = "0.144.2" -DART_SASS_VERSION = "1.85.0" +HUGO_VERSION = "0.147.9" +DART_SASS_VERSION = "1.89.2" NODE_VERSION = "22" TZ = "America/Los_Angeles" diff --git a/docs/content/en/functions/css/TailwindCSS.md b/docs/content/en/functions/css/TailwindCSS.md index 6add7373a..9d40ad0aa 100644 --- a/docs/content/en/functions/css/TailwindCSS.md +++ b/docs/content/en/functions/css/TailwindCSS.md @@ -18,8 +18,10 @@ Use the `css.TailwindCSS` function to process your Tailwind CSS files. This func 1. Compile those utility classes into standard CSS. 1. Generate an optimized CSS output file. -> [!caution] -> Tailwind CSS v4.0 and later requires a relatively [modern browser](https://tailwindcss.com/docs/compatibility#browser-support) to render correctly. +> [!note] +> Use this function with Tailwind CSS v4.0 and later, which require a relatively [modern browser] to render correctly. + +[modern browser]: https://tailwindcss.com/docs/compatibility#browser-support ## Setup @@ -27,11 +29,12 @@ Use the `css.TailwindCSS` function to process your Tailwind CSS files. This func Install the Tailwind CSS CLI v4.0 or later: -```sh +```sh {copy=true} npm install --save-dev tailwindcss @tailwindcss/cli ``` -The TailwindCSS CLI is also available as a [standalone executable] if you want to use it without installing Node.js. +The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable. + [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest @@ -40,21 +43,23 @@ The TailwindCSS CLI is also available as a [standalone executable] if you want t Add this to your site configuration: {{< code-toggle file=hugo copy=true >}} -[[module.mounts]] -source = "assets" -target = "assets" -[[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 = "css" -[[build.cachebusters]] -source = "(postcss|tailwind)\\.config\\.js" -target = "css" +[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 = 'assets' + target = 'assets' + [[module.mounts]] + disableWatch = true + source = 'hugo_stats.json' + target = 'assets/notwatching/hugo_stats.json' {{< /code-toggle >}} ### Step 3 @@ -72,20 +77,15 @@ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` i Create a partial template to process the CSS with the Tailwind CSS CLI: -```go-html-template {file="layouts/partials/css.html" copy=true} -{{ with (templates.Defer (dict "key" "global")) }} - {{ with resources.Get "css/main.css" }} - {{ $opts := dict - "minify" hugo.IsProduction - "inlineImports" true - }} - {{ with . | css.TailwindCSS $opts }} - {{ if hugo.IsProduction }} - {{ with . | fingerprint }} - <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> - {{ end }} - {{ else }} - <link rel="stylesheet" href="{{ .RelPermalink }}"> +```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 }} @@ -94,33 +94,16 @@ Create a partial template to process the CSS with the Tailwind CSS CLI: ### Step 5 -Call the partial template from your base template: +Call the partial template from your base template, deferring template execution until after all sites and output formats have been rendered: -```go-html-template {file="layouts/_default/baseof.html"} +```go-html-template {file="layouts/baseof.html" copy=true} <head> ... - {{ partialCached "css.html" . }} + {{ with (templates.Defer (dict "key" "global")) }} + {{ partial "css.html" . }} + {{ end }} ... -<head> -``` - -### Step 6 - -Optionally create a `tailwind.config.js` file in the root of your project as shown below. This is necessary if you use the [Tailwind CSS IntelliSense -extension] for Visual Studio Code. - -[Tailwind CSS IntelliSense -extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss - -```js {file="tailwind.config.js" copy=true} -/* -This file is present to satisfy a requirement of the Tailwind CSS IntelliSense -extension for Visual Studio Code. - -https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss - -The rest of this file is intentionally empty. -*/ +</head> ``` ## Options @@ -131,8 +114,9 @@ minify optimize : (`bool`) Whether to optimize the output without minifying. Default is `false`. -inlineImports -: (`bool`) Whether to enable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`. +disableInlineImports +: {{< new-in 0.147.4 />}} +: (`bool`) Whether to disable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`. skipInlineImportsNotFound : (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default is `false`. diff --git a/docs/content/en/functions/debug/Timer.md b/docs/content/en/functions/debug/Timer.md index c2cd59211..74395b130 100644 --- a/docs/content/en/functions/debug/Timer.md +++ b/docs/content/en/functions/debug/Timer.md @@ -18,7 +18,7 @@ The timer starts when you instantiate it, and stops when you call its `Stop` met ```go-html-template {{ $t := debug.Timer "TestSqrt" }} -{{ range seq 2000 }} +{{ range 2000 }} {{ $f := math.Sqrt . }} {{ end }} {{ $t.Stop }} diff --git a/docs/content/en/functions/diagrams/Goat.md b/docs/content/en/functions/diagrams/Goat.md index e2f55eee0..5f6fcf1da 100644 --- a/docs/content/en/functions/diagrams/Goat.md +++ b/docs/content/en/functions/diagrams/Goat.md @@ -66,7 +66,7 @@ To customize rendering, override Hugo's [embedded code block render hook] for Go By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. -```go-html-template {file="layouts/_default/_markup/render-codeblock-goat.html"} +```go-html-template {file="layouts/_markup/render-codeblock-goat.html"} {{ $caption := or .Attributes.caption "" }} {{ $class := or .Attributes.class "diagram" }} {{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} diff --git a/docs/content/en/functions/global/page.md b/docs/content/en/functions/global/page.md index 0d4b8070f..40f6aba8f 100644 --- a/docs/content/en/functions/global/page.md +++ b/docs/content/en/functions/global/page.md @@ -30,7 +30,7 @@ When a `Page` object is not in context, you can use the global `page` function: ## Explanation -Hugo almost always passes a `Page` as the data context into the top-level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template. +Hugo almost always passes a `Page` as the data context into the top-level template (e.g., `baseof.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template. But when you are deeply nested inside of a [content view](g), [partial](g), or [render hook](g), it is not always practical or possible to access the `Page` object. diff --git a/docs/content/en/functions/go-template/block.md b/docs/content/en/functions/go-template/block.md index bffab1f8c..383a3d72e 100644 --- a/docs/content/en/functions/go-template/block.md +++ b/docs/content/en/functions/go-template/block.md @@ -23,7 +23,7 @@ and then executing it in place: ``` The typical use is to define a set of root templates that are then customized by redefining the block templates within. -```go-html-template {file="layouts/_default/baseof.html"} +```go-html-template {file="layouts/baseof.html"} <body> <main> {{ block "main" . }} @@ -33,14 +33,14 @@ The typical use is to define a set of root templates that are then customized by </body> ``` -```go-html-template {file="layouts/_default/single.html"} +```go-html-template {file="layouts/page.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ end }} ``` -```go-html-template {file="layouts/_default/list.html"} +```go-html-template {file="layouts/section.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} diff --git a/docs/content/en/functions/go-template/define.md b/docs/content/en/functions/go-template/define.md index 19762a3d6..40d495bd9 100644 --- a/docs/content/en/functions/go-template/define.md +++ b/docs/content/en/functions/go-template/define.md @@ -28,7 +28,7 @@ Use with the [`partial`] function: ```go-html-template {{ partial "inline/foo.html" (dict "answer" 42) }} -{{ define "partials/inline/foo.html" }} +{{ define "_partials/inline/foo.html" }} {{ printf "The answer is %v." .answer }} {{ end }} ``` @@ -43,8 +43,21 @@ Use with the [`template`] function: {{ end }} ``` +> [!warning] +> Only [template comments] are allowed outside of the `define` and `end` statements. Avoid placing any other text, including HTML comments, outside of these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below. + +```go-html-template {file="layouts/do-not-do-this.html"} +<div>This div element broke your template.</div> +{{ define "main" }} + <h2>{{ .Title }}</h2> + {{ .Content }} +{{ end }} +<!-- An HTML comment will break your template too. --> +``` + +{{% include "/_common/functions/go-template/text-template.md" %}} + [`block`]: /functions/go-template/block/ [`template`]: /functions/go-template/block/ [`partial`]: /functions/partials/include/ - -{{% include "/_common/functions/go-template/text-template.md" %}} +[template comments]: /templates/introduction/#comments diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index a06907c79..50f714140 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -11,7 +11,7 @@ params: aliases: [/functions/range] --- -{{% include "/_common/functions/truthy-falsy.md" %}} +The collection may be a slice, a map, or an integer. ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -40,19 +40,22 @@ Within a range block: At the top of a page template, the [context](g) (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: +With this contrived example: ```go-html-template -{{ range seq 3 }} - {{ .Title }} +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ .Title }} {{ end }} ``` Hugo will throw an error: - can't evaluate field Title in type int +```text +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. +The error occurs because we are trying to use the `.Title` method on a string 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. @@ -60,15 +63,18 @@ The error occurs because we are trying to use the `.Title` method on an integer This template will render the page title three times: ```go-html-template -{{ range seq 3 }} - {{ $.Title }} +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ $.Title }} {{ end }} ``` > [!note] > Gaining a thorough understanding of context is critical for anyone writing template code. -## Array or slice of scalars +## Examples + +### Slice of scalars This template code: @@ -121,7 +127,7 @@ Is rendered to: <p>2: baz</p> ``` -## Array or slice of maps +### Slice of maps This template code: @@ -144,7 +150,7 @@ Is rendered to: <p>Joey is 24</p> ``` -## Array or slice of pages +### Slice of pages This template code: @@ -162,7 +168,7 @@ Is rendered to: <h2><a href="/articles/article-1/">Article 1</a></h2> ``` -## Maps +### Maps This template code: @@ -182,9 +188,32 @@ Is rendered to: Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. +### Integers + +{{< new-in 0.123.0 />}} + +Ranging over a positive integer `n` executes the block `n` times, with the context starting at zero and incrementing by one in each iteration. + +```go-html-template +{{ $s := slice }} +{{ range 1 }} + {{ $s = $s | append . }} +{{ end }} +{{ $s }} → [0] +``` + +```go-html-template +{{ $s := slice }} +{{ range 3 }} + {{ $s = $s | append . }} +{{ end }} +{{ $s }} → [0 1 2] +``` + +Ranging over a non-positive integer executes the block zero times. + {{% include "/_common/functions/go-template/text-template.md" %}} [`break`]: /functions/go-template/break/ [`continue`]: /functions/go-template/continue/ [`else`]: /functions/go-template/else/ -[`seq`]: /functions/collections/seq/ diff --git a/docs/content/en/functions/go-template/return.md b/docs/content/en/functions/go-template/return.md index eb6ba30cd..911c0925c 100644 --- a/docs/content/en/functions/go-template/return.md +++ b/docs/content/en/functions/go-template/return.md @@ -23,7 +23,7 @@ A `return` statement without a value returns an empty string of type `template.H By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: -```go-html-template {file="layouts/partials/odd-or-even.html"} +```go-html-template {file="layouts/_partials/odd-or-even.html"} {{ if math.ModBool . 2 }} <p>{{ . }} is even</p> {{ else }} @@ -39,7 +39,7 @@ When called, the partial renders HTML: Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: -```go-html-template {file="layouts/partials/is-even.html"} +```go-html-template {file="layouts/_partials/is-even.html"} {{ return math.ModBool . 2 }} ``` @@ -60,8 +60,6 @@ Hugo renders: <p>42 is even</p> ``` -See additional examples in the [partial templates] section. - ## Usage > [!note] @@ -71,7 +69,7 @@ A partial that returns a value must contain only one `return` statement, placed For example: -```go-html-template {file="layouts/partials/is-even.html"} +```go-html-template {file="layouts/_partials/is-even.html"} {{ $result := false }} {{ if math.ModBool . 2 }} {{ $result = "even" }} @@ -84,7 +82,7 @@ For example: > [!note] > The construct below is incorrect; it contains more than one `return` statement. -```go-html-template {file="layouts/partials/do-not-do-this.html"} +```go-html-template {file="layouts/_partials/do-not-do-this.html"} {{ if math.ModBool . 2 }} {{ return "even" }} {{ else }} @@ -92,5 +90,4 @@ For example: {{ end }} ``` -[partial templates]: /templates/partial/#returning-a-value-from-a-partial [text/template package]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/template.md b/docs/content/en/functions/go-template/template.md index 053cfcc22..903f1490a 100644 --- a/docs/content/en/functions/go-template/template.md +++ b/docs/content/en/functions/go-template/template.md @@ -10,27 +10,7 @@ params: signatures: ['template NAME [CONTEXT]'] --- -Use the `template` function to execute any of these [embedded templates](g): - -- [`disqus.html`] -- [`google_analytics.html`] -- [`opengraph.html`] -- [`pagination.html`] -- [`schema.html`] -- [`twitter_cards.html`] - - - -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: +Use the `template` function to execute a defined template: ```go-html-template {{ template "foo" (dict "answer" 42) }} @@ -40,12 +20,12 @@ You can also use the `template` function to execute a defined template: {{ end }} ``` -The example above can be rewritten using an [inline partial] template: +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" }} +{{ define "_partials/inline/foo.html" }} {{ printf "The answer is %v." .answer }} {{ end }} ``` @@ -58,13 +38,5 @@ The key distinctions between the preceding two examples are: {{% include "/_common/functions/go-template/text-template.md" %}} -[`disqus.html`]: /templates/embedded/#disqus -[`google_analytics.html`]: /templates/embedded/#google-analytics -[`opengraph.html`]: /templates/embedded/#open-graph -[`pagination.html`]: /templates/embedded/#pagination [`partialCached`]: /functions/partials/includecached/ -[`partial`]: /functions/partials/include/ [`return`]: /functions/go-template/return/ -[`schema.html`]: /templates/embedded/#schema -[`twitter_cards.html`]: /templates/embedded/#x-twitter-cards -[inline partial]: /templates/partial/#inline-partials diff --git a/docs/content/en/functions/hugo/Generator.md b/docs/content/en/functions/hugo/Generator.md index dc72a7af2..c044a210c 100644 --- a/docs/content/en/functions/hugo/Generator.md +++ b/docs/content/en/functions/hugo/Generator.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.144.2"> +{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.147.9"> ``` diff --git a/docs/content/en/functions/hugo/Version.md b/docs/content/en/functions/hugo/Version.md index 7925af981..a23bd75cd 100644 --- a/docs/content/en/functions/hugo/Version.md +++ b/docs/content/en/functions/hugo/Version.md @@ -11,5 +11,5 @@ params: --- ```go-html-template -{{ hugo.Version }} → 0.144.2 +{{ hugo.Version }} → 0.147.9 ``` diff --git a/docs/content/en/functions/images/QR.md b/docs/content/en/functions/images/QR.md index eee2dff14..bf13e16e9 100644 --- a/docs/content/en/functions/images/QR.md +++ b/docs/content/en/functions/images/QR.md @@ -68,7 +68,7 @@ Specify `level`, `scale`, and `targetDir` as needed to achieve the desired resul To include a QR code that points to the `Permalink` of the current page: -```go-html-template {file="layouts/_default/single.html"} +```go-html-template {file="layouts/page.html"} {{ with images.QR .Permalink }} <img src="{{ .RelPermalink }}" diff --git a/docs/content/en/functions/images/Text.md b/docs/content/en/functions/images/Text.md index 8f7e730ba..c6a0e5b6e 100644 --- a/docs/content/en/functions/images/Text.md +++ b/docs/content/en/functions/images/Text.md @@ -19,6 +19,7 @@ alignx : (`string`) The horizontal alignment of the text relative to the horizontal offset, one of `left`, `center`, or `right`. Default is `left`. aligny +: {{< new-in 0.147.0 />}} : (`string`) The vertical alignment of the text relative to the vertical offset, one of `top`, `center`, or `bottom`. Default is `top`. color @@ -74,6 +75,7 @@ Create the filter, centering the text horizontally and vertically: {{ with $r = resources.Get $imagePath }} {{ $opts := dict "alignx" "center" + "aligny" "center" "color" "#fbfaf5" "font" $font "linespacing" 8 diff --git a/docs/content/en/functions/js/Build.md b/docs/content/en/functions/js/Build.md index 1bec6b16f..d55220a52 100644 --- a/docs/content/en/functions/js/Build.md +++ b/docs/content/en/functions/js/Build.md @@ -20,18 +20,18 @@ The `js.Build` function uses the [evanw/esbuild] package to: ```go-html-template {{ with resources.Get "js/main.js" }} - {{ $opts := dict - "minify" hugo.IsProduction - "sourceMap" (cond hugo.IsProduction "" "external") + {{$opts := dict + "minify" (not hugo.IsDevelopment) + "sourceMap" (cond hugo.IsDevelopment "external" "") "targetPath" "js/main.js" }} {{ with . | js.Build $opts }} - {{ if hugo.IsProduction }} + {{ if hugo.IsDevelopment }} + <script src="{{ .RelPermalink }}"></script> + {{ else }} {{ with . | fingerprint }} <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script> {{ end }} - {{ else }} - <script src="{{ .RelPermalink }}"></script> {{ end }} {{ end }} {{ end }} diff --git a/docs/content/en/functions/lang/Merge.md b/docs/content/en/functions/lang/Merge.md index db40c2669..f2ce16011 100644 --- a/docs/content/en/functions/lang/Merge.md +++ b/docs/content/en/functions/lang/Merge.md @@ -24,6 +24,6 @@ A more practical example is to fill in the missing translations from the other l ```sh {{ $pages := .Site.RegularPages }} {{ range .Site.Home.Translations }} -{{ $pages = $pages | lang.Merge .Site.RegularPages }} + {{ $pages = $pages | lang.Merge .Site.RegularPages }} {{ end }} ``` diff --git a/docs/content/en/functions/math/Counter.md b/docs/content/en/functions/math/Counter.md index 16456cec6..eec4df8b3 100644 --- a/docs/content/en/functions/math/Counter.md +++ b/docs/content/en/functions/math/Counter.md @@ -12,14 +12,14 @@ params: 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 }} +```go-html-template {file="layouts/page.html"} +{{ warnf "page.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 +```text +WARN page.html called 1 times +WARN page.html called 2 times +WARN page.html called 3 times ``` Use this function to: diff --git a/docs/content/en/functions/math/MaxInt64.md b/docs/content/en/functions/math/MaxInt64.md new file mode 100644 index 000000000..ee4f68ffd --- /dev/null +++ b/docs/content/en/functions/math/MaxInt64.md @@ -0,0 +1,27 @@ +--- +title: math.MaxInt64 +description: Returns the maximum value for a signed 64-bit integer. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: int64 + signatures: [math.MaxInt64] +--- + +{{< new-in 0.147.3 />}} + +```go-html-template +{{ math.MaxInt64 }} → 9223372036854775807 +``` + +This function is helpful for simulating a loop that continues indefinitely until a break condition is met. For example: + +```go-html-template +{{ range math.MaxInt64 }} + {{ if eq . 42 }} + {{ break }} + {{ end }} +{{ end }} +``` diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md index d1f928aeb..ca2ee93e3 100644 --- a/docs/content/en/functions/openapi3/Unmarshal.md +++ b/docs/content/en/functions/openapi3/Unmarshal.md @@ -39,7 +39,7 @@ To inspect the data structure: To list the GET and POST operations for each of the API paths: ```go-html-template -{{ range $path, $details := $api.Paths }} +{{ range $path, $details := $api.Paths.Map }} <p>{{ $path }}</p> <dl> {{ with $details.Get }} @@ -54,6 +54,11 @@ To list the GET and POST operations for each of the API paths: {{ end }} ``` +> [!warning] +> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration. +> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above). +> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions. + Hugo renders this to: ```html diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md index eb7eeafdc..0474bf77f 100644 --- a/docs/content/en/functions/partials/Include.md +++ b/docs/content/en/functions/partials/Include.md @@ -19,7 +19,7 @@ In this example we have three partial templates: ```text layouts/ -└── partials/ +└── _partials/ ├── average.html ├── breadcrumbs.html └── footer.html diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md index 3905ee15e..9bf1d5384 100644 --- a/docs/content/en/functions/partials/IncludeCached.md +++ b/docs/content/en/functions/partials/IncludeCached.md @@ -16,7 +16,7 @@ Without a [`return`] statement, the `partialCached` function returns a string of The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. > [!note] -> Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. +> 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. @@ -28,7 +28,7 @@ Here is the simplest usage: 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: -```go-html-template {file="layouts/_default/baseof.html"} +```go-html-template {file="layouts/baseof.html"} {{ partialCached "footer.html" . .Section }} ``` diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md index 4cd04f609..bd2d894b1 100644 --- a/docs/content/en/functions/resources/FromString.md +++ b/docs/content/en/functions/resources/FromString.md @@ -22,9 +22,9 @@ Let's say you need to publish a file named "site.json" in the root of your `publ ```json { - "build_date": "2025-01-16T19:14:41-08:00", - "hugo_version": "0.141.0", - "last_modified": "2025-01-16T19:14:46-08:00" + "build_date": "2025-05-03T19:14:41-08:00", + "hugo_version": "0.147.9", + "last_modified": "2025-05-03T19:14:46-08:00" } ``` 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" . }} diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md index a9f12c546..0beb8f56a 100644 --- a/docs/content/en/functions/transform/ToMath.md +++ b/docs/content/en/functions/transform/ToMath.md @@ -6,7 +6,7 @@ keywords: [] params: functions_and_methods: aliases: [] - returnType: types.Result[template.HTML] + returnType: template.HTML signatures: ['transform.ToMath INPUT [OPTIONS]'] aliases: [/functions/tomath] --- @@ -58,12 +58,25 @@ minRuleThickness : (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`. output -: (`string`). Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`. +: (`string`) Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`. With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template. ```html - <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet"> + <link href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" rel="stylesheet"> + +strict +: {{< new-in 0.147.6 />}} +: (`string`) Controls how KaTeX handles LaTeX features that offer convenience but aren't officially supported, one of `error`, `ignore`, or `warn`. Default is `error`. + + - `error`: Throws an error when convenient, unsupported LaTeX features are encountered. + - `ignore`: Allows convenient, unsupported LaTeX features without any feedback. + - `warn`: {{< new-in 0.147.7 />}} Emits a warning when convenient, unsupported LaTeX features are encountered. + +: The `newLineInDisplayMode` error code, which flags the use of `\\` +or `\newline` in display mode outside an array or tabular environment, is +intentionally designed not to throw an error, despite this behavior +being questionable. throwOnError : (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`. @@ -96,13 +109,13 @@ inline = [['\(', '\)']] {{< /code-toggle >}} > [!note] -> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. +> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. ### Step 2 Create a [passthrough render hook] to capture and render the LaTeX markup. -```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true} +```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true} {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} {{- with try (transform.ToMath .Inner $opts) }} {{- with .Err }} @@ -118,11 +131,11 @@ Create a [passthrough render hook] to capture and render the LaTeX markup. In your base template, conditionally include the KaTeX CSS within the head element. -```go-html-template {file="layouts/_default/baseof.html" copy=true} +```go-html-template {file="layouts/baseof.html" copy=true} <head> {{ $noop := .WordCount }} {{ if .Page.Store.Get "hasMath" }} - <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet"> + <link href="https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css" rel="stylesheet"> {{ end }} </head> ``` diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md index 93168294c..8b2173b9b 100644 --- a/docs/content/en/functions/transform/Unmarshal.md +++ b/docs/content/en/functions/transform/Unmarshal.md @@ -180,7 +180,7 @@ To render an HTML table from a CSV file: To extract a subset of the data, or to sort the data, unmarshal to a map instead of a slice: ```go-html-template -{{ $data := slice }} +{{ $data := dict }} {{ $file := "pets.csv" }} {{ with or (.Resources.Get $file) (resources.Get $file) }} {{ $opts := dict "targetType" "map" }} diff --git a/docs/content/en/functions/transform/XMLEscape.md b/docs/content/en/functions/transform/XMLEscape.md index 9e6c77927..372ad9b6a 100644 --- a/docs/content/en/functions/transform/XMLEscape.md +++ b/docs/content/en/functions/transform/XMLEscape.md @@ -31,7 +31,7 @@ For example: When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template: -```xml {file="layouts/_default/rss.xml"} +```xml {file="layouts/rss.xml"} <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description> ``` |