mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/content/en/functions/resources/Babel.md
View File

@@ -3,15 +3,16 @@ title: resources.Babel
description: Compiles the given JavaScript resource with Babel.
categories: []
keywords: []
action:
related: []
returnType: resource.Resource
signatures: ['resources.Babel [OPTIONS] RESOURCE']
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: ['resources.Babel [OPTIONS] RESOURCE']
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
---
{{% deprecated-in 0.128.0 %}}
{{< deprecated-in 0.128.0 >}}
Use [`js.Babel`] instead.
[`js.Babel`]: /functions/js/babel/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

25
docs/content/en/functions/resources/ByType.md
View File

@@ -3,16 +3,11 @@ title: resources.ByType
description: Returns a collection of global resources of the given media type, or nil if none found.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/Get
- functions/resources/GetMatch
- functions/resources/GetRemote
- functions/resources/Match
- methods/page/Resources
returnType: resource.Resources
signatures: [resources.ByType MEDIATYPE]
params:
functions_and_methods:
aliases: []
returnType: resource.Resources
signatures: [resources.ByType MEDIATYPE]
---
The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`.
@@ -23,12 +18,10 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl
{{ end }}
```
{{% note %}}
This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.ByType`] method on a `Page` object.
> [!note]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
> For page resources, use the [`Resources.ByType`] method on a `Page` object.
[`Resources.ByType`]: /methods/page/resources/
{{% /note %}}
[media type]: https://en.wikipedia.org/wiki/Media_type

10
docs/content/en/functions/resources/Concat.md
View File

@@ -3,11 +3,11 @@ title: resources.Concat
description: Returns a concatenated slice of resources.
categories: []
keywords: []
action:
aliases: []
related: []
returnType: resource.Resource
signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
---
The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].

15
docs/content/en/functions/resources/Copy.md
View File

@@ -2,11 +2,11 @@
title: resources.Copy
description: Copies the given resource to the target path.
categories: []
action:
aliases: []
related: []
returnType: resource.Resource
signatures: [resources.Copy TARGETPATH RESOURCE]
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: [resources.Copy TARGETPATH RESOURCE]
---
```go-html-template
@@ -23,6 +23,5 @@ The relative URL of the new published resource will be:
/img/new-image-name.jpg
```
{{% note %}}
Use the `resources.Copy` function with global, page, and remote resources.
{{% /note %}}
> [!note]
> Use the `resources.Copy` function with global, page, and remote resources.

27
docs/content/en/functions/resources/ExecuteAsTemplate.md
View File

@@ -3,30 +3,25 @@ title: resources.ExecuteAsTemplate
description: Returns a resource created from a Go template, parsed and executed with the given context.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/FromString
returnType: resource.Resource
signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE]
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE]
---
The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key.
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
[`publish`]: /methods/resource/publish/
[`permalink`]: /methods/resource/permalink/
[`relpermalink`]: /methods/resource/relpermalink/
Let's say you have a CSS file that you wish to populate with values from your site configuration:
{{< code file=assets/css/template.css lang=go-html-template >}}
```go-html-template {file="assets/css/template.css"}
body {
background-color: {{ site.Params.style.bg_color }};
color: {{ site.Params.style.text_color }};
}
{{< /code >}}
```
And your site configuration contains:
@@ -54,9 +49,13 @@ The example above:
The result is:
{{< code file=public/css/main.css >}}
```css {file="public/css/main.css"}
body {
background-color: #fefefe;
color: #222;
}
{{< /code >}}
```
[`publish`]: /methods/resource/publish/
[`permalink`]: /methods/resource/permalink/
[`relpermalink`]: /methods/resource/relpermalink/

15
docs/content/en/functions/resources/Fingerprint.md
View File

@@ -3,16 +3,11 @@ title: resources.Fingerprint
description: Cryptographically hashes the content of the given resource.
categories: []
keywords: []
action:
aliases: [fingerprint]
related:
- functions/resources/Minify
- functions/css/Sass
- functions/css/TailwindCSS
- functions/js/Build
- functions/js/Babel
returnType: resource.Resource
signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE']
params:
functions_and_methods:
aliases: [fingerprint]
returnType: resource.Resource
signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE']
---
```go-html-template

11
docs/content/en/functions/resources/FromString.md
View File

@@ -3,12 +3,11 @@ title: resources.FromString
description: Returns a resource created from a string.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/ExecuteAsTemplate
returnType: resource.Resource
signatures: [resources.FromString TARGETPATH STRING]
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: [resources.FromString TARGETPATH STRING]
---
The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.

24
docs/content/en/functions/resources/Get.md
View File

@@ -3,16 +3,11 @@ title: resources.Get
description: Returns a global resource from the given path, or nil if none found.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/ByType
- functions/resources/GetMatch
- functions/resources/GetRemote
- functions/resources/Match
- methods/page/Resources
returnType: resource.Resource
signatures: [resources.Get PATH]
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: [resources.Get PATH]
---
```go-html-template
@@ -21,10 +16,9 @@ action:
{{ end }}
```
{{% note %}}
This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.Get`] method on a `Page` object.
> [!note]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
> For page resources, use the [`Resources.Get`] method on a `Page` object.
[`Resources.Get`]: /methods/page/resources/
{{% /note %}}

32
docs/content/en/functions/resources/GetMatch.md
View File

@@ -3,16 +3,11 @@ title: resources.GetMatch
description: Returns the first global resource from paths matching the given glob pattern, or nil if none found.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/ByType
- functions/resources/Get
- functions/resources/GetRemote
- functions/resources/Match
- methods/page/Resources
returnType: resource.Resource
signatures: [resources.GetMatch PATTERN]
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: [resources.GetMatch PATTERN]
---
```go-html-template
@@ -21,16 +16,13 @@ action:
{{ end }}
```
{{% note %}}
This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
> [!note]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
> For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
Hugo determines a match using a case-insensitive [glob](g) pattern.
{{% include "/_common/glob-patterns.md" %}}
[`Resources.GetMatch`]: /methods/page/resources/
{{% /note %}}
Hugo determines a match using a case-insensitive [glob pattern].
{{% include "functions/_common/glob-patterns.md" %}}
[glob pattern]: https://github.com/gobwas/glob#example

51
docs/content/en/functions/resources/GetRemote.md
View File

@@ -3,19 +3,11 @@ title: resources.GetRemote
description: Returns a remote resource from the given URL, or nil if none found.
categories: []
keywords: []
action:
aliases: []
related:
- functions/data/GetCSV
- functions/data/GetJSON
- functions/resources/ByType
- functions/resources/Get
- functions/resources/GetMatch
- functions/resources/Match
- methods/page/Resources
returnType: resource.Resource
signatures: ['resources.GetRemote URL [OPTIONS]']
toc: true
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: ['resources.GetRemote URL [OPTIONS]']
---
{{< new-in 0.141.0 >}}
@@ -69,11 +61,10 @@ The `resources.GetRemote` function takes an optional map of options.
## Options examples
{{% note %}}
For brevity, the examples below do not include [error handling].
> [!note]
> For brevity, the examples below do not include [error handling].
[error handling]: #error-handling
{{% /note %}}
To include a header:
@@ -148,15 +139,12 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars
{{ end }}
```
{{% note %}}
When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
`{{ $data = .Content | transform.Unmarshal }}`
[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
{{% /note %}}
> [!note]
> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
>
> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
>
> `{{ $data = .Content | transform.Unmarshal }}`
## Error handling
@@ -164,9 +152,8 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t
[`try`]: /functions/go-template/try
{{% note %}}
Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
{{% /note %}}
> [!note]
> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
```go-html-template
{{ $url := "https://broken-example.org/images/a.jpg" }}
@@ -206,9 +193,7 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function
Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any.
Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
@@ -217,7 +202,7 @@ Override the cache key by setting a `key` in the options map. Use this approach
{{ $resource := resources.GetRemote $url $opts }}
```
[configure file caches]: /getting-started/configuration/#configure-file-caches
[configure file caches]: /configuration/caches/
## Security
@@ -245,7 +230,7 @@ mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
Note that the entry above is:
- An _addition_ to the allowlist; it does not _replace_ the allowlist
- An array of regular expressions
- An array of [regular expressions](g)
[allowlist]: https://en.wikipedia.org/wiki/Whitelist
[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type

29
docs/content/en/functions/resources/Match.md
View File

@@ -3,16 +3,11 @@ title: resources.Match
description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found.
categories: []
keywords: []
action:
aliases: []
related:
- functions/resources/ByType
- functions/resources/Get
- functions/resources/GetMatch
- functions/resources/GetRemote
- methods/page/Resources
returnType: resource.Resources
signatures: [resources.Match PATTERN]
params:
functions_and_methods:
aliases: []
returnType: resource.Resources
signatures: [resources.Match PATTERN]
---
```go-html-template
@@ -21,16 +16,14 @@ action:
{{ end }}
```
{{% note %}}
This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.Match`] method on a `Page` object.
[`Resources.Match`]: /methods/page/resources/
{{% /note %}}
> [!note]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
> For page resources, use the [`Resources.Match`] method on a `Page` object.
Hugo determines a match using a case-insensitive [glob pattern].
{{% include "functions/_common/glob-patterns.md" %}}
{{% include "/_common/glob-patterns.md" %}}
[`Resources.Match`]: /methods/page/resources/
[glob pattern]: https://github.com/gobwas/glob#example

15
docs/content/en/functions/resources/Minify.md
View File

@@ -3,16 +3,11 @@ title: resources.Minify
description: Minifies the given resource.
categories: []
keywords: []
action:
aliases: [minify]
related:
- functions/resources/Fingerprint
- functions/css/Sass
- functions/css/TailwindCSS
- functions/js/Build
- functions/js/Babel
returnType: resource.Resource
signatures: [resources.Minify RESOURCE]
params:
functions_and_methods:
aliases: [minify]
returnType: resource.Resource
signatures: [resources.Minify RESOURCE]
---
```go-html-template

13
docs/content/en/functions/resources/PostCSS.md
View File

@@ -3,15 +3,16 @@ title: resources.PostCSS
description: Processes the given resource with PostCSS using any PostCSS plugin.
categories: []
keywords: []
action:
related: []
returnType: resource.Resource
signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
---
{{% deprecated-in 0.128.0 %}}
{{< deprecated-in 0.128.0 >}}
Use [`css.PostCSS`] instead.
[`css.PostCSS`]: /functions/css/postcss/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

51
docs/content/en/functions/resources/PostProcess.md
View File

@@ -3,14 +3,11 @@ title: resources.PostProcess
description: Processes the given resource after the build.
categories: []
keywords: []
action:
aliases: []
related:
- functions/css/PostCSS
- functions/css/Sass
returnType: postpub.PostPublishedResource
signatures: [resources.PostProcess RESOURCE]
toc: true
params:
functions_and_methods:
aliases: []
returnType: postpub.PostPublishedResource
signatures: [resources.PostProcess RESOURCE]
---
The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
@@ -22,19 +19,11 @@ In this example, after the build is complete, Hugo will:
1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
3. [Minify] the CSS
4. [Fingerprint] the CSS
[autoprefixer]: https://github.com/postcss/autoprefixer
[fingerprint]: /functions/resources/fingerprint/
[minify]: /functions/resources/minify/
[postcss]: /functions/css/postcss/
[purgecss]: https://purgecss.com/plugins/postcss.html
4. [Fingerprint] the CSS
Step 1
: Install [Node.js].
[node.js]: https://nodejs.org/en/download
Step 2
: Install the required Node.js packages in the root of your project:
@@ -45,8 +34,6 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
Step 3
: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
[`config/production`]: /getting-started/configuration/#configuration-directory
{{< code-toggle file=hugo >}}
[build.buildStats]
enable = true
@@ -54,12 +41,10 @@ enable = true
See the [configure build] documentation for details and options.
[configure build]: /getting-started/configuration/#configure-build
Step 4
: Create a PostCSS configuration file in the root of your project.
{{< code file="postcss.config.js" copy=true >}}
```js {file="postcss.config.js" copy=true}
const autoprefixer = require('autoprefixer');
const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
@@ -83,11 +68,10 @@ module.exports = {
autoprefixer,
]
};
{{< /code >}}
```
{{% note %}}
{{% include "functions/resources/_common/postcss-windows-warning.md" %}}
{{% /note %}}
> [!note]
> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
Step 5
: Place your CSS file within the `assets/css` directory.
@@ -132,7 +116,7 @@ HUGO_FILE_X
- `postcss.config.js`
- `tailwind.config.js`
For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example:
For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example:
```js
let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
@@ -144,10 +128,21 @@ Do not use `resources.PostProcess` when running Hugo's built-in development serv
The `resources.PostProcess` function only works within templates that produce HTML files.
You cannot manipulate the values returned from the resource’s methods. For example, the `strings.ToUpper` function in this example will not work as expected:
You cannot manipulate the values returned from the resource's methods. For example, the `strings.ToUpper` function in this example will not work as expected:
```go-html-template
{{ $css := resources.Get "css/main.css" }}
{{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
{{ $css.RelPermalink | strings.ToUpper }}
```
[#7333]: https://github.com/gohugoio/hugo/issues/7333
[`config/production`]: /configuration/introduction/#configuration-directory
[Autoprefixer]: https://github.com/postcss/autoprefixer
[configure build]: /configuration/build/
[Fingerprint]: /functions/resources/fingerprint/
[Minify]: /functions/resources/minify/
[Node.js]: https://nodejs.org/en
[PostCSS]: https://postcss.org/
[PurgeCSS]: https://github.com/FullHuman/purgecss
[this example]: https://github.com/postcss/postcss-load-config#packagejson

13
docs/content/en/functions/resources/ToCSS.md
View File

@@ -3,15 +3,16 @@ title: resources.ToCSS
description: Transpiles Sass to CSS.
categories: []
keywords: []
action:
related: []
returnType: resource.Resource
signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
params:
functions_and_methods:
aliases: []
returnType: resource.Resource
signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
---
{{% deprecated-in 0.128.0 %}}
{{< deprecated-in 0.128.0 >}}
Use [`css.Sass`] instead.
[`css.Sass`]: /functions/css/sass/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

12
docs/content/en/functions/resources/_common/_index.md
View File

@@ -1,12 +0,0 @@
---
_build:
list: never
publishResources: false
render: never
---
<!--
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->

8
docs/content/en/functions/resources/_common/postcss-windows-warning.md
View File

@@ -1,8 +0,0 @@
---
_comment: Do not remove front matter.
---
If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
[this example]: https://github.com/postcss/postcss-load-config#packagejson
[#7333]: https://github.com/gohugoio/hugo/issues/7333

7
docs/content/en/functions/resources/_index.md
View File

@@ -1,12 +1,7 @@
---
title: Resource functions
linkTitle: resources
description: Template functions to work with resources.
description: Use these functions to work with resources.
categories: []
keywords: []
menu:
docs:
parent: functions
---
Use these functions to work with resources.