content: Miscellaneous updates related to v0.146.0

This commit is contained in:
Joe Mooring
2025-03-09 23:36:52 -07:00
committed by Bjørn Erik Pedersen
parent 0a906ad491
commit 195b368e86
11 changed files with 281 additions and 128 deletions
+1 -1
View File
@@ -249,7 +249,7 @@ HUGO_FILE_LOG_FORMAT
HUGO_MEMORYLIMIT
: {{< new-in 0.123.0 />}}
: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that The `HUGO_MEMORYLIMIT` is a best effort setting. Don't expect Hugo to build a million pages with only 1 GB memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
HUGO_NUMWORKERMULTIPLIER
: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
+59 -89
View File
@@ -12,13 +12,66 @@ params:
{{< new-in 0.128.0 />}}
```go-html-template
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, 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
enableSourceMap
: (`bool`) Whether to generate a source map. Default is `false`.
includePaths
: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
outputStyle
: (`string`) The output style of the resulting CSS. With LibSass, one of `nested` (default), `expanded`, `compact`, or `compressed`. With Dart Sass, either `expanded` (default) or `compressed`.
precision
: (`int`) The precision of floating point math. Applicable to LibSass. Default is `8`.
silenceDeprecations
: {{< new-in 0.139.0 />}}
: (`slice`) A slice of deprecation IDs to silence. IDs are enclosed in brackets within Dart Sass warning messages (e.g., `import` in `WARN Dart Sass: DEPRECATED [import]`). Applicable to Dart Sass. Default is `false`.
silenceDependencyDeprecations
: {{< new-in 0.146.0 />}}
: (`bool`) Whether to silence deprecation warnings from dependencies, where a dependency is considered any file transitively imported through a load path. This does not apply to `@warn` or `@debug` rules.Default is `false`.
sourceMapIncludeSources
: (`bool`) Whether to embed sources in the generated source map. Applicable to Dart Sass. Default is `false`.
targetPath
: (`string`) The publish path for the transformed resource, relative to the[`publishDir`]. If unset, the target path defaults to the asset's original path with a `.css` extension.
transpiler
: (`string`) The transpiler to use, either `libsass` or `dartsass`. Hugo's extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass). Default is `libsass`.
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;
```
## Example
```go-html-template {copy=true}
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict
"enableSourceMap" (not hugo.IsProduction)
"outputStyle" (cond hugo.IsProduction "compressed" "expanded")
"targetPath" "css/main.css"
"transpiler" "libsass"
"transpiler" "dartsass"
"vars" site.Params.styles
"includePaths" (slice "node_modules/bootstrap/scss")
}}
{{ with . | toCSS $opts }}
{{ if hugo.IsProduction }}
@@ -32,63 +85,6 @@ params:
{{ end }}
```
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, 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 and extended/deploy editions include 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`) Whether to generate a source map. Default is `false`.
sourceMapIncludeSources
: (`bool`) Whether to embed sources in the generated source map. Not applicable to LibSass. Default is `false`.
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 }}
```
silenceDeprecations
: (`slice`) {{< new-in 0.139.0 />}} A slice of deprecation IDs to silence. The deprecation IDs are printed to in the warning message, e.g "import" in `WARN Dart Sass: DEPRECATED [import] ...`. This is for Dart Sass only.
## Dart Sass
Hugo's extended and extended/deploy editions include [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].
@@ -121,6 +117,9 @@ You may also install [prebuilt binaries] for Linux, macOS, and Windows.
Run `hugo env` to list the active transpilers.
> [!note]
> 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.
### Installing in a production environment
For [CI/CD](g) 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.
@@ -136,8 +135,6 @@ To install Dart Sass for your builds on GitHub Pages, add this step to the GitHu
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:
@@ -194,34 +191,6 @@ command = """\
"""
```
### Example
To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `css.Sass`. For example:
```go-html-template
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict
"enableSourceMap" (not hugo.IsProduction)
"outputStyle" (cond hugo.IsProduction "compressed" "expanded")
"targetPath" "css/main.css"
"transpiler" "dartsass"
}}
{{ with . | toCSS $opts }}
{{ if hugo.IsProduction }}
{{ with . | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ else }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ 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
[dart sass]: https://sass-lang.com/dart-sass
@@ -232,3 +201,4 @@ If you build Hugo from source and run `mage test -v`, the test will fail if you
[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
[`publishDir`]: /configuration/all/#publishdir
+127
View File
@@ -0,0 +1,127 @@
---
title: templates.Current
description: Returns information about the currently executing template.
categories: []
keywords: []
params:
functions_and_methods:
aliases: []
returnType: tpl.CurrentTemplateInfo
signatures: [templates.Current]
---
> [!note]
> This function is experimental and subject to change.
{{< new-in 0.146.0 />}}
The `templates.Current` function provides introspection capabilities, allowing you to access details about the currently executing templates. This is useful for debugging complex template hierarchies and understanding the flow of execution during rendering.
## Methods
Ancestors
: (`tpl.CurrentTemplateInfos`) Returns a slice containing information about each template in the current execution chain, starting from the parent of the current template and going up towards the initial template called. It excludes any base template applied via `define` and `block`. You can chain the `Reverse` method to this result to get the slice in chronological execution order.
Base
: (`tplimpl.TemplInfo`) Returns an object representing the base template that was applied to the current template, if any. This may be `nil`.
Filename
: (`string`) Returns the absolute path of the current template. This will be empty for embedded templates.
Name
: (`string`) Returns the path of the current template, relative to the `layouts` directory.
Parent
: (`tpl.CurrentTemplateInfo`) Returns an object representing the parent of the current template, if any. This may be `nil`.
## Examples
The examples below help visualize template execution and require a `debug` parameter set to `true` in your site configuration:
{{< code-toggle file=hugo >}}
[params]
debug = true
{{< /code-toggle >}}
### Template boundaries
To visually mark where a template begins and ends execution:
```go-html-template {file="layouts/_default/single.html"}
{{ define "main" }}
{{ if site.Params.debug }}
<div class="debug">[entering {{ templates.Current.Filename }}]</div>
{{ end }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ if site.Params.debug }}
<div class="debug">[leaving {{ templates.Current.Filename }}]</div>
{{ end }}
{{ end }}
```
### Template call stack
To show 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/render-template-stack.html" copy=true}
<div class="debug">
{{ with templates.Current }}
{{ range .Ancestors }}
{{ .Filename }}<br>
{{ with .Base }}
{{ .Filename }}<br>
{{ end }}
{{ end }}
{{ end }}
</div>
```
Then call the partial from any template:
```go-html-template {file="layouts/partials/footer/copyright.html" copy=true}
{{ if site.Params.debug }}
{{ partial "render-template-stack.html" . }}
{{ end }}
```
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/themes/foo/layouts/_default/single.html
/home/user/project/themes/foo/layouts/_default/baseof.html
```
To reverse the order of the entries chain the `Reverse` method to the `Ancestors` method:
```go-html-template {file="layouts/partials/render-template-stack.html" copy=true}
<div class="debug">
{{ with templates.Current }}
{{ range .Ancestors.Reverse }}
{{ with .Base }}
{{ .Filename }}<br>
{{ end }}
{{ .Filename }}<br>
{{ end }}
{{ end }}
</div>
```
To render each entry as an anchor element that, when clicked, will open the template in VS Code:
```go-html-template {file="layouts/partials/render-template-stack.html" copy=true}
<div class="debug">
{{ with templates.Current }}
{{ range .Ancestors }}
<a href="vscode://file/{{ .Filename }}">{{ .Filename }}</a><br>
{{ with .Base }}
<a href="vscode://file/{{ .Filename }}">{{ .Filename }}</a><br>
{{ end }}
{{ end }}
{{ end }}
</div>
```
+30
View File
@@ -0,0 +1,30 @@
---
title: time.In
description: Returns the given date/time as represented in the specified IANA time zone.
categories: []
keywords: []
params:
functions_and_methods:
aliases: []
returnType: time.Time
signatures: [time.In TIMEZONE INPUT]
---
{{< new-in 0.146.0 />}}
The `time.In` function returns the given date/time as represented in the specified [IANA](g) time zone.
- If the time zone is an empty string or `UTC`, the time is returned in [UTC](g).
- If the time zone is `Local`, the time is returned in the system's local time zone.
- Otherwise, the time zone must be a valid IANA [time zone name].
[time zone name]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
```go-html-template
{{ $layout := "2006-01-02T15:04:05-07:00" }}
{{ $t := time.AsTime "2025-03-31T14:45:00-00:00" }}
{{ $t | time.In "America/Denver" | time.Format $layout }} → 2025-03-31T08:45:00-06:00
{{ $t | time.In "Australia/Adelaide" | time.Format $layout }} → 2025-04-01T01:15:00+10:30
{{ $t | time.In "Europe/Oslo" | time.Format $layout }} → 2025-03-31T16:45:00+02:00
```
+2 -1
View File
@@ -23,7 +23,8 @@
"dates" $dates
"kind" "page"
"params" $params
"path" .name
"path" (strings.Replace .name "." "-")
"slug" .name
"title" (printf "Release %s" .name)
}}
{{ $.AddPage $page }}
@@ -0,0 +1,6 @@
---
title: IANA
reference: https://www.iana.org/about
---
_IANA_ is an abbreviation for the Internet Assigned Numbers Authority, a non-profit organization that manages the allocation of global IP addresses, autonomous system numbers, DNS root zone, media types, and other Internet Protocol-related resources.
@@ -0,0 +1,6 @@
---
title: UTC
reference: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
---
_UTC_ is an abbreviation for Coordinated Universal Time, the primary time standard used worldwide to regulate clocks and time. It is the basis for civil time and time zones across the globe.
+12 -4
View File
@@ -29,19 +29,27 @@ Hugo renders this to:
## Arguments
id
: (string) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
allowFullScreen
: {{< new-in 0.146.0 />}}
: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
class
: (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling.
id
: (`string`) The `id` of the Vimeo video
loading
: {{< new-in 0.146.0 />}}
: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
title
: (`string`) The `title` attribute of the `iframe` element.
If you provide a `class` or `title` you must use a named parameter for the `id`.
Here's an example using some of the available arguments:
```text
{{</* vimeo id=55073825 class="foo bar" title="My Video" */>}}
{{</* vimeo id=55073825 allowFullScreen=false loading=lazy */>}}
```
## Privacy
+1 -1
View File
@@ -70,7 +70,7 @@ start
title
: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
Example using some of the above:
Here's an example using some of the available arguments:
```text
{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
+5
View File
@@ -34,6 +34,11 @@ Use the [`printf`] function (render) or [`warnf`] function (log to console) to i
{{ printf "%[1]v (%[1]T)" $value }} → 42 (int)
```
{{< new-in 0.146.0 />}}
Use the [`templates.Current`] function to visually mark template execution boundaries or to display the template call stack.
[`debug.Dump`]: /functions/debug/dump/
[`printf`]: /functions/fmt/printf/
[`warnf`]: /functions/fmt/warnf/
[`templates.Current`]: /functions/templates/current/
+32 -32
View File
@@ -4,39 +4,39 @@
# BaseURL
'base_url' = 'https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates'
# Templates
'alias' = 'alias.html'
'disqus' = 'disqus.html'
'google_analytics' = 'google_analytics.html'
'opengraph' = 'opengraph.html'
'pagination' = 'pagination.html'
'robots' = '_default/robots.txt'
'rss' = '_default/rss.xml'
'schema' = 'schema.html'
'sitemap' = '_default/sitemap.xml'
'sitemapindex' = '_default/sitemapindex.xml'
'twitter_cards' = 'twitter_cards.html'
# Partials
'disqus' = '_partials/disqus.html'
'google_analytics' = '_partials/google_analytics.html'
'opengraph' = '_partials/opengraph.html'
'pagination' = '_partials/pagination.html'
'schema' = '_partials/schema.html'
'twitter_cards' = '_partials/twitter_cards.html'
# Render hooks
'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
'render-image' = '_default/_markup/render-image.html'
'render-link' = '_default/_markup/render-link.html'
'render-table' = '_default/_markup/render-table.html'
'render-codeblock-goat' = '_markup/render-codeblock-goat.html'
'render-image' = '_markup/render-image.html'
'render-link' = '_markup/render-link.html'
'render-table' = '_markup/render-table.html'
# Shortcodes
'details' = 'shortcodes/details.html'
'figure' = 'shortcodes/figure.html'
'gist' = 'shortcodes/gist.html'
'highlight' = 'shortcodes/highlight.html'
'instagram' = 'shortcodes/instagram.html'
'param' = 'shortcodes/param.html'
'qr' = 'shortcodes/qr.html'
'ref' = 'shortcodes/ref.html'
'relref' = 'shortcodes/relref.html'
'twitter' = 'shortcodes/twitter.html'
'twitter_simple' = 'shortcodes/twitter_simple.html'
'vimeo' = 'shortcodes/vimeo.html'
'vimeo_simple' = 'shortcodes/vimeo_simple.html'
'x' = 'shortcodes/x.html'
'x_simple' = 'shortcodes/x_simple.html'
'youtube' = 'shortcodes/youtube.html'
'details' = '_shortcodes/details.html'
'figure' = '_shortcodes/figure.html'
'gist' = '_shortcodes/gist.html'
'highlight' = '_shortcodes/highlight.html'
'instagram' = '_shortcodes/instagram.html'
'param' = '_shortcodes/param.html'
'qr' = '_shortcodes/qr.html'
'ref' = '_shortcodes/ref.html'
'relref' = '_shortcodes/relref.html'
'vimeo' = '_shortcodes/vimeo.html'
'vimeo_simple' = '_shortcodes/vimeo_simple.html'
'x' = '_shortcodes/x.html'
'x_simple' = '_shortcodes/x_simple.html'
'youtube' = '_shortcodes/youtube.html'
# Other
'alias' = 'alias.html'
'robots' = 'robots.txt'
'rss' = 'rss.xml'
'sitemap' = 'sitemap.xml'
'sitemapindex' = 'sitemapindex.xml'