Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

docs/content/en/_common/functions/fmt/format-string.md

@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+The documentation for Go's [fmt] package describes the structure and content of the format string.
+
+[fmt]: https://pkg.go.dev/fmt

docs/content/en/_common/functions/go-html-template-package.md

@@ -0,0 +1,14 @@
+---
+_comment: Do not remove front matter.
+---
+
+Hugo uses Go's [text/template] and [html/template] packages.
+
+The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
+
+By default, Hugo uses the html/template package when rendering HTML files.
+
+To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts.
+
+[text/template]: https://pkg.go.dev/text/template
+[html/template]: https://pkg.go.dev/html/template

docs/content/en/_common/functions/go-template/text-template.md

@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+See Go's [text/template] documentation for more information.
+
+[text/template]: https://pkg.go.dev/text/template

docs/content/en/_common/functions/images/apply-image-filter.md

@@ -0,0 +1,27 @@
+---
+_comment: Do not remove front matter.
+---
+
+Apply the filter using the [`images.Filter`] function:
+
+[`images.Filter`]: /functions/images/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+  {{ with . | images.Filter $filter }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a `Resource` object:
+
+[`Filter`]: /methods/resource/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+  {{ with .Filter $filter }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
+```

docs/content/en/_common/functions/js/options.md

@@ -0,0 +1,108 @@
+---
+_comment: Do not remove front matter.
+---
+
+params
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
+
+  ```go-html-template
+  {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+  ```
+  And then in your JS file:
+
+  ```js
+  import * as params from '@params';
+  ```
+
+  Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
+
+minify
+: (`bool`) Whether to let `js.Build` handle the minification.
+
+loaders
+: {{< new-in 0.140.0 />}}
+: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`,  `css`,  `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`,  `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject.
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN  (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+  ```go-html-template
+  {{ $shims := dict "react" "js/shims/react.js"  "react-dom" "js/shims/react-dom.js" }}
+  {{ $js = $js | js.Build dict "shims" $shims }}
+  ```
+
+  The _shim_ files may look like these:
+
+  ```js
+  // js/shims/react.js
+  module.exports = window.React;
+  ```
+
+  ```js
+  // js/shims/react-dom.js
+  module.exports = window.ReactDOM;
+  ```
+
+  With the above, these imports should work in both scenarios:
+
+  ```js
+  import * as React from 'react';
+  import * as ReactDOM from 'react-dom/client';
+  ```
+
+target
+: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
+
+platform
+: {{< new-in 0.140.0 />}}
+: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external.
+
+defines
+: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
+
+  ```go-html-template
+  {{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+  ```
+
+drop
+: {{< new-in 0.144.0 />}}
+: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
+: See https://esbuild.github.io/api/#drop
+
+sourceMap
+: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
+
+sourcesContent
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
+
+JSX
+: {{< new-in 0.124.0 />}}
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx.
+
+JSXImportSource
+: {{< new-in 0.124.0 />}}
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source.
+
+  The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+  ```go-html-template
+  {{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+  ```
+
+  With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+  ```jsx
+  import { render } from 'preact';
+
+  const App = () => <>Hello world!</>;
+
+  const container = document.getElementById('app');
+  if (container) render(<App />, container);
+  ```

docs/content/en/_common/functions/locales.md

@@ -0,0 +1,8 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!note]
+> Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
+
+[gohugoio/locales]: https://github.com/gohugoio/locales

docs/content/en/_common/functions/regular-expressions.md

@@ -0,0 +1,12 @@
+---
+_comment: Do not remove front matter.
+---
+
+When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
+
+Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported.
+
+[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
+[PCRE]: https://www.pcre.org/
+[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/
+[string literal]: https://go.dev/ref/spec#String_literals

docs/content/en/_common/functions/truthy-falsy.md

@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+
+Everything else is truthy.

docs/content/en/_common/functions/urls/anchorize-vs-urlize.md

@@ -0,0 +1,35 @@
+---
+_comment: Do not remove front matter.
+---
+
+The [`anchorize`] and [`urlize`] functions are similar:
+
+[`anchorize`]: /functions/urls/anchorize/
+[`urlize`]: /functions/urls/urlize/
+
+- Use the `anchorize` function to generate an HTML `id` attribute value
+- Use the `urlize` function to sanitize a string for usage in a URL
+
+For example:
+
+```go-html-template
+{{ $s := "A B C" }}
+{{ $s | anchorize }} → a-b-c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "a b   c" }}
+{{ $s | anchorize }} → a-b---c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "< a, b, & c >" }}
+{{ $s | anchorize }} → -a-b--c-
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "main.go" }}
+{{ $s | anchorize }} → maingo
+{{ $s | urlize }} → main.go
+
+{{ $s := "Hugö" }}
+{{ $s | anchorize }} → hugö
+{{ $s | urlize }} → hug%C3%B6
+```