diff --git a/docs/.codespellrc b/docs/.codespellrc index f322b0123..8f82b8749 100644 --- a/docs/.codespellrc +++ b/docs/.codespellrc @@ -4,7 +4,7 @@ [codespell] # Comma separated list of dirs to be skipped. -skip = *.ai,chroma.css,chroma_dark.css,.cspell.json +skip = *.ai,chroma.css,chroma_dark.css,.cspell.json,./data/docs.yaml # Comma separated list of words to be ignored. Words must be lowercased. ignore-words-list = abl,edn,januar,te,trys,ue,womens diff --git a/docs/.cspell.json b/docs/.cspell.json index c41b857fd..8adfc51dd 100644 --- a/docs/.cspell.json +++ b/docs/.cspell.json @@ -23,8 +23,7 @@ "**/emojis.md", "**/commands/*", "**/showcase/*", - "**/tools/*", - "data/docs.yaml" + "**/tools/*" ], "ignoreRegExpList": [ "# cspell: ignore fenced code blocks", @@ -182,6 +181,7 @@ "dring", "fleqn", "inor", + "iptc", "jausten", "jdoe", "jsmith", diff --git a/docs/.gitignore b/docs/.gitignore index 5208c5c3a..a1788816b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,6 @@ .DS_Store .hugo_build.lock +.hvm /.idea /.vscode /dist diff --git a/docs/.markdownlint-cli2.yaml b/docs/.markdownlint-cli2.yaml index c8f5b7bd3..68c28a3d0 100644 --- a/docs/.markdownlint-cli2.yaml +++ b/docs/.markdownlint-cli2.yaml @@ -80,7 +80,7 @@ config: url_inline: false MD055: style: consistent - MD056: true + MD056: false # interferes with Markdown attributes # MD057 deprecated MD058: true MD059: @@ -89,3 +89,6 @@ config: - here - link - more + MD060: + aligned_delimiter: false + style: any diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 000000000..7524fd477 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,25 @@ +## Theme + +### Role +You are an expert front-end and Tailwind CSS developer. Your primary goal is to build reliable, readable, and scalable user interfaces using the existing project structure and design system. + +### Directives +* **ALWAYS** use existing Tailwind utility classes for styling. +* **NEVER** write raw CSS in `.css` files unless absolutely necessary for a non-utility-based global reset. +* **NEVER** use inline styles (e.g., `
`). + +### Project Knowledge + +* **Tech Stack:** Hugo (static site generator), AlpineJS, Tailwind CSS. Icons from https://heroicons.com/. +* **Core Files and Directories:** + - `hugo.toml`: Hugo configuration file. + - `assets/css/styles.css`: Main CSS file with Tailwind directives. + - `assets/js/main.js`: Main JavaScript with AlpineJS configuration. + - `package.json`: Project dependencies and scripts. + - `content/`: Directory for markdown content files. + - `layouts/`: Directory for Hugo templates and partials. + - `layouts/_partials/icons.html`: SVG icon sprites. + + + + diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 000000000..eef4bd20c --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 58d0e748c..06b952d17 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,5 +23,3 @@ Please see the [contributing] section for guidelines, examples, and process. npm i hugo server ``` - -**Note:** We're working on removing the need to run `npm i` for local development. Stay tuned. diff --git a/docs/assets/css/styles.css b/docs/assets/css/styles.css index 05304a93b..6734e9a30 100644 --- a/docs/assets/css/styles.css +++ b/docs/assets/css/styles.css @@ -77,8 +77,9 @@ /* Fonts. */ --font-sans: - "Mulish", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", - "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; + "Mulish", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", + Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", + "Segoe UI Symbol", "Noto Color Emoji"; } html { @@ -134,3 +135,9 @@ body { :not(pre) > code { white-space: nowrap; } + +/* Utility class for tables to prevent word wrapping in the first column. */ +.no-wrap-first-col td:first-child, +.no-wrap-first-col th:first-child { + white-space: nowrap; +} diff --git a/docs/assets/js/alpinejs/stores/nav.js b/docs/assets/js/alpinejs/stores/nav.js index 6409cd86c..1dad17c8d 100644 --- a/docs/assets/js/alpinejs/stores/nav.js +++ b/docs/assets/js/alpinejs/stores/nav.js @@ -31,6 +31,16 @@ export const navStore = (Alpine) => ({ atTop: true, }, + mobileMenu: { + open: false, + toggle() { + this.open = !this.open; + }, + close() { + this.open = false; + }, + }, + userSettings: { // settings gets persisted between page navigations. settings: Alpine.$persist({ diff --git a/docs/content/en/_common/functions/js/options.md b/docs/content/en/_common/functions/js/options.md index 0c82fcae5..077775dcb 100644 --- a/docs/content/en/_common/functions/js/options.md +++ b/docs/content/en/_common/functions/js/options.md @@ -84,11 +84,9 @@ sourcesContent : (`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 . 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 . The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.: diff --git a/docs/content/en/_common/installation/01-editions.md b/docs/content/en/_common/installation/01-editions.md index 634002822..b68c89975 100644 --- a/docs/content/en/_common/installation/01-editions.md +++ b/docs/content/en/_common/installation/01-editions.md @@ -2,15 +2,17 @@ _comment: Do not remove front matter. --- -Hugo is available in three editions: standard, extended, and extended/deploy. While the standard edition provides core functionality, the extended and extended/deploy editions offer advanced features. +## Editions + +Hugo offers a standard edition with core features, plus extended and extended/deploy editions with more. Use the standard edition unless you need the features below. + + Feature|extended edition|extended/deploy edition :--|:-:|:-: -Encode to the WebP format when [processing images]. You can decode WebP images with any edition.|:heavy_check_mark:|:heavy_check_mark: -[Transpile Sass to CSS] using the embedded LibSass transpiler. You can use the [Dart Sass] transpiler with any edition.|:heavy_check_mark:|:heavy_check_mark: +[Transpile Sass to CSS] via embedded LibSass. Note that embedded LibSass was deprecated in v0.153.0 and will be removed in a future release. Use the [Dart Sass] transpiler instead, which is compatible with any edition.|:heavy_check_mark:|:heavy_check_mark: Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details].|:x:|:heavy_check_mark: [dart sass]: /functions/css/sass/#dart-sass -[processing images]: /content-management/image-processing/ [transpile sass to css]: /functions/css/sass/ [details]: /host-and-deploy/deploy-with-hugo-deploy/ diff --git a/docs/content/en/_common/installation/02-prerequisites.md b/docs/content/en/_common/installation/02-prerequisites.md index 2a0b1ac09..293645dda 100644 --- a/docs/content/en/_common/installation/02-prerequisites.md +++ b/docs/content/en/_common/installation/02-prerequisites.md @@ -12,7 +12,7 @@ Git is required to: - Use the [Hugo Modules] feature - Install a theme as a Git submodule - Access [commit information] from a local Git repository -- Host your site with services such as [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify] +- Host your site on [CI/CD](g) platforms such as [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], or [Vercel][] Go is required to: @@ -27,16 +27,17 @@ Please refer to the relevant documentation for installation instructions: - [Go][go install] - [Dart Sass][dart sass install] -[cloudcannon]: https://cloudcannon.com/ -[cloudflare pages]: https://pages.cloudflare.com/ +[Cloudflare]: /host-and-deploy/host-on-cloudflare/ [commit information]: /methods/page/GitInfo [dart sass install]: /functions/css/sass/#dart-sass [dart sass]: https://sass-lang.com/dart-sass [git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git [git]: https://git-scm.com/ -[github pages]: https://pages.github.com/ -[gitlab pages]: https://docs.gitlab.com/ee/user/project/pages/ +[GitHub Pages]: /host-and-deploy/host-on-github-pages/ +[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/ [go install]: https://go.dev/doc/install [go]: https://go.dev/ [hugo modules]: /hugo-modules/ -[netlify]: https://www.netlify.com/ +[Netlify]: /host-and-deploy/host-on-netlify/ +[Render]: /host-and-deploy/host-on-render/ +[Vercel]: /host-and-deploy/host-on-vercel/ diff --git a/docs/content/en/_common/methods/output-formats/to-use-this-method.md b/docs/content/en/_common/methods/output-formats/to-use-this-method.md new file mode 100644 index 000000000..027e89b66 --- /dev/null +++ b/docs/content/en/_common/methods/output-formats/to-use-this-method.md @@ -0,0 +1,9 @@ +--- +_comment: Do not remove front matter. +--- + +To use this method you must first select a specific [output format](g) from a page's [`OutputFormats`][] collection using the [`Get`][] or [`Canonical`][] methods. + +[`Canonical`]: /methods/page/outputformats/#canonical +[`Get`]: /methods/page/outputformats/#get +[`OutputFormats`]: /methods/page/outputformats/ diff --git a/docs/content/en/_common/methods/page/output-format-methods.md b/docs/content/en/_common/methods/page/output-format-methods.md deleted file mode 100644 index 1e914db03..000000000 --- a/docs/content/en/_common/methods/page/output-format-methods.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -### Get IDENTIFIER - -(`any`) Returns the `OutputFormat` object with the given identifier. - -### MediaType - -(`media.Type`) Returns the media type of the output format. - -### MediaType.MainType - -(`string`) Returns the main type of the output format's media type. - -### MediaType.SubType - -(`string`) Returns the subtype of the current format's media type. - -### Name - -(`string`) Returns the output identifier of the output format. - -### Permalink - -(`string`) Returns the permalink of the page generated by the current output format. - -### Rel - -(`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration. - -### RelPermalink - -(`string`) Returns the relative permalink of the page generated by the current output format. diff --git a/docs/content/en/_common/methods/resource/processing-spec.md b/docs/content/en/_common/methods/resource/processing-spec.md index 395217328..20b8f8498 100644 --- a/docs/content/en/_common/methods/resource/processing-spec.md +++ b/docs/content/en/_common/methods/resource/processing-spec.md @@ -2,35 +2,72 @@ _comment: Do not remove front matter. --- -## Process specification +## Processing specification -The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: +The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence: action -: Applicable to the [`Process`](/methods/resource/process) method only. Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. - -dimensions -: Provide width _or_ height when using the [`Resize`](/methods/resource/resize) method, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). +: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions. anchor -: Use with the [`Crop`](/methods/resource/crop) and [`Fill`](/methods/resource/fill) methods. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). - -rotation -: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). - -target format -: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). - -quality -: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). - -hint -: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). - -[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp +: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your site configuration. background color -: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). +: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your site configuration. + +compression +: {{< new-in 0.153.5 />}} +: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your site configuration. + +dimensions +: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`. + +format +: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image. + +hint +: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your site configuration. + + Value|Example + :--|:-- + `drawing`|Hand or line drawing with high-contrast details + `icon`|Small colorful image + `photo`|Outdoor photograph with natural lighting + `picture`|Indoor photograph such as a portrait + `text`|Image that is primarily text + +quality +: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your site configuration. resampling filter -: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). +: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your site configuration. + + Filter|Description + :--|:-- + `box`|Simple and fast averaging filter appropriate for downscaling + `lanczos`|High-quality resampling filter for photographic images yielding sharp results + `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results + `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom + `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters + `nearestNeighbor`|Fastest resampling filter, no antialiasing + + Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. + +rotation +: The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation. + + Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your site configuration. + +[`anchor`]: /configuration/imaging/#anchor +[`bgcolor`]: /configuration/imaging/#bgcolor +[`compression`]: /configuration/imaging/#compression +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp +[`hint`]: /configuration/imaging/#hint +[`images.AutoOrient`]: /functions/images/autoorient/ +[`images.Process`]: /functions/images/process/ +[`Process`]: /methods/resource/process +[`quality`]: /configuration/imaging/#quality +[`resampleFilter`]: /configuration/imaging/#resamplefilter +[`smartcrop.js`]: https://github.com/jwagner/smartcrop.js +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[source documentation]: https://github.com/disintegration/imaging#image-resizing diff --git a/docs/content/en/_common/render-hooks/pageinner.md b/docs/content/en/_common/render-hooks/pageinner.md index 2068b28db..4cde59325 100644 --- a/docs/content/en/_common/render-hooks/pageinner.md +++ b/docs/content/en/_common/render-hooks/pageinner.md @@ -4,8 +4,6 @@ _comment: Do not remove front matter. ## PageInner details -{{< new-in 0.125.0 />}} - The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents: ```go-html-template {file="layouts/_shortcodes/include.html" copy=true} diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md index d9fd36f61..e39e359ec 100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@ -60,6 +60,9 @@ weight: 20 ## Content management +[Multidimensional content model] +: Generate pages across any combination of language, role, and version from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions. + [Content adapters] : Create content adapters to dynamically add content when building your site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. @@ -78,7 +81,7 @@ weight: 20 ## Asset pipelines [Image processing] -: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data. +: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata. [JavaScript bundling] : Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing. @@ -120,6 +123,7 @@ weight: 20 [Syntax highlighting]: /content-management/syntax-highlighting/ [Shortcodes]: /content-management/shortcodes/ +[Multidimensional content model]: /quick-reference/glossary/#sites-matrix [Content adapters]: /content-management/content-adapters/ [Taxonomies]: /content-management/taxonomies/ [Data]: /content-management/data-sources/ diff --git a/docs/content/en/configuration/all.md b/docs/content/en/configuration/all.md index 2d6178e5b..fe8e3248d 100644 --- a/docs/content/en/configuration/all.md +++ b/docs/content/en/configuration/all.md @@ -19,7 +19,7 @@ baseURL : (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash. build -: See [configure build](/configuration/build/). +: See [configure build][]. buildDrafts : (`bool`) Whether to include draft content when building a site. Default is `false`. @@ -34,20 +34,19 @@ cacheDir : (`string`) The designated cache directory. See [details](#cache-directory). caches -: See [configure file caches](/configuration/caches/). +: See [configure file caches][]. canonifyURLs : (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`. capitalizeListTitles -: {{< new-in 0.123.3 />}} -: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules. +: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`][] setting to configure capitalization rules. Default is `true`. cascade -: See [configure cascade](/configuration/cascade/). +: See [configure cascade][]. cleanDestinationDir -: (`bool`) Whether to remove files from the [`publishDir`](#publishdir) that do not exist in the [`staticDir`](#staticdir) when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`. +: (`bool`) Whether to remove files from the [`publishDir`][] that do not exist in the [`staticDir`][] when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`. contentDir : (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}} @@ -59,23 +58,43 @@ dataDir : (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}} defaultContentLanguage -: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Default is `en`. +: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`. defaultContentLanguageInSubdir -: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`. +: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`. + +defaultContentRole +: {{< new-in 0.153.0 />}} +: (`string`) The project's default content [role](g). Default is `guest`. + +defaultContentRoleInSubdir +: {{< new-in 0.153.0 />}} +: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`][]. Default is `false`. + +defaultContentVersion +: {{< new-in 0.153.0 />}} +: (`string`) The project's default content version. Default is `v1.0.0`. + +defaultContentVersionInSubdir +: {{< new-in 0.153.0 />}} +: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`][]. Default is `false`. defaultOutputFormat : (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used. deployment -: See [configure deployment](/configuration/deployment/). +: See [configure deployment][]. disableAliases -: (`bool`) Whether to disable generation of alias redirects. Even if this option is enabled, the defined aliases will still be present on the page. This allows you to manage redirects separately, for example, by generating 301 redirects in an `.htaccess` file or a Netlify `_redirects` file using a custom output format. Default is `false`. +: (`bool`) Whether to disable the generation of HTML redirect files for each path defined in the [`aliases`][aliases_front_matter] front matter field. When `true`, Hugo will not create physical files for [client-side redirection][], but the alias data remains available via the [`Aliases`][aliases_page_method] method on a `Page` object. Default is `false`. disableDefaultLanguageRedirect : {{< new-in 0.140.0 />}} -: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`. +: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`. + +disableDefaultSiteRedirect +: {{< new-in 0.154.5 />}} +: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. The default site is the site with the default content language, version, and role. Default is `false`. disableHugoGeneratorInject : (`bool`) Whether to disable injection of a `` tag into the home page. Default is `false`. @@ -84,19 +103,19 @@ disableKinds : (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`. disableLanguages -: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`] key under each language instead. +: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`][] key under each language instead. disableLiveReload : (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`. disablePathToLower -: (`bool`) Whether to disable transformation of page URLs to lower case. +: (`bool`) Whether to disable transformation of page URLs to lower case. Default is `false`. enableEmoji : (`bool`) Whether to allow emoji in Markdown. Default is `false`. enableGitInfo -: (`bool`) For sites under Git version control, whether to enable the [`GitInfo`] object for each page. With the [default front matter configuration], the `Lastmod` method on a `Page` object will return the Git author date. Default is `false`. +: (`bool`) For sites under Git version control, whether to enable the [`GitInfo`][] object for each page. With the [default front matter configuration][], the `Lastmod` method on a `Page` object will return the Git author date. Default is `false`. enableMissingTranslationPlaceholders : (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`. @@ -108,13 +127,13 @@ environment : (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`. frontmatter -: See [configure front matter](/configuration/front-matter/). +: See [configure front matter][]. hasCJKLanguage -: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`] and [`FuzzyWordCount`] methods. Default is `false`. +: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`][] and [`FuzzyWordCount`][] methods. Default is `false`. HTTPCache -: See [configure HTTP cache](/configuration/http-cache/). +: See [configure HTTP cache][]. i18nDir : (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}} @@ -123,49 +142,49 @@ ignoreCache : (`bool`) Whether to ignore the cache directory. Default is `false`. ignoreFiles -: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts]. +: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts][]. ignoreLogs -: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`]. +: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][]. ignoreVendorPaths -: (`string`) A [glob](g) pattern matching the module paths to exclude from the `_vendor` directory. +: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory. imaging -: See [configure imaging](/configuration/imaging/). +: See [configure imaging][]. languageCode -: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646]. This value does not affect translations or localization. Hugo uses this value to populate: +: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646][]. This value does not affect translations or localization. Hugo uses this value to populate: - - The `language` element in the [embedded RSS template] - - The `lang` attribute of the `html` element in the [embedded alias template] - - The `og:locale` `meta` element in the [embedded Open Graph template] + - The `language` element in the [embedded RSS template][] + - The `lang` attribute of the `html` element in the [embedded alias template][] + - The `og:locale` `meta` element in the [embedded Open Graph template][] When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key. languages -: See [configure languages](/configuration/languages/). +: See [configure languages][]. layoutDir : (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}} mainSections -: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages. +: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`][] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages. markup -: See [configure markup](/configuration/markup/). +: See [configure markup][]. mediaTypes -: See [configure media types](/configuration/media-types/). +: See [configure media types][]. menus -: See [configure menus](/configuration/menus/). +: See [configure menus][]. minify -: See [configure minify](/configuration/minify/). +: See [configure minify][]. module -: See [configure modules](/configuration/module/). +: See [configure modules][]. newContentEditor : (`string`) The editor to use when creating new content. @@ -180,25 +199,25 @@ noTimes : (`bool`) Whether to disable synchronization of file modification times. Default is `false`. outputFormats -: See [configure output formats](/configuration/output-formats/). +: See [configure output formats][]. outputs -: See [configure outputs](/configuration/outputs/). +: See [configure outputs][]. page -: See [configure page](/configuration/page/). +: See [configure page][]. pagination -: See [configure pagination](/configuration/pagination/). +: See [configure pagination][]. panicOnWarning : (`bool`) Whether to panic on the first WARNING. Default is `false`. params -: See [configure params](/configuration/params/). +: See [configure params][]. permalinks -: See [configure permalinks](/configuration/permalinks/). +: See [configure permalinks][]. pluralizeListTitles : (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`. @@ -213,7 +232,7 @@ printUnusedTemplates : (`bool`) Whether to log WARNINGs for each unused template. Default is `false`. privacy -: See [configure privacy](/configuration/privacy/). +: See [configure privacy][]. publishDir : (`string`) The designated directory for publishing the site. Default is `public`. @@ -225,47 +244,49 @@ refLinksNotFoundURL : (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. related -: See [configure related content](/configuration/related-content/). +: See [configure related content][]. relativeURLs : (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`. removePathAccents -: (`bool`) Whether to remove [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`. +: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`. renderSegments -: {{< new-in 0.124.0 />}} -: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`] configuration. +: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration. resourceDir : (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`. +roles +: See [configure roles][]. + security -: See [configure security](/configuration/security/). +: See [configure security][]. sectionPagesMenu : (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details](/content-management/menus/#define-automatically). segments -: See [configure segments](/configuration/segments/). +: See [configure segments][]. server -: See [configure server](/configuration/server/). +: See [configure server][]. services -: See [configure services](/configuration/services/). +: See [configure services][]. sitemap -: See [configure sitemap](/configuration/sitemap/). +: See [configure sitemap][]. staticDir : (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}} summaryLength -: (`int`) Applicable to [automatic summaries], the minimum number of words returned by the [`Summary`] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. Default is `70`. +: (`int`) Applicable to [automatic summaries][], the minimum number of words returned by the [`Summary`][] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. Default is `70`. taxonomies -: See [configure taxonomies](/configuration/taxonomies/). +: See [configure taxonomies][]. templateMetrics : (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics). @@ -280,26 +301,29 @@ themesDir : (`string`) The designated directory for themes. Default is `themes`. timeout -: (`string`) The timeout for generating page content, either as a [duration] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `60s`. +: (`string`) The timeout for generating page content, either as a [duration][] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `60s`. timeZone -: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`] and [`time.Format`] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones. +: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`][] and [`time.Format`][] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database][]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones. title : (`string`) The site title. titleCaseStyle -: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style). +: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`][] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style). uglyurls -: See [configure ugly URLs](/configuration/ugly-urls/). +: See [configure ugly URLs][]. + +versions +: See [configure versions][]. ## Cache directory -Hugo's file cache directory is configurable via the [`cacheDir`] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference: +Hugo's file cache directory is configurable via the [`cacheDir`][] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference: -1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) vendors, please read their documentation. For an CircleCI example, see [this configuration]. -1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir] function. On Unix systems, per the [XDG base directory specification], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. +1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) platforms, please read their documentation. For a CircleCI example, see [this configuration][]. +1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir][] function. On Unix systems, per the [XDG base directory specification][], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. 1. In a `hugo_cache_$USER` directory below the OS temp dir. To determine the current `cacheDir`: @@ -310,13 +334,13 @@ hugo config | grep cachedir ## Title case style -Hugo's [`titleCaseStyle`] setting governs capitalization for automatically generated section titles and the [`strings.Title`] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules. +Hugo's [`titleCaseStyle`][] setting governs capitalization for automatically generated section titles and the [`strings.Title`][] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules. ap -: Use the capitalization rules published in the [Associated Press Stylebook]. This is the default. +: Use the capitalization rules published in the [Associated Press Stylebook][]. This is the default. chicago -: Use the capitalization rules published in the [Chicago Manual of Style]. +: Use the capitalization rules published in the [Chicago Manual of Style][]. go : Capitalize the first letter of every word. @@ -329,15 +353,24 @@ none ## Localized settings -Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings). +Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages][]. [`cacheDir`]: #cachedir +[`defaultContentLanguage`]: #defaultcontentlanguage +[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir +[`defaultContentRole`]: #defaultcontentrole +[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir +[`defaultContentVersion`]: #defaultcontentversion +[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir [`disabled`]: /configuration/languages/#disabled +[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect [`erroridf`]: /functions/fmt/erroridf/ [`FuzzyWordCount`]: /methods/page/fuzzywordcount/ [`GitInfo`]: /methods/page/gitinfo/ [`MainSections`]: /methods/site/mainsections/ +[`publishDir`]: #publishdir [`segments`]: /configuration/segments/ +[`staticDir`]: #staticdir [`strings.Title`]: /functions/strings/title/ [`Summary`]: /methods/page/summary/ [`time.AsTime`]: /functions/time/astime/ @@ -345,16 +378,52 @@ Some configuration settings, such as menus and custom parameters, can be defined [`titleCaseStyle`]: #titlecasestyle [`warnidf`]: /functions/fmt/warnidf/ [`WordCount`]: /methods/page/wordcount/ +[aliases_front_matter]: /content-management/front-matter/#aliases +[aliases_page_method]: /methods/page/aliases/ [Associated Press Stylebook]: https://www.apstylebook.com/ [automatic summaries]: /content-management/summaries/#automatic-summary [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html +[client-side redirection]: /content-management/urls/#client-side-redirection +[composite characters]: https://en.wikipedia.org/wiki/Precomposed_character +[configure build]: /configuration/build/ +[configure cascade]: /configuration/cascade/ +[configure deployment]: /configuration/deployment/ +[configure file caches]: /configuration/caches/ +[configure front matter]: /configuration/front-matter/ +[configure HTTP cache]: /configuration/http-cache/ +[configure imaging]: /configuration/imaging/ +[configure languages]: /configuration/languages/ +[configure markup]: /configuration/markup/ +[configure media types]: /configuration/media-types/ +[configure menus]: /configuration/menus/ +[configure minify]: /configuration/minify/ +[configure modules]: /configuration/module/ +[configure output formats]: /configuration/output-formats/ +[configure outputs]: /configuration/outputs/ +[configure page]: /configuration/page/ +[configure pagination]: /configuration/pagination/ +[configure params]: /configuration/params/ +[configure permalinks]: /configuration/permalinks/ +[configure privacy]: /configuration/privacy/ +[configure related content]: /configuration/related-content +[configure roles]: /configuration/roles/ +[configure security]: /configuration/security/ +[configure segments]: /configuration/segments/ +[configure server]: /configuration/server/ +[configure services]: /configuration/services/ +[configure sitemap]: /configuration/sitemap/ +[configure taxonomies]: /configuration/taxonomies/ +[configure ugly URLs]: /configuration/ugly-urls/ +[configure versions]: /configuration/versions/ [default front matter configuration]: /configuration/front-matter/ [duration]: https://pkg.go.dev/time#Duration [embedded alias template]: <{{% eturl alias %}}> [embedded Open Graph template]: <{{% eturl opengraph %}}> [embedded RSS template]: <{{% eturl rss %}}> [IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +[language keys]: /configuration/languages/#language-keys [module mounts]: /configuration/module/#mounts +[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn [os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 [this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml diff --git a/docs/content/en/configuration/caches.md b/docs/content/en/configuration/caches.md index 03b499dcb..15783a7af 100644 --- a/docs/content/en/configuration/caches.md +++ b/docs/content/en/configuration/caches.md @@ -10,21 +10,49 @@ This is the default configuration: {{< code-toggle config=caches />}} +## Purpose + +Hugo uses file caches to store data on disk, avoiding repeated operations within the same build and persisting data from one build to the next. + +assets +: Caches processed CSS and Sass resources. + +getresource +: Caches files fetched from remote URLs via the [`resources.GetRemote`][] function. + +images +: Caches processed images. + +misc +: Caches miscellaneous data. + +modulequeries +: Caches the results of module resolution queries. + +modules +: Caches downloaded modules. + ## Keys dir -: (`string`) The absolute file system path where the cached files will be stored. You can begin the path with the `:cacheDir` or `:resourceDir` token. These tokens will be replaced with the actual configured cache directory and resource directory paths, respectively. +: (`string`) The absolute file system path where Hugo stores the cached files. You can begin the path with the `:cacheDir` or `:resourceDir` [tokens](#tokens) to anchor the cache to specific system or project locations. maxAge -: (`string`) The [duration](g) a cached entry remains valid before being evicted. A value of `0` disables the cache. A value of `-1` means the cache entry never expires (the default). +: (`string`) The duration a cached entry remains valid before being evicted, expressed as a [duration](g). A value of `0` disables the cache for that key, and a value of `-1` means the cache entry never expires. Default is `-1`. ## Tokens `:cacheDir` -: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir). +: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir). `:project` -: (`string`) The base directory name of the current Hugo project. By default, this ensures each project has isolated file caches, so running `hugo --gc` will only affect the current project's cache and not those of other Hugo projects on the same machine. +: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo --gc` command from affecting other projects on the same machine. `:resourceDir` -: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir). +: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir). + +## Garbage collection + +As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo --gc` command to remove these expired or unused entries from the file cache. + +[`resources.GetRemote`]: /functions/resources/getremote/ diff --git a/docs/content/en/configuration/cascade.md b/docs/content/en/configuration/cascade.md index 9a1fda4c6..7b6ccd933 100644 --- a/docs/content/en/configuration/cascade.md +++ b/docs/content/en/configuration/cascade.md @@ -23,7 +23,7 @@ color = 'red' The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself: @@ -40,16 +40,16 @@ path = '{/articles,/articles/**}' Use any combination of these keywords to target pages and/or environments: environment -: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`. +: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`. kind -: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`. +: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`. lang -: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`. +: (`string`) A [glob pattern](g) matching the [page language]. For example: `{en,de}`. path -: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`. +: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`. ## Array diff --git a/docs/content/en/configuration/deployment.md b/docs/content/en/configuration/deployment.md index fad50da63..f145f3f70 100644 --- a/docs/content/en/configuration/deployment.md +++ b/docs/content/en/configuration/deployment.md @@ -53,13 +53,13 @@ cloudFrontDistributionID : (`string`) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target. exclude -: (`string`) A [glob](g) pattern matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. +: (`string`) A [glob pattern](g) matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. googleCloudCDNOrigin : (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `/`. include -: (`string`) A [glob](g) pattern matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. +: (`string`) A [glob pattern](g) matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted. name : (`string`) An arbitrary name for this target. diff --git a/docs/content/en/configuration/http-cache.md b/docs/content/en/configuration/http-cache.md index c48c9cbcd..73ef02a6c 100644 --- a/docs/content/en/configuration/http-cache.md +++ b/docs/content/en/configuration/http-cache.md @@ -57,10 +57,10 @@ respectCacheControlNoStoreInResponse : (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` response header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `false`. cache.for.excludes -: (`string`) A list of [glob](g) patterns to exclude from caching. In its default configuration HTTP caching excludes all files. +: (`[]string`) A slice of [glob patterns](g) to exclude from caching. In its default configuration HTTP caching excludes all files. cache.for.includes -: (`string`) A list of [glob](g) patterns to cache. +: (`[]string`) A slice of [glob patterns](g) to cache. polls : A slice of polling configurations. @@ -75,10 +75,10 @@ polls.low : (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`. polls.for.excludes -: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration. +: (`[]string`) A slice of [glob patterns](g) to exclude from polling for this configuration. polls.for.includes -: (`string`) A list of [glob](g) patterns to include in polling for this configuration. +: (`[]string`) A slice of [glob patterns](g) to include in polling for this configuration. ## HTTP polling @@ -109,10 +109,10 @@ polls.low : (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`. polls.for.excludes -: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration. +: (`[]string`) A list of [glob patterns](g) to exclude from polling for this configuration. polls.for.includes -: (`string`) A list of [glob](g) patterns to include in polling for this configuration. +: (`[]string`) A list of [glob patterns](g) to include in polling for this configuration. ## Behavior diff --git a/docs/content/en/configuration/imaging.md b/docs/content/en/configuration/imaging.md index 13ecf9c26..69c654d60 100644 --- a/docs/content/en/configuration/imaging.md +++ b/docs/content/en/configuration/imaging.md @@ -14,56 +14,119 @@ These are the default settings for processing images: [imaging] anchor = 'Smart' bgColor = '#ffffff' -hint = 'photo' +compression = 'lossy' quality = 75 resampleFilter = 'box' {{< /code-toggle >}} anchor -: (`string`) When using the [`Crop`] or [`Fill`] method, the anchor determines the placement of the crop box. One of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. +: (`string`) The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. Default is `Smart`. bgColor -: (`string`) The background color of the resulting image. Applicable when converting from a format that supports transparency to a format that does not support transparency, for example, when converting from PNG to JPEG. Expressed as an RGB [hexadecimal] value. Default is `#ffffff`. +: (string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`. -[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color - -hint -: (`string`) Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. One of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). +compression +: {{< new-in 0.153.5 />}} +: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. Default is `lossy`. quality -: (`int`) Applicable to JPEG and WebP images, this value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between `1` and `100`, inclusive. Default is `75`. +: (`int`) The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`. resampleFilter -: (`string`) The resampling filter used when resizing an image. Default is `box`. See [details](/content-management/image-processing/#resampling-filter) +: (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`. -## EXIF data + Filter|Description + :--|:-- + `box`|Simple and fast averaging filter appropriate for downscaling + `lanczos`|High-quality resampling filter for photographic images yielding sharp results + `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results + `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom + `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters + `nearestNeighbor`|Fastest resampling filter, no antialiasing -These are the default settings for extracting EXIF data from images: + Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. + +## WebP images + +{{< new-in 0.155.0 />}} + +These are the default settings specific to processing WebP images: + +{{< code-toggle file=hugo >}} +[imaging.webp] +hint = 'photo' +method = 4 +useSharpYuv = true +{{< /code-toggle >}} + +hint +: (`string`) The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. + + Value|Example + :--|:-- + `drawing`|Hand or line drawing with high-contrast details + `icon`|Small colorful image + `photo`|Outdoor photograph with natural lighting + `picture`|Indoor photograph such as a portrait + `text`|Image that is primarily text + +method +: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `4`. + +useSharpYuv +: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `true`. + +## Exif method + +These are the default settings for the [`Exif`] method on an image `Resource` object: {{< code-toggle file=hugo >}} [imaging.exif] -includeFields = "" -excludeFields = "" disableDate = false disableLatLong = false +excludeFields = "" +includeFields = "" {{< /code-toggle >}} disableDate -: (`bool`) Whether to disable extraction of the image creation date/time. Default is `false`. +: (`bool`) Whether to disable the [`Date`][] method by returning its zero value. Default is `false`. disableLatLong -: (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`. +: (`bool`) Whether to disable the [`Lat`][] and [`Long`][] methods by returning their zero values. Default is `false`. excludeFields -: (`string`) A [regular expression](g) matching the tags to exclude when extracting EXIF data. +: (`string`) A [regular expression](g) matching the fields to exclude when extracting metadata. + + > [!note] + > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. includeFields -: (`string`) A [regular expression](g) matching the tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`. +: (`string`) A [regular expression](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `'.*'` to include all fields. -> [!note] -> To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. -> -> To control tag availability, change the `excludeFields` or `includeFields` settings as described above. +## Meta method -[`Crop`]: /methods/resource/crop/ -[`Fill`]: /methods/resource/fill/ +{{< new-in 0.155.0 />}} + +These are the default settings for the [`Meta`] method on an image `Resource` object: + +{{< code-toggle file=hugo >}} +[imaging.meta] +fields = [] +sources = ['exif', 'iptc'] +{{< /code-toggle >}} + +fields +: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields. + + > [!note] + > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. + +sources +: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance. + +[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp +[`Exif`]: /methods/resource/exif/ +[`Meta`]: /methods/resource/meta/ +[`smartcrop.js`]: https://github.com/jwagner/smartcrop.js +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[source documentation]: https://github.com/disintegration/imaging#image-resizing diff --git a/docs/content/en/configuration/introduction.md b/docs/content/en/configuration/introduction.md index 77fce4e8a..c1f94ae8d 100644 --- a/docs/content/en/configuration/introduction.md +++ b/docs/content/en/configuration/introduction.md @@ -235,7 +235,7 @@ The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configura > [!note] > An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used. -Environment variables simplify configuration for [CI/CD](g) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files. +Environment variables simplify configuration for [CI/CD](g) platforms by allowing you to set values directly within their respective configuration and workflow files. > [!note] > Environment variable names must be prefixed with `HUGO_`. @@ -253,7 +253,6 @@ HUGO_FILE_LOG_FORMAT : (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`. 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 `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 diff --git a/docs/content/en/configuration/languages.md b/docs/content/en/configuration/languages.md index 72fee25d3..f9f81e1ea 100644 --- a/docs/content/en/configuration/languages.md +++ b/docs/content/en/configuration/languages.md @@ -18,14 +18,14 @@ disableLanguages = [] {{< /code-toggle >}} defaultContentLanguage -: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined [language keys](#language-keys). Default is `en`. +: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`. defaultContentLanguageInSubdir -: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`. +: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`. disableDefaultLanguageRedirect : {{< new-in 0.140.0 />}} -: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`. +: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`. disableLanguages : (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`](#disabled) key under each language instead. @@ -42,25 +42,30 @@ disabled : (`bool`) Whether to disable this language when building the site. Default is `false`. languageCode -: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate: +: (`string`) The language tag as described in [RFC 5646][]. This is the primary value used by the [`language.Translate`][] function to select a translation table, falling back to the language key if a matching translation table does not exist. - - The `lang` attribute of the `html` element in the [embedded alias template] - - The `language` element in the [embedded RSS template] - - The `locale` property in the [embedded OpenGraph template] + Hugo also uses this value to populate: - Access this value from a template using the [`Language.LanguageCode`] method on a `Site` or `Page` object. + - The `lang` attribute of the `html` element in the [embedded alias template][] + - The `language` element in the [embedded RSS template][] + - The `locale` property in the [embedded OpenGraph template][] + + > [!note] + > This value does not affect localization of dates, numbers, and currencies, nor does it affect the site's URL structure. These are controlled by the [language key](#language-keys). + + Access this value from a template using the [`Language.LanguageCode`][] method on a `Site` or `Page` object. languageDirection -: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`] method on a `Site` or `Page` object. +: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. languageName -: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`] method on a `Site` or `Page` object. +: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object. title -: (`string`) The site title for this language. Access this value from a template using the [`Title`] method on a `Site` object. +: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object. weight -: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`] method on a `Site` or `Page` object. +: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`][] method on a `Site` or `Page` object. ## Localized settings @@ -87,7 +92,7 @@ Any key not defined in a `languages` object will fall back to the global value i ## Language keys -Language keys must conform to the syntax described in [RFC 5646]. For example: +Language keys must conform to the syntax described in [RFC 5646][]. For example: {{< code-toggle file=hugo >}} defaultContentLanguage = 'de' @@ -99,7 +104,7 @@ defaultContentLanguage = 'de' weight = 3 {{< /code-toggle >}} -Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example: +Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. Omit the `art-x-` prefix from the language key. For example: {{< code-toggle file=hugo >}} defaultContentLanguage = 'en' @@ -145,7 +150,7 @@ subtitle = 'Reference, Tutorials, and Explanations' {{< /code-toggle >}} > [!note] -> In the example above, omit `contentDir` if [translating by file name]. +> In the example above, omit `contentDir` if [translating by file name][]. ## Multihost @@ -179,15 +184,20 @@ public └── fr ``` +[`defaultContentLanguage`]: #defaultcontentlanguage +[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir [`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir +[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect [`Language.LanguageCode`]: /methods/site/language/#languagecode [`Language.LanguageDirection`]: /methods/site/language/#languagedirection [`Language.LanguageName`]: /methods/site/language/#languagename +[`language.Translate`]: /functions/lang/translate/ [`Language.Weight`]: /methods/site/language/#weight [`Title`]: /methods/site/title/ [embedded alias template]: <{{% eturl alias %}}> [embedded OpenGraph template]: <{{% eturl opengraph %}}> [embedded RSS template]: <{{% eturl rss %}}> -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 +[language keys]: #language-keys [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 [translating by file name]: /content-management/multilingual/#translation-by-file-name diff --git a/docs/content/en/configuration/markup.md b/docs/content/en/configuration/markup.md index a34074ae5..31c8de505 100644 --- a/docs/content/en/configuration/markup.md +++ b/docs/content/en/configuration/markup.md @@ -136,7 +136,6 @@ Markdown|Replaced by|Description Most of the Goldmark settings above are self-explanatory, but some require explanation. duplicateResourceFiles -: {{< new-in 0.123.0 />}} : (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`. > [!note] @@ -169,30 +168,27 @@ parser.attribute.title renderHooks.image.enableDefault -: {{< new-in 0.123.0 />}} : Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead. renderHooks.image.useEmbedded : {{< new-in 0.148.0 />}} : (`string`) When to use the [embedded image render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`. - - `auto`: Automatically use the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom image render hooks are defined by your project, modules, or themes, these will be used instead. + - `auto`: Use the embedded image render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom image render hooks are defined by your project, modules, or themes, these will be used instead. - `never`: Never use the embedded image render hook. If custom image render hooks are defined by your project, modules, or themes, these will be used instead. - - `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes. In this case, the embedded hook takes precedence. + - `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes. - `fallback`: Use the embedded image render hook only if custom image render hooks are not provided by your project, modules, or themes. If custom image render hooks exist, these will be used instead. renderHooks.link.enableDefault -: {{< new-in 0.123.0 />}} : Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead. renderHooks.link.useEmbedded -: {{< new-in 0.148.0 />}} : (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`. - - `auto`: Automatically use the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead. + - `auto`: Use the embedded link render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom link render hooks are defined by your project, modules, or themes, these will be used instead. - `never`: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead. - - `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes. In this case, the embedded hook takes precedence. + - `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes. - `fallback`: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead. renderer.hardWraps @@ -216,7 +212,7 @@ backend : (`string`) The backend output file format. Default is `html5`. extensions -: (`string array`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`. +: (`[]string`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`. > [!note] > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`. diff --git a/docs/content/en/configuration/minify.md b/docs/content/en/configuration/minify.md index 3f010f974..5107385ec 100644 --- a/docs/content/en/configuration/minify.md +++ b/docs/content/en/configuration/minify.md @@ -13,8 +13,6 @@ This is the default configuration: See the [tdewolff/minify] project page for details, but note the following: - `css.inline` is for internal use. Changing this setting has no effect. -- `css.keepCSS2` has been deprecated. Use `css.version` instead. - `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead. -- `svg.inline` is for internal use. Changing this setting has no effect. [tdewolff/minify]: https://github.com/tdewolff/minify diff --git a/docs/content/en/configuration/module.md b/docs/content/en/configuration/module.md index 76fc034de..9c1618c71 100644 --- a/docs/content/en/configuration/module.md +++ b/docs/content/en/configuration/module.md @@ -30,13 +30,13 @@ auth : (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information. noProxy -: (`string`) A comma-separated list of [glob](g) patterns matching paths that should not use the [configured proxy server](#proxy). +: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should not use the [configured proxy server](#proxy). noVendor -: (`string`) A [glob](g) pattern matching module paths to skip when vendoring. +: (`string`) A [glob pattern](g) matching module paths to skip when vendoring. private -: (`string`) A comma-separated list of [glob](g) patterns matching paths that should be treated as private. +: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should be treated as private. proxy : (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar. @@ -76,8 +76,18 @@ You can omit any of the settings above. extended : (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition. + > [!note] + > The extended version check is disabled in v0.153.2 and later. + > + > Historically, certain features—specifically WebP encoding and LibSass—required the Hugo Extended binary. However, as of v0.153.0: + > + > - WebP encoding is now supported in all Hugo editions. + > - LibSass has been deprecated in favor of [Dart Sass][], which is compatible with any Hugo edition. + > + > Because these dependencies no longer require a specialized binary, the internal enforcement check for the extended version has been removed. Site and theme authors are encouraged to use Dart Sass to ensure cross-edition compatibility. + max -: (`string`) The maximum Hugo version supported, for example `0.152.2`. +: (`string`) The maximum Hugo version supported, for example `0.153.0`. min : (`string`) The minimum Hugo version supported, for example `0.102.0`. @@ -123,14 +133,6 @@ version > [!important] > If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`][], [`assetDir`][], [`contentDir`][], [`dataDir`][], [`i18nDir`][], [`layoutDir`][], or [`staticDir`][]. -[`archetypeDir`]: /configuration/all/#archetypedir -[`assetDir`]: /configuration/all/#assetdir -[`contentDir`]: /configuration/all/#contentdir -[`dataDir`]: /configuration/all/#datadir -[`i18nDir`]: /configuration/all/#i18ndir -[`layoutDir`]: /configuration/all/#layoutdir -[`staticDir`]: /configuration/all/#staticdir - ### Default mounts Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one. @@ -153,16 +155,13 @@ disableWatch : {{< new-in 0.128.0 />}} : (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`. -lang -: (`string`) The language code, e.g. "en". Relevant for `content` mounts, and `static` mounts when in multihost mode. +files +: {{< new-in 0.153.0 />}} +: (`[]string`) A [glob slice](g) defining the files to include or exclude. -includeFiles -: (`string` or `[]string`) One or more [glob](g) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted. - - The glob patterns are matched against file names relative to the source root. Use Unix-style forward slashes (`/`), even on Windows. A single forward slash (`/`) matches the mount root, and double asterisks (`**`) act as a recursive wildcard, matching all directories and files beneath a given point (e.g., `/posts/**.jpg`). The search is case-insensitive. - -excludeFiles -: (`string` or `[]string`) One or more [glob](g) patterns matching files to exclude. +sites +: {{< new-in 0.153.0 />}} +: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the mount. Relevant for `content` and `layouts` mounts, and `static` mounts when in multihost mode. For `static` and `layouts`, only the `matrix` keyword is supported. ### Example @@ -171,7 +170,7 @@ excludeFiles [[module.mounts]] source="content" target="content" - excludeFiles="docs/*" + files=["! docs/*"] [[module.mounts]] source="node_modules" target="assets" @@ -180,4 +179,12 @@ excludeFiles target="assets" {{< /code-toggle >}} +[`archetypeDir`]: /configuration/all/#archetypedir +[`assetDir`]: /configuration/all/#assetdir +[`contentDir`]: /configuration/all/#contentdir +[`dataDir`]: /configuration/all/#datadir +[`i18nDir`]: /configuration/all/#i18ndir +[`layoutDir`]: /configuration/all/#layoutdir +[`staticDir`]: /configuration/all/#staticdir [`themesDir`]: /configuration/all/#themesdir +[Dart Sass]: /functions/css/sass/#dart-sass diff --git a/docs/content/en/configuration/output-formats.md b/docs/content/en/configuration/output-formats.md index 7e80d30fb..bf61b3d2e 100644 --- a/docs/content/en/configuration/output-formats.md +++ b/docs/content/en/configuration/output-formats.md @@ -41,7 +41,7 @@ baseName : (`string`) The base name of the published file. Default is `index`. isHTML -: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`. +: (`bool`) Whether to classify the output format as HTML. This value determines when the LiveReload script is injected and, in conjunction with [`permalinkable`](#permalinkable), whether [alias redirects][] are generated. Default is `false`. isPlainText : (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`. @@ -59,13 +59,13 @@ path : (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing. permalinkable -: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`. +: (`bool`) Whether to return the rendering output format rather than the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`. protocol : (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`. rel -: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`. +: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`. root : (`bool`) Whether to publish files to the root of the publish directory. Default is `false`. @@ -196,6 +196,7 @@ Output format|Template path [`publishDir`]: /configuration/all/#publishdir [`RelPermalink`]: /methods/page/relpermalink/ [`uglyURLs`]: /configuration/ugly-urls/ +[alias redirects]: /content-management/urls/#aliases [configure media types]: /configuration/media-types/ [configure outputs]: /configuration/outputs/ [configured media types]: /configuration/media-types/ diff --git a/docs/content/en/configuration/related-content.md b/docs/content/en/configuration/related-content.md index 421a1ea77..967c72a9a 100644 --- a/docs/content/en/configuration/related-content.md +++ b/docs/content/en/configuration/related-content.md @@ -46,7 +46,7 @@ weight : (`int`) An integer weight that indicates how important this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. Default is `0`. cardinalityThreshold -: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`. +: (`int`) If between `1` and `100`, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`. pattern : (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. diff --git a/docs/content/en/configuration/roles.md b/docs/content/en/configuration/roles.md new file mode 100644 index 000000000..9c5bfe62c --- /dev/null +++ b/docs/content/en/configuration/roles.md @@ -0,0 +1,24 @@ +--- +title: Configure roles +linkTitle: Roles +description: Configure roles. +categories: [] +keywords: [] +--- + +{{< new-in 0.153.0 />}} + +This is the default configuration: + +{{< code-toggle config=roles />}} + +To define "guest" and "member" roles: + +{{< code-toggle >}} +[roles.guest] +weight = 20 +[roles.member] +weight = 10 +{{< /code-toggle >}} + +Roles are sorted by their [weight](g) in descending order, then by their name in descending order. This affects build order and complement selection. diff --git a/docs/content/en/configuration/segments.md b/docs/content/en/configuration/segments.md index b87c870c4..a5e3f1c2a 100644 --- a/docs/content/en/configuration/segments.md +++ b/docs/content/en/configuration/segments.md @@ -6,8 +6,6 @@ categories: [] keywords: [] --- -{{< new-in 0.124.0 />}} - > [!note] > The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available. @@ -23,7 +21,7 @@ Segmented rendering offers several advantages: Each segment is defined by include and exclude filters: - Filters: Each segment has zero or more exclude filters and zero or more include filters. -- Matchers: Each filter contains one or more field [glob](g) matchers. +- Matchers: Each filter contains one or more field [glob pattern](g) matchers. - Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic. ## Filter fields @@ -31,16 +29,17 @@ Each segment is defined by include and exclude filters: Available fields for filtering: kind -: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`. +: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`. -lang -: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`. +sites +: {{< new-in 0.153.0 />}} +: (`map`) A map to define [sites matrix](g). output -: (`string`) A [glob](g) pattern matching the [output format](g) of the page. For example: `{html,json}`. +: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`. path -: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`. +: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`. ## Example @@ -74,4 +73,3 @@ hugo --renderSegments segment1,segment2 ``` [`renderSegments`]: /configuration/all/#rendersegments -[page language]: /methods/page/language/ diff --git a/docs/content/en/configuration/server.md b/docs/content/en/configuration/server.md index f77e7f47f..0d4831bff 100644 --- a/docs/content/en/configuration/server.md +++ b/docs/content/en/configuration/server.md @@ -29,11 +29,11 @@ force : (`bool`) Whether to force a redirect even if there is existing content in the path. from -: (`string`) A [glob](g) pattern matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. +: (`string`) A [glob pattern](g) matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. fromHeaders : {{< new-in 0.144.0 />}} -: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob](g) pattern with values to match. If the map is empty, the redirect will always be triggered. +: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob pattern](g) with values to match. If the map is empty, the redirect will always be triggered. fromRe : {{< new-in 0.144.0 />}} diff --git a/docs/content/en/configuration/services.md b/docs/content/en/configuration/services.md index dbe3893a7..a25e63ac3 100644 --- a/docs/content/en/configuration/services.md +++ b/docs/content/en/configuration/services.md @@ -26,12 +26,6 @@ googleAnalytics.id {{ .Site.Config.Services.GoogleAnalytics.ID }} ``` -instagram.accessToken -: (`string`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting. - -instagram.disableInlineCSS -: (`bool`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting. - rss.limit : (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details](/templates/rss/). To access this value from a template: @@ -39,9 +33,6 @@ rss.limit {{ .Site.Config.Services.RSS.Limit }} ``` -twitter.disableInlineCSS -: (`bool`) Do not use. Deprecated in [v0.141.0]. Use the `x` shortcode instead. - x.disableInlineCSS : (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template: diff --git a/docs/content/en/configuration/sitemap.md b/docs/content/en/configuration/sitemap.md index bc972994c..800032583 100644 --- a/docs/content/en/configuration/sitemap.md +++ b/docs/content/en/configuration/sitemap.md @@ -14,7 +14,6 @@ changefreq : (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). disable -: {{< new-in 0.125.0 />}} : (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. filename diff --git a/docs/content/en/configuration/versions.md b/docs/content/en/configuration/versions.md new file mode 100644 index 000000000..e6902b643 --- /dev/null +++ b/docs/content/en/configuration/versions.md @@ -0,0 +1,26 @@ +--- +title: Configure versions +linkTitle: Versions +description: Configure versions. +categories: [] +keywords: [] +--- + +{{< new-in 0.153.0 />}} + +This is the default configuration: + +{{< code-toggle config=versions />}} + +To define "v1.0.0" and "v2.0.0" versions: + +{{< code-toggle >}} +[versions."v1.0.0"] +weight = 0 +[versions."v2.0.0"] +weight = 0 +{{< /code-toggle >}} + +Versions are sorted by their [weight](g) in ascending order, then by their [semantic version] in descending order. This affects build order and complement selection. + +[semantic version]: https://semver.org/ diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index b843ddb99..f4ab7d8be 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -41,6 +41,7 @@ Disqus has its own [internal template](/templates/embedded/#disqus) available, t Commercial commenting systems: +- [Commentix](https://www.commentix.com/) - [Emote](https://emote.com/) - [Graph Comment](https://graphcomment.com/) - [Hyvor Talk](https://talk.hyvor.com/) @@ -60,6 +61,7 @@ Open-source commenting systems: - [Staticman](https://staticman.net/) - [Talkyard](https://blog-comments.talkyard.io/) - [Utterances](https://utteranc.es/) +- [Zoomment](https://zoomment.com/) [configuration]: /configuration/ [disquspartial]: /templates/embedded/#disqus diff --git a/docs/content/en/content-management/content-adapters.md b/docs/content/en/content-management/content-adapters.md index 9eae86266..f586311b3 100644 --- a/docs/content/en/content-management/content-adapters.md +++ b/docs/content/en/content-management/content-adapters.md @@ -99,7 +99,9 @@ Returns a persistent "scratch pad" to store and manipulate data. The main use ca ### EnableAllLanguages -By default, Hugo executes the content adapter for the language defined by the `_content.gotmpl` file. Use this method to activate the content adapter for all languages. +By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to all languages while maintaining the current role and version. + +For more fine-grained control, define a `sites.matrix` in front matter or in a content mount. ```go-html-template {file="content/books/_content.gotmpl"} {{ .EnableAllLanguages }} @@ -116,6 +118,14 @@ By default, Hugo executes the content adapter for the language defined by the `_ {{ .AddPage $page }} ``` +### EnableAllDimensions + +By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, role, and version. + +For more fine-grained control, define a `sites.matrix` in front matter or in a content mount. + +{{< new-in v0.153.0 />}} + ## Page map Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below. diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md index f0484ef74..9b2a434b8 100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@ -41,7 +41,7 @@ The most common front matter fields are `date`, `draft`, `title`, and `weight`, [parameters]: #parameters aliases -: (`string array`) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details. +: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details. build : (`map`) A map of [build options]. @@ -68,7 +68,7 @@ isCJKLanguage : (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object. keywords -: (`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object. +: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object. lastmod : (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object. @@ -83,16 +83,15 @@ markup : (`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension. menus -: (`string`, `string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details. +: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details. modified : Alias to [lastmod](#lastmod). outputs -: (`string array`) The [output formats] to render. See [configure outputs] for more information. +: (`[]string`) The [output formats] to render. See [configure outputs] for more information. params -: {{< new-in 0.123.0 />}} : (`map`) A map of custom [page parameters]. pubdate @@ -110,6 +109,24 @@ resources sitemap : (`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object. +sites +: {{< new-in 0.153.0 />}} +: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page. + + + + {{< code-toggle file=content/_index.md fm=true >}} + title = 'Home' + [sites.matrix] + languages = ["en","fr"] + versions = ["v1.2.*","v2.*.*"] + roles = ["**"] + [sites.complements] + versions = ["v3.*.*"] + {{< /code-toggle >}} + + + slug : (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object. @@ -136,8 +153,6 @@ weight ## Parameters -{{< new-in 0.123.0 />}} - Specify custom page parameters under the `params` key in front matter: {{< code-toggle file=content/example.md fm=true >}} @@ -219,12 +234,15 @@ title = 'Home' color = 'red' {{< /code-toggle >}} +{{< new-in 0.153.0 />}} +From Hugo 0.153.0, you can also set the [sites](#sites) front matter as cascade front matter values, which means that you can e.g. apply one or more languages to the `target` pages. + ### Target The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter from the home page only to pages within the "articles" section, including the "articles" section page itself: @@ -237,18 +255,24 @@ title = 'Home' color = 'red' [cascade.target] path = '{/articles,/articles/**}' +[cascade.target.sites.matrix] +languages = ['en','fr'] {{< /code-toggle >}} Use any combination of these keywords to target pages and/or environments: environment -: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`. +: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`. kind -: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`. +: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`. path -: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`. +: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`. + +sites +: {{< new-in 0.153.0 />}} +: (`map`) A map to define [sites matrix](g) for the target, as in: Which sites should receive the cascaded values. ### Array diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md index 3cf8aa4fd..fca742048 100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@ -1,15 +1,17 @@ --- title: Image processing -description: Resize, crop, rotate, filter, and convert images. +description: Process, transform, and analyze images. categories: [] keywords: [] --- -## Image resources +Hugo provides methods to transform and analyze images during the build process. The results are cached to ensure subsequent builds remain fast. -To process an image you must access the file as a page resource, global resource, or remote resource. +## Resources -### Page resource +To process an image you must capture the file as a page resource, a global resource, or a remote resource. + +### Page {{% glossary-term "page resource" %}} @@ -21,13 +23,13 @@ content/ └── sunset.jpg <-- page resource ``` -To access an image as a page resource: +To capture an image as a page resource: ```go-html-template {{ $image := .Resources.Get "sunset.jpg" }} ``` -### Global resource +### Global {{% glossary-term "global resource" %}} @@ -37,34 +39,34 @@ assets/ └── sunset.jpg <-- global resource ``` -To access an image as a global resource: +To capture an image as a global resource: ```go-html-template {{ $image := resources.Get "images/sunset.jpg" }} ``` -### Remote resource +### Remote {{% glossary-term "remote resource" %}} -To access an image as a remote resource: +To capture an image as a remote resource: ```go-html-template {{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} ``` -## Image rendering +## Rendering -Once you have accessed an image as a resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties. +Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods. -Example 1: Throws an error if the resource is not found. +Example 1: Throw an error if the resource is not found. ```go-html-template {{ $image := .Resources.GetMatch "sunset.jpg" }} ``` -Example 2: Skips image rendering if the resource is not found. +Example 2: Skip image rendering if the resource is not found. ```go-html-template {{ $image := .Resources.GetMatch "sunset.jpg" }} @@ -81,7 +83,7 @@ Example 3: A more concise way to skip image rendering if the resource is not fou {{ end }} ``` -Example 4: Skips rendering if there's problem accessing a remote resource. +Example 4: Skip rendering if there's problem accessing a remote resource. ```go-html-template {{ $url := "https://gohugo.io/img/hugo-logo.png" }} @@ -96,350 +98,80 @@ Example 4: Skips rendering if there's problem accessing a remote resource. {{ end }} ``` -## Image processing methods +## Processing -The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. - -> [!note] -> Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG, PNG, TIFF, and WebP images. - -### Process - -> [!note] -> The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process). - -Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`]. - -See [Options](#image-processing-options) for available options. - -You can also use this method apply image processing that does not need any scaling, e.g. format conversions: +To transform an image, apply a processing method to the image resource. Hugo generates the processed image on demand, caches the result, and returns a new resource object. ```go-html-template -{{/* Convert the image from JPG to PNG. */}} -{{ $png := $jpg.Process "png" }} -``` - -Some more examples: - -```go-html-template -{{/* Rotate the image 90 degrees counter-clockwise. */}} -{{ $image := $image.Process "r90" }} - -{{/* Scaling actions. */}} -{{ $image := $image.Process "resize 600x" }} -{{ $image := $image.Process "crop 600x400" }} -{{ $image := $image.Process "fit 600x400" }} -{{ $image := $image.Process "fill 600x400" }} -``` - -### Resize - -Resize an image to the given width and/or height. - -If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. - -```go-html-template -{{/* Resize to a width of 600px and preserve aspect ratio */}} -{{ $image := $image.Resize "600x" }} - -{{/* Resize to a height of 400px and preserve aspect ratio */}} -{{ $image := $image.Resize "x400" }} - -{{/* Resize to a width of 600px and a height of 400px */}} -{{ $image := $image.Resize "600x400" }} -``` - -### Fit - -Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. - -```go-html-template -{{ $image := $image.Fit "600x400" }} -``` - -### Fill - -Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. - -```go-html-template -{{ $image := $image.Fill "600x400" }} -``` - -### Crop - -Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. - -```go-html-template -{{ $image := $image.Crop "600x400" }} -``` - -### Filter - -Apply one or more [filters] to an image. - -```go-html-template -{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} -``` - -Write this in a more functional style using pipes. Hugo applies the filters in the order given. - -```go-html-template -{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} -``` - -Sometimes it can be useful to create the filter chain once and then reuse it. - -```go-html-template -{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} -{{ $image1 := $image1.Filter $filters }} -{{ $image2 := $image2.Filter $filters }} -``` - -### Colors - -`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method. - -```go-html-template -{{ $colors := $image.Colors }} -``` - -This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image. - -### EXIF - -Provides an [EXIF] object containing image metadata. - -You may access EXIF data in JPEG, PNG, TIFF, and WebP images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement. - -```go-html-template -{{ with $image.Exif }} - Date: {{ .Date }} - Lat/Long: {{ .Lat }}/{{ .Long }} - Tags: - {{ range $k, $v := .Tags }} - TAG: {{ $k }}: {{ $v }} - {{ end }} -{{ end }} -``` - -You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed. - -```go-html-template -{{ with $image.Exif }} -
    - {{ with .Date }}
  • Date: {{ .Format "January 02, 2006" }}
    • {{ end }} - {{ with .Tags.ApertureValue }}
  • Aperture: {{ lang.FormatNumber 2 . }}
    • {{ end }} - {{ with .Tags.BrightnessValue }}
  • Brightness: {{ lang.FormatNumber 2 . }}
    • {{ end }} - {{ with .Tags.ExposureTime }}
  • Exposure Time: {{ . }}
    • {{ end }} - {{ with .Tags.FNumber }}
  • F Number: {{ . }}
    • {{ end }} - {{ with .Tags.FocalLength }}
  • Focal Length: {{ . }}
    • {{ end }} - {{ with .Tags.ISOSpeedRatings }}
  • ISO Speed Ratings: {{ . }}
    • {{ end }} - {{ with .Tags.LensModel }}
  • Lens Model: {{ . }}
    • {{ end }} -
-{{ end }} -``` - -#### EXIF methods - -Date -: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function. - -Lat -: (`float64`) Returns the GPS latitude in degrees. - -Long -: (`float64`) Returns the GPS longitude in degrees. - -Tags -: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration]. - -## Image processing options - -The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant. - -### Dimensions - -With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels. - -```go-html-template -{{ $image := $image.Resize "600x" }} -{{ $image := $image.Resize "x400" }} -{{ $image := $image.Resize "600x400" }} -{{ $image := $image.Fit "600x400" }} -{{ $image := $image.Fill "600x400" }} -{{ $image := $image.Crop "600x400" }} -``` - -### Rotation - -Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%: - -```go-html-template -{{ $image = $image.Resize "200x r90" }} -``` - -In the example above, the width represents the desired width _after_ rotation. - -To rotate an image without scaling, use the dimensions of the original image: - -```go-html-template -{{ with .Resources.GetMatch "sunset.jpg" }} - {{ with .Resize (printf "%dx%d r90" .Height .Width) }} +{{ with .Resources.Get "sunset.jpg" }} + {{ with .Resize "400x" }} {{ end }} {{ end }} ``` -In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation. +> [!note] +> Metadata is not preserved during image transformation. Use the `Exif` or `Meta` methods with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images. -### Anchor +Each method serves a specific transformation or metadata requirement: -When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. - -The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration]. - -For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird: - -```go-html-template -{{ $image.Crop "200x100 TopLeft" }} -``` - -If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image. - -### Target format - -By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`. - -```go-html-template -{{ $image.Resize "600x webp" }} -``` - -To convert an image without scaling, use the dimensions of the original image: - -```go-html-template -{{ with .Resources.GetMatch "sunset.jpg" }} - {{ with .Resize (printf "%dx%d webp" .Width .Height) }} - - {{ end }} -{{ end }} -``` - -### Quality - -Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive. - -The default value is 75. You may override the default value in the [site configuration]. - -```go-html-template -{{ $image.Resize "600x webp q50" }} -``` - -### Hint - -Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder. - -Value|Example +Method|Description :--|:-- -`drawing`|Hand or line drawing with high-contrast details -`icon`|Small colorful image -`photo`|Outdoor photograph with natural lighting -`picture`|Indoor photograph such as a portrait -`text`|Image that is primarily text +[`Colors`]|Returns a slice of the most dominant colors using a simple histogram method. +[`Crop`]|Returns a new image resource cropped according to the given processing specification. +[`Exif`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata. +[`Fill`]|Returns a new image resource cropped and resized according to the given processing specification. +[`Filter`]|Applies one or more image filters to the given image resource. +[`Fit`]|Returns a new image resource downscaled to fit according to the given processing specification. +[`Meta`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata. +[`Process`]|Returns a new image resource processed according to the given processing specification. +[`Resize`]|Returns a new image resource resized according to the given processing specification. +{class="!mt-0"} -The default value is `photo`. You may override the default value in the [site configuration]. +Select a method from the table above for syntax and usage examples. -```go-html-template -{{ $image.Resize "600x webp picture" }} +## Performance + +### Caching + +Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache] section of your site configuration. + +If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds: + +```toml +[caches] + [caches.images] + dir = ':cacheDir/images' ``` -### Background color +### Garbage collection -When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image. +If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection: -Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`). - -The default value is `#ffffff` (white). You may override the default value in the [site configuration]. - -```go-html-template -{{ $image.Resize "600x jpg #b31280" }} +```text +hugo --gc ``` -### Resampling filter +### Resource usage -You may specify the resampling filter used when resizing an image. Commonly used resampling filters include: +The time and memory required to process an image increase with the image's dimensions. For example, a `4032x2268` image requires significantly more memory and processing time than a `1920x1080` image. -Filter|Description -:--|:-- -`Box`|Simple and fast averaging filter appropriate for downscaling -`Lanczos`|High-quality resampling filter for photographic images yielding sharp results -`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results -`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom -`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters -`NearestNeighbor`|Fastest resampling filter, no antialiasing - -The default value is `Box`. You may override the default value in the [site configuration]. - -```go-html-template -{{ $image.Resize "600x400 Lanczos" }} -``` - -See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. - -## Image processing examples - -_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://bep.is) (Creative Commons Attribution-Share Alike 4.0 International license)_ - -{{< imgproc path="sunset.jpg" spec="resize 480x" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="fill 120x150 left" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="fit 120x120" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="crop 240x240 center" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="resize 360x q10" alt="A sunset" />}} +If your source images are much larger than the maximum size you intend to publish, consider scaling them down before the build to optimize performance. ## Configuration See [configure imaging](/configuration/imaging). -## Smart cropping of images - -By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or `Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. - -Examples using the sunset image from above: - -{{< imgproc path="sunset.jpg" spec="fill 200x200 smart" alt="A sunset" />}} - -{{< imgproc path="sunset.jpg" spec="crop 200x200 smart" alt="A sunset" />}} - -## Image processing performance consideration - -Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a [CI/CD](g) workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds. - -If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with: - -```sh -hugo --gc -``` - -[`anchor`]: /content-management/image-processing#anchor -[`Colors`]: #colors -[`Crop`]: #crop -[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp -[`Exif`]: #exif -[`Fill`]: #fill -[`Filter`]: #filter -[`Fit`]: #fit -[`lang.FormatNumber`]: /functions/lang/formatnumber/ -[`Process`]: #process -[`Resize`]: #resize -[`time.Format`]: /functions/time/format/ -[`with`]: /functions/go-template/with/ -[EXIF]: https://en.wikipedia.org/wiki/Exif -[filters]: /functions/images/filter/#image-filters -[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing -[site configuration]: /configuration/imaging/ -[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop +[`Colors`]: /methods/resource/colors/ +[`Crop`]: /methods/resource/crop/ +[`Exif`]: /methods/resource/exif/ +[`Fill`]: /methods/resource/fill/ +[`Filter`]: /methods/resource/filter/ +[`Fit`]: /methods/resource/fit/ +[`Height`]: /methods/resource/height/ +[`Meta`]: /methods/resource/meta/ +[`Permalink`]: /methods/resource/permalink/ +[`Process`]: /methods/resource/process/ +[`RelPermalink`]: /methods/resource/relpermalink/ +[`Resize`]: /methods/resource/resize/ +[`Width`]: /methods/resource/width/ diff --git a/docs/content/en/content-management/markdown-attributes.md b/docs/content/en/content-management/markdown-attributes.md index f52a48f17..a27edc012 100644 --- a/docs/content/en/content-management/markdown-attributes.md +++ b/docs/content/en/content-management/markdown-attributes.md @@ -16,19 +16,26 @@ This is a paragraph. {class="foo bar" id="baz"} ``` -With `class` and `id` you can use shorthand notation: +With `class` and `id` attributes you can also use short-form notation: ```text This is a paragraph. {.foo .bar #baz} ``` -Hugo renders both of these to: +Hugo renders both of the examples above to: ```html

This is a paragraph.

``` +With `class` and `id` attributes, whether you use long-form or short-form notation, the resulting values are available in [render hook templates][] via the `Attributes` method. For example: + +```go-html-template +{{ .Attributes.class }} → foo bar +{{ .Attributes.id }} → baz +``` + ## Block elements Update your site configuration to enable Markdown attributes for block-level elements. @@ -82,14 +89,14 @@ In most cases, place the attribute list beneath the markup element. For headings Element|Position of attribute list :--|:-- -blockquote | bottom -fenced code block | right -heading | right -horizontal rule | bottom -image | bottom -list | bottom -paragraph | bottom -table | bottom +blockquote|bottom +fenced code block|right +heading|right +horizontal rule|bottom +image|bottom +list|bottom +paragraph|bottom +table|bottom For example: @@ -106,3 +113,5 @@ This is a paragraph. ```` As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options). + +[render hook templates]: /render-hooks/introduction/ diff --git a/docs/content/en/content-management/page-resources.md b/docs/content/en/content-management/page-resources.md index e8991de6f..c429d8af5 100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@ -188,13 +188,11 @@ the `Name` and `Title` will be assigned to the resource files as follows: |-------------------|-------------------|-----------------------| | checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | | guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | -| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | -| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | +| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | +| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | ## Multilingual -{{< new-in 0.123.0 />}} - By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site. > [!note] diff --git a/docs/content/en/content-management/shortcodes.md b/docs/content/en/content-management/shortcodes.md index 07ad22568..59ac4d651 100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@ -203,7 +203,8 @@ Hugo renders this HTML: In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not. -The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments. +> [!note] +> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments. ## Nesting diff --git a/docs/content/en/content-management/urls.md b/docs/content/en/content-management/urls.md index fda5f198c..737d23367 100644 --- a/docs/content/en/content-management/urls.md +++ b/docs/content/en/content-management/urls.md @@ -40,7 +40,7 @@ Set the `url` in front matter to override the entire path. Use this with either > [!note] > Hugo does not sanitize the `url` front matter field, allowing you to generate: > -> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system. +> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters][]. Hugo throws an error if a file path includes a character reserved by the current operating system. > - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL. If you set both `slug` and `url` in front matter, the `url` value takes precedence. @@ -96,7 +96,7 @@ https://example.org/articles/my-first-article.html #### Leading slashes -With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix. +With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`][]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix. Site type|Front matter `url`|Resulting URL :--|:--|:-- @@ -138,7 +138,7 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_ #### Canonical URLs > [!caution] -> This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release]. +> This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release][]. {class="!mt-6"} If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs. @@ -181,83 +181,80 @@ relativeURLs = true ## Aliases -Create redirects from old URLs to new URLs with aliases: +Aliases allow you to redirect old URLs to new URLs. This is essential for preventing broken links and ensuring that existing bookmarks or external links continue to function when you rename or move content. -- An alias with a leading slash is relative to the `baseURL` -- An alias without a leading slash is relative to the current directory +### Defining aliases -### Examples {#alias-examples} +To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, role, or version. -Change the file name of an existing page, and create an alias from the previous URL to the new URL: - -{{< code-toggle file=content/posts/new-file-name.md fm=true >}} -aliases = ['/posts/previous-file-name'] +{{< code-toggle file=content/examples/example-1.en.md fm=true >}} +title = 'Example 1' +date = 2025-02-02 +aliases = ['/old-url', 'old-name', '../old/path'] {{< /code-toggle >}} -Each of these directory-relative aliases is equivalent to the site-relative alias above: +As shown in the example above, you can use [site-relative](g) paths or [page-relative](g) paths. Page-relative paths can also include directory traversal. Using the file `content/examples/example-1.en.md` as a reference point, here is how Hugo interprets those different path types: -- `previous-file-name` -- `./previous-file-name` -- `../posts/previous-file-name` +Path type|Alias|Server-relative path +:--|:--|:-- +site-relative|`/old-url`|`/en/old-url/` +page-relative|`old-name`|`/en/examples/old-name/` +page-relative|`../old/path`|`/en/old/path/` -You can create more than one alias to the current page: +### Redirection methods -{{< code-toggle file=content/posts/new-file-name.md fm=true >}} -aliases = ['previous-file-name','original-file-name'] -{{< /code-toggle >}} +There are two ways to implement aliases depending on your hosting environment and preferences: client-side redirection and server-side redirection. -In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias: +> [!note] +> Alias data is only generated for [output formats](g) where both [`isHTML`][] and [`permalinkable`][] are `true`. This affects both the creation of client-side redirect files and the results returned by the [`Aliases`][aliases_method] method used in server-side redirection. -{{< code-toggle file=content/posts/new-file-name.de.md fm=true >}} -aliases = ['/de/posts/previous-file-name'] -{{< /code-toggle >}} +#### Client-side redirection -### How aliases work +By default, Hugo uses client-side redirection, generating a small HTML file for every alias. This file contains a `meta http-equiv="refresh"` tag that instructs the browser to navigate to the new URL. This approach is portable across all hosting providers. -Using the first example above, Hugo generates the following site structure: +When using this method, Hugo creates a physical directory and an `index.html` file at each alias location. For example, if a page at `content/posts/new.md` has a page-relative alias of `old-path`, a file is generated at `public/posts/old-path/index.html`. -```text -public/ -├── posts/ -│ ├── new-file-name/ -│ │ └── index.html -│ ├── previous-file-name/ -│ │ └── index.html -│ └── index.html -└── index.html -``` +Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files: -The alias from the previous URL to the new URL is a client-side redirect: - -```html {file="posts/previous-file-name/index.html"} +```go-html-template - + - https://example.org/posts/new-file-name/ - + {{ .Permalink }} + {{ with .OutputFormats.Canonical }}{{ end }} - + ``` -The `link rel="canonical"` tag informs search engines that the new URL is the preferred or "canonical" version of the page. This is crucial for SEO, as it prevents issues with duplicate content by consolidating all ranking signals to a single URL. +To override this, create a file named `alias.html` in your `layouts` directory. This custom template has access to the following context: -The `http-equiv="refresh"` meta tag instructs the web browser to automatically redirect the user to the new URL. This ensures that anyone who accesses the old alias URL is seamlessly taken to the correct, updated page. +`Permalink` +: (`string`) The absolute URL of the destination page. -Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected. +`Page` +: (`page.Page`) The full `Page` object of the destination. -### Customize +#### Server-side redirection -To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the `layouts` directory. The template receives the following context: +Alternatively, you can implement server-side redirection by using the [`Aliases`][aliases_method] method on a `Page` object to generate a single configuration file that the web server processes. This method is more efficient because the redirect happens at the HTTP header level before any page content is processed, whereas a meta refresh requires the browser to download and parse the HTML body before acting. Additionally, server-side redirection improves build and deployment times because Hugo doesn't need to write a physical directory and HTML file for every alias. -Permalink -: The link to the page being aliased. +To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include: -Page -: The Page data for the page being aliased. +- A `_redirects` file for hosting services such as Cloudflare, GitLab Pages, and Netlify. +- An `.htaccess` file for web servers such as Apache and LiteSpeed. + +See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules. + +If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your site configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates. [`baseURL`]: /configuration/all/#baseurl +[`disableAliases`]: /configuration/all/#disablealiases +[`isHTML`]: /configuration/output-formats/#ishtml +[`permalinkable`]: /configuration/output-formats/#permalinkable +[aliases_field]: /content-management/front-matter/#aliases +[aliases_method]: /methods/page/aliases/ +[embedded alias template]: <{{% eturl alias %}}> [removed in a future release]: https://github.com/gohugoio/hugo/issues/4733 [reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions -[source code]: <{{% eturl alias %}}> diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md index db1a2de69..1269c8509 100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@ -143,7 +143,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest To build and install a specific release: ```sh -CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.152.2 +CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.155.3 ``` To build and install at the latest commit on the master branch: diff --git a/docs/content/en/functions/collections/After.md b/docs/content/en/functions/collections/After.md index c8a822846..28acfd63f 100644 --- a/docs/content/en/functions/collections/After.md +++ b/docs/content/en/functions/collections/After.md @@ -1,13 +1,13 @@ --- title: collections.After -description: Slices an array to the items after the Nth item. +description: Returns a slice containing the elements after the first N elements of the given slice. categories: [] keywords: [] params: functions_and_methods: aliases: [after] - returnType: any - signatures: [collections.After INDEX COLLECTION] + returnType: '[]any' + signatures: [collections.After N SLICE] aliases: [/functions/after] --- diff --git a/docs/content/en/functions/collections/Append.md b/docs/content/en/functions/collections/Append.md index cf1d1a3f5..d392a3f83 100644 --- a/docs/content/en/functions/collections/Append.md +++ b/docs/content/en/functions/collections/Append.md @@ -1,15 +1,15 @@ --- title: collections.Append -description: Appends one or more elements to a slice and returns the resulting slice. +description: Returns a slice by adding one or more elements, or an entire second slice, to the end of the given slice. categories: [] keywords: [] params: functions_and_methods: aliases: [append] - returnType: any - signatures: - - collections.Append ELEMENT [ELEMENT...] COLLECTION - - collections.Append COLLECTION1 COLLECTION2 + returnType: '[]any' + signatures: + - collections.Append ELEMENT [ELEMENT...] SLICE + - collections.Append SLICE1 SLICE2 aliases: [/functions/append] --- diff --git a/docs/content/en/functions/collections/Apply.md b/docs/content/en/functions/collections/Apply.md index 7ffe49053..1d4f9bfdc 100644 --- a/docs/content/en/functions/collections/Apply.md +++ b/docs/content/en/functions/collections/Apply.md @@ -1,19 +1,19 @@ --- title: collections.Apply -description: Returns a new collection with each element transformed by the given function. +description: Returns a slice by transforming each element of the given slice using a specific function and parameters. categories: [] keywords: [] params: functions_and_methods: aliases: [apply] returnType: '[]any' - signatures: [collections.Apply COLLECTION FUNCTION PARAM...] + signatures: [collections.Apply SLICE FUNCTION PARAM...] aliases: [/functions/apply] --- -The `apply` function takes three or more arguments, depending on the function being applied to the collection elements. +The `apply` function takes three or more arguments, depending on the function being applied to the slice elements. -The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element. +The first argument is the slice itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the slice element. ```go-html-template {{ $s := slice "hello" "world" }} diff --git a/docs/content/en/functions/collections/Complement.md b/docs/content/en/functions/collections/Complement.md index ce810dc00..c9fc02c86 100644 --- a/docs/content/en/functions/collections/Complement.md +++ b/docs/content/en/functions/collections/Complement.md @@ -1,13 +1,13 @@ --- title: collections.Complement -description: Returns the elements of the last collection that are not in any of the others. +description: Returns a slice by identifying elements in the last given slice that do not appear in any of the preceding slices. categories: [] keywords: [] params: functions_and_methods: aliases: [complement] - returnType: any - signatures: ['collections.Complement COLLECTION [COLLECTION...]'] + returnType: '[]any' + signatures: ['collections.Complement SLICE [SLICE...]'] aliases: [/functions/complement] --- diff --git a/docs/content/en/functions/collections/D.md b/docs/content/en/functions/collections/D.md index 655ced7e3..35386321e 100644 --- a/docs/content/en/functions/collections/D.md +++ b/docs/content/en/functions/collections/D.md @@ -1,19 +1,36 @@ --- title: collections.D -description: Returns a slice of sequentially ordered random integers. +description: Returns a sorted slice of unique random integers based on a given seed, count, and maximum value. categories: [] keywords: [random] params: functions_and_methods: + aliases: [] returnType: '[]int' signatures: [collections.D SEED N HIGH] --- {{< new-in 0.149.0 />}} -The `collections.D` function returns a slice of `N` sequentially ordered unique random integers in the half-open [interval](g) [0, `HIGH`) using the provided [`SEED`](g) value. This function implements J. S. Vitter's Method D[^1] for sequential random sampling, a fast and efficient algorithm for this task. +The `collections.D` function returns a sorted slice of unique random integers in the half-open [interval](g) `[0, HIGH)` using the provided [`SEED`](g) value. The number of elements in the resulting slice is `N` or `HIGH`, whichever is less. -See [this article][] for a detailed explanation. +- `N` and `H` must be integers in the closed interval `[0, 1000000]` +- `SEED` must be an integer in the closed interval `[0, 2^64 - 1]` + +## Return values + +Condition|Return value +:--|:--|:-- +`N <= HIGH`|A sorted random sample of size `N` using J. S. Vitter's [Method D][] for sequential random sampling +`N > HIGH`|The full, sorted range `[0, HIGH)` of size `HIGH` +`N == 0`|An empty slice +`N < 0`|Error +`N > 10^6`|Error +`HIGH == 0`|An empty slice +`HIGH < 0`|Error +`HIGH > 10^6`|Error +`SEED < 0`|Error +{.no-wrap-first-col} ## Examples @@ -27,6 +44,12 @@ The example above generates the _same_ random numbers each time it is called. To {{ collections.D 2 7 42 }} → [3, 11, 19, 25, 32, 33, 38] ``` +When `N` is greater than `HIGH`, this function returns the full, sorted range [0, `HIGH`) of size `HIGH`: + +```go-html-template +{{ collections.D 6 42 7 }} → [0 1 2 3 4 5 6] +``` + A common use case is the selection of random pages from a page collection. For example, to render a list of 5 random pages using the [day of the year][] as the seed value: ```go-html-template @@ -54,11 +77,6 @@ Same result per day|`time.Now.YearDay` Same result per page|`hash.FNV32a .Path` Different result per page per day|`hash.FNV32a (print .Path time.Now.YearDay)` -> [!note] -> The slice created by this function is limited to 1 million elements. - -[^1]: J. S. Vitter, "An efficient algorithm for sequential random sampling," _ACM Trans. Math. Soft._, vol. 13, pp. 58–67, Mar. 1987. - [`collections.Shuffle`]: /functions/collections/shuffle/ [day of the year]: /methods/time/yearday/ -[this article]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/ +[Method D]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/ diff --git a/docs/content/en/functions/collections/Delimit.md b/docs/content/en/functions/collections/Delimit.md index 9d09620aa..b8cba7ff3 100644 --- a/docs/content/en/functions/collections/Delimit.md +++ b/docs/content/en/functions/collections/Delimit.md @@ -1,13 +1,13 @@ --- title: collections.Delimit -description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter. +description: Returns a string by joining the values of the given slice or map with a delimiter. categories: [] keywords: [] params: functions_and_methods: aliases: [delimit] returnType: string - signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] + signatures: ['collections.Delimit SLICE|MAP DELIMITER [LAST]'] aliases: [/functions/delimit] --- diff --git a/docs/content/en/functions/collections/Dictionary.md b/docs/content/en/functions/collections/Dictionary.md index 8aa428106..621adb8a2 100644 --- a/docs/content/en/functions/collections/Dictionary.md +++ b/docs/content/en/functions/collections/Dictionary.md @@ -1,6 +1,6 @@ --- title: collections.Dictionary -description: Returns a map composed of the given key-value pairs. +description: Returns a map created from the given key-value pairs. categories: [] keywords: [] params: diff --git a/docs/content/en/functions/collections/First.md b/docs/content/en/functions/collections/First.md index d7bd565b9..2df5ec059 100644 --- a/docs/content/en/functions/collections/First.md +++ b/docs/content/en/functions/collections/First.md @@ -1,13 +1,13 @@ --- title: collections.First -description: Returns the given collection, limited to the first N elements. +description: Returns the first N elements of the given slice or string. categories: [] keywords: [] params: functions_and_methods: aliases: [first] - returnType: any - signatures: [collections.First N COLLECTION] + returnType: 'any' + signatures: [collections.First N SLICE|STRING] aliases: [/functions/first] --- @@ -39,7 +39,7 @@ To use the `collections.First` function with a page collection: {{ end }} ``` -Set `N` to zero to return an empty collection: +Set `N` to zero to return an empty slice: ```go-html-template {{ $emptyPageCollection := first 0 .Pages }} diff --git a/docs/content/en/functions/collections/Group.md b/docs/content/en/functions/collections/Group.md index 4b269b92a..3542e3f55 100644 --- a/docs/content/en/functions/collections/Group.md +++ b/docs/content/en/functions/collections/Group.md @@ -1,12 +1,12 @@ --- title: collections.Group -description: Groups the given page collection by the given key. +description: Returns a map by grouping the given page collection (slice) by a specific key. categories: [] keywords: [] params: functions_and_methods: aliases: [group] - returnType: any + returnType: page.PageGroup signatures: [collections.Group KEY PAGES] aliases: [/functions/group] --- diff --git a/docs/content/en/functions/collections/In.md b/docs/content/en/functions/collections/In.md index e94b4b0ed..3ae72f1da 100644 --- a/docs/content/en/functions/collections/In.md +++ b/docs/content/en/functions/collections/In.md @@ -1,33 +1,21 @@ --- title: collections.In -description: Reports whether the given value is a member of the given set. +description: Reports whether a value exists within the given slice or string. categories: [] keywords: [] params: functions_and_methods: aliases: [in] returnType: bool - signatures: [collections.In SET VALUE] + signatures: [collections.In SLICE|STRING VALUE] aliases: [/functions/in] --- -The `SET` can be an [array](g), [slice](g), or [string](g). - ```go-html-template {{ $s := slice "a" "b" "c" }} {{ in $s "b" }} → true ``` -```go-html-template -{{ $s := slice 1 2 3 }} -{{ in $s 2 }} → true -``` - -```go-html-template -{{ $s := slice 1.11 2.22 3.33 }} -{{ in $s 2.22 }} → true -``` - ```go-html-template {{ $s := "abc" }} {{ in $s "b" }} → true diff --git a/docs/content/en/functions/collections/IndexFunction.md b/docs/content/en/functions/collections/IndexFunction.md index 248595961..f7155c53d 100644 --- a/docs/content/en/functions/collections/IndexFunction.md +++ b/docs/content/en/functions/collections/IndexFunction.md @@ -1,13 +1,13 @@ --- title: collections.Index -description: Returns the object, element, or value associated with the given key or keys. +description: Returns an element or value from the given slice or map at the specified key(s). categories: [] keywords: [] params: functions_and_methods: aliases: [index] returnType: any - signatures: [collections.Index COLLECTION KEY...] + signatures: [collections.Index SLICE|MAP KEY...] aliases: [/functions/index,/functions/index-function] --- diff --git a/docs/content/en/functions/collections/Intersect.md b/docs/content/en/functions/collections/Intersect.md index ffa9c8196..3f7d9dea3 100644 --- a/docs/content/en/functions/collections/Intersect.md +++ b/docs/content/en/functions/collections/Intersect.md @@ -1,13 +1,13 @@ --- title: collections.Intersect -description: Returns the common elements of two arrays or slices, in the same order as the first array. +description: Returns a slice containing the common elements found in two given slices, in the same order as the first slice. categories: [] keywords: [] params: functions_and_methods: aliases: [intersect] - returnType: any - signatures: [collections.Intersect SET1 SET2] + returnType: '[]any' + signatures: [collections.Intersect SLICE1 SLICE2] aliases: [/functions/intersect] --- diff --git a/docs/content/en/functions/collections/IsSet.md b/docs/content/en/functions/collections/IsSet.md index d254abf1d..405aa92af 100644 --- a/docs/content/en/functions/collections/IsSet.md +++ b/docs/content/en/functions/collections/IsSet.md @@ -1,13 +1,13 @@ --- title: collections.IsSet -description: Reports whether the key exists within the collection. +description: Reports whether a specific key or index exists in the given map or slice. categories: [] keywords: [] params: functions_and_methods: aliases: [isset] returnType: bool - signatures: [collections.IsSet COLLECTION KEY] + signatures: [collections.IsSet MAP|SLICE KEY|INDEX] aliases: [/functions/isset] --- diff --git a/docs/content/en/functions/collections/KeyVals.md b/docs/content/en/functions/collections/KeyVals.md index bd58caea0..12d0a007c 100644 --- a/docs/content/en/functions/collections/KeyVals.md +++ b/docs/content/en/functions/collections/KeyVals.md @@ -1,6 +1,6 @@ --- title: collections.KeyVals -description: Returns a KeyVals struct. +description: Returns a KeyVals struct by pairing a given key and values. categories: [] keywords: [] params: diff --git a/docs/content/en/functions/collections/Last.md b/docs/content/en/functions/collections/Last.md index 9ac60de15..9c0dc6f15 100644 --- a/docs/content/en/functions/collections/Last.md +++ b/docs/content/en/functions/collections/Last.md @@ -1,13 +1,13 @@ --- title: collections.Last -description: Returns the given collection, limited to the last N elements. +description: Returns the last N elements of the given slice or string. categories: [] keywords: [] params: functions_and_methods: aliases: [last] - returnType: any - signatures: [collections.Last N COLLECTION] + returnType: 'any' + signatures: [collections.Last N SLICE|STRING] aliases: [/functions/last] --- @@ -39,7 +39,7 @@ To use the `collections.Last` function with a page collection: {{ end }} ``` -Set `N` to zero to return an empty collection: +Set `N` to zero to return an empty slice: ```go-html-template {{ $emptyPageCollection := last 0 .Pages }} diff --git a/docs/content/en/functions/collections/Merge.md b/docs/content/en/functions/collections/Merge.md index c9998be39..d86b58c1d 100644 --- a/docs/content/en/functions/collections/Merge.md +++ b/docs/content/en/functions/collections/Merge.md @@ -1,12 +1,12 @@ --- title: collections.Merge -description: Returns the result of merging two or more maps. +description: Returns a map by combining two or more given maps. categories: [] keywords: [] params: functions_and_methods: aliases: [merge] - returnType: any + returnType: map[string]any signatures: [collections.Merge MAP MAP...] aliases: [/functions/merge] --- diff --git a/docs/content/en/functions/collections/NewScratch.md b/docs/content/en/functions/collections/NewScratch.md index 34fc7f5d6..82f9a3c9b 100644 --- a/docs/content/en/functions/collections/NewScratch.md +++ b/docs/content/en/functions/collections/NewScratch.md @@ -7,7 +7,7 @@ params: functions_and_methods: aliases: [newScratch] returnType: maps.Scratch - signatures: [collections.NewScratch ] + signatures: [collections.NewScratch] --- Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. diff --git a/docs/content/en/functions/collections/Querify.md b/docs/content/en/functions/collections/Querify.md index fd74935b7..a91393787 100644 --- a/docs/content/en/functions/collections/Querify.md +++ b/docs/content/en/functions/collections/Querify.md @@ -1,13 +1,13 @@ --- title: collections.Querify -description: Returns a URL query string composed of the given key-value pairs, encoded and sorted by key. +description: Returns a URL query string from the given map, slice, or sequence of key-value pairs. categories: [] keywords: [] params: functions_and_methods: aliases: [querify] returnType: string - signatures: ['collections.Querify [VALUE...]'] + signatures: [collections.Querify MAP|SLICE|KEY VALUE...] aliases: [/functions/querify] --- diff --git a/docs/content/en/functions/collections/Reverse.md b/docs/content/en/functions/collections/Reverse.md index ee455939c..e44358375 100644 --- a/docs/content/en/functions/collections/Reverse.md +++ b/docs/content/en/functions/collections/Reverse.md @@ -1,13 +1,13 @@ --- title: collections.Reverse -description: Reverses the order of a collection. +description: Returns a slice by reversing the order of elements in the given slice. categories: [] keywords: [] params: functions_and_methods: aliases: [] - returnType: any - signatures: [collections.Reverse COLLECTION] + returnType: '[]any' + signatures: [collections.Reverse SLICE] aliases: [/functions/collections.reverse] --- diff --git a/docs/content/en/functions/collections/Seq.md b/docs/content/en/functions/collections/Seq.md index d3fb34bfa..93cd5ccf7 100644 --- a/docs/content/en/functions/collections/Seq.md +++ b/docs/content/en/functions/collections/Seq.md @@ -1,6 +1,6 @@ --- title: collections.Seq -description: Returns a slice of integers. +description: Returns a slice of integers starting from 1 or a given value, incrementing by 1 or a given value, and ending at a given value. categories: [] keywords: [] params: diff --git a/docs/content/en/functions/collections/Shuffle.md b/docs/content/en/functions/collections/Shuffle.md index d346a644d..cdaea0ac9 100644 --- a/docs/content/en/functions/collections/Shuffle.md +++ b/docs/content/en/functions/collections/Shuffle.md @@ -1,13 +1,13 @@ --- title: collections.Shuffle -description: Returns a random permutation of a given array or slice. +description: Returns a slice by randomizing the element order of the given slice. categories: [] keywords: [random] params: functions_and_methods: aliases: [shuffle] - returnType: any - signatures: [collections.Shuffle COLLECTION] + returnType: '[]any' + signatures: [collections.Shuffle SLICE] aliases: [/functions/shuffle] --- diff --git a/docs/content/en/functions/collections/Slice.md b/docs/content/en/functions/collections/Slice.md index 76180fabe..bcf9b9c77 100644 --- a/docs/content/en/functions/collections/Slice.md +++ b/docs/content/en/functions/collections/Slice.md @@ -1,12 +1,12 @@ --- title: collections.Slice -description: Returns a slice composed of the given values. +description: Returns a slice created from the given values. categories: [] keywords: [] params: functions_and_methods: aliases: [slice] - returnType: any + returnType: '[]any' signatures: ['collections.Slice [VALUE...]'] aliases: [/functions/slice] --- diff --git a/docs/content/en/functions/collections/Sort.md b/docs/content/en/functions/collections/Sort.md index 67e5de5cb..c48610923 100644 --- a/docs/content/en/functions/collections/Sort.md +++ b/docs/content/en/functions/collections/Sort.md @@ -1,13 +1,13 @@ --- title: collections.Sort -description: Sorts slices, maps, and page collections. +description: Returns a sorted map or slice by reordering the given collection by a key and order. categories: [] keywords: [] params: functions_and_methods: aliases: [sort] returnType: any - signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] + signatures: ['collections.Sort MAP|SLICE [KEY] [ORDER]'] aliases: [/functions/sort] --- diff --git a/docs/content/en/functions/collections/SymDiff.md b/docs/content/en/functions/collections/SymDiff.md index 8974d2d3e..a895da012 100644 --- a/docs/content/en/functions/collections/SymDiff.md +++ b/docs/content/en/functions/collections/SymDiff.md @@ -1,13 +1,13 @@ --- title: collections.SymDiff -description: Returns the symmetric difference of two collections. +description: Returns a slice containing the symmetric difference of two given slices. categories: [] keywords: [] params: functions_and_methods: aliases: [symdiff] - returnType: any - signatures: [COLLECTION | collections.SymDiff COLLECTION] + returnType: '[]any' + signatures: [SLICE1 | collections.SymDiff SLICE2] aliases: [/functions/symdiff] --- diff --git a/docs/content/en/functions/collections/Union.md b/docs/content/en/functions/collections/Union.md index ce6d6d010..53e94accc 100644 --- a/docs/content/en/functions/collections/Union.md +++ b/docs/content/en/functions/collections/Union.md @@ -1,26 +1,23 @@ --- title: collections.Union -description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. +description: Returns a slice containing the unique elements from two given slices. categories: [] keywords: [] params: functions_and_methods: aliases: [union] - returnType: any - signatures: [collections.Union SET1 SET2] + returnType: '[]any' + signatures: [collections.Union SLICE1 SLICE2] aliases: [/functions/union] --- -Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. + ```go-html-template {{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5] - -{{ union (slice 1 2 3) nil }} → [1 2 3] - -{{ union nil (slice 1 2 3) }} → [1 2 3] - -{{ union nil nil }} → [] +{{ union (slice 1 2 3) nil }} → [1 2 3] +{{ union nil (slice 1 2 3) }} → [1 2 3] +{{ union nil nil }} → [] ``` ## OR filter in where query diff --git a/docs/content/en/functions/collections/Uniq.md b/docs/content/en/functions/collections/Uniq.md index d19298b21..664c8517d 100644 --- a/docs/content/en/functions/collections/Uniq.md +++ b/docs/content/en/functions/collections/Uniq.md @@ -1,13 +1,13 @@ --- title: collections.Uniq -description: Returns the given collection, removing duplicate elements. +description: Returns a slice by removing duplicate elements from the given slice. categories: [] keywords: [] params: functions_and_methods: aliases: [uniq] - returnType: any - signatures: [collections.Uniq COLLECTION] + returnType: '[]any' + signatures: [collections.Uniq SLICE] aliases: [/functions/uniq] --- diff --git a/docs/content/en/functions/collections/Where.md b/docs/content/en/functions/collections/Where.md index 84fd1d21e..a08412621 100644 --- a/docs/content/en/functions/collections/Where.md +++ b/docs/content/en/functions/collections/Where.md @@ -1,22 +1,22 @@ --- title: collections.Where -description: Returns the given collection, removing elements that do not satisfy the comparison condition. +description: Returns a slice by filtering the given slice based on a key, operator, and value. categories: [] keywords: [] params: functions_and_methods: aliases: [where] - returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] + returnType: '[]any' + signatures: ['collections.Where SLICE KEY [OPERATOR] VALUE'] aliases: [/functions/where] --- -The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments: +The `where` function returns the given slice, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments: ```text -collections.Where COLLECTION KEY [OPERATOR] VALUE - -------------------- - comparison condition +collections.Where SLICE KEY [OPERATOR] VALUE + -------------------- + comparison condition ``` Hugo will test for equality if you do not provide an `OPERATOR` argument. For example: @@ -30,15 +30,15 @@ Hugo will test for equality if you do not provide an `OPERATOR` argument. For ex The where function takes three or four arguments. The `OPERATOR` argument is optional. -COLLECTION -: (`any`) A [page collection](g) or a [slice](g) of [maps](g). +SLICE +: (`[]any`) A [page collection](g) or a [slice](g) of [maps](g). KEY : (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain](g) the subkey as shown below: -```go-html-template -{{ $result := where .Site.RegularPages "Params.foo" "bar" }} -``` + ```go-html-template + {{ $result := where .Site.RegularPages "Params.foo" "bar" }} + ``` OPERATOR : (`string`) The logical comparison [operator](#operators). @@ -133,7 +133,7 @@ Compare the value of the given field to a [`bool`](g): Compare a [`scalar`](g) to a [`slice`](g). -For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow": +For example, to return a slice of pages where the `color` page parameter is either "red" or "yellow": ```go-html-template {{ $fruit := where site.RegularPages "Section" "eq" "fruit" }} @@ -142,7 +142,7 @@ For example, to return a collection of pages where the `color` page parameter is {{ $pages := where $fruit "Params.color" "in" $colors }} ``` -To return a collection of pages where the "color" page parameter is neither "red" nor "yellow": +To return a slice of pages where the "color" page parameter is neither "red" nor "yellow": ```go-html-template {{ $fruit := where site.RegularPages "Section" "eq" "fruit" }} @@ -153,9 +153,9 @@ To return a collection of pages where the "color" page parameter is neither "red ## Intersection comparison -Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms. +Compare a `slice` to a `slice`, returning elements with common values. This is frequently used when comparing taxonomy terms. -For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": +For example, to return a slice of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": ```go-html-template {{ $books := where site.RegularPages "Section" "eq" "books" }} @@ -166,7 +166,7 @@ For example, to return a collection of pages where any of the terms in the "genr ## Regular expression comparison -To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor": +To return a slice of pages where the "author" page parameter begins with either "victor" or "Victor": ```go-html-template {{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} @@ -175,7 +175,7 @@ To return a collection of pages where the "author" page parameter begins with ei {{% include "/_common/functions/regular-expressions.md" %}} > [!note] -> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. +> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice. ## Date comparison @@ -183,7 +183,7 @@ To return a collection of pages where the "author" page parameter begins with ei There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons. -For example, to return a collection of pages that were created before the current year: +For example, to return a slice of pages that were created before the current year: ```go-html-template {{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }} @@ -208,14 +208,14 @@ eventDate = 2024-04-01 +++ ``` -To return a collection of future events: +To return a slice of future events: ```go-html-template {{ $events := where .Site.RegularPages "Type" "events" }} {{ $futureEvents := where $events "Params.eventDate" "gt" now }} ``` -When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection: +When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging over the slice: ```go-html-template {{ $events := where .Site.RegularPages "Type" "events" }} @@ -229,13 +229,13 @@ When working with YAML or JSON, or quoted TOML values, custom dates are strings; ## Nil comparison -To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`: +To return a slice of pages where the "color" parameter is present in front matter, compare to `nil`: ```go-html-template {{ $pages := where .Site.RegularPages "Params.color" "ne" nil }} ``` -To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`: +To return a slice of pages where the "color" parameter is not present in front matter, compare to `nil`: ```go-html-template {{ $pages := where .Site.RegularPages "Params.color" "eq" nil }} @@ -368,9 +368,9 @@ Is rendered to: To exclude a page with an undefined field from a boolean _inequality_ test: -1. Create a collection using a boolean comparison -1. Create a collection using a nil comparison -1. Subtract the second collection from the first collection using the [`collections.Complement`] function. +1. Create a slice using a boolean comparison +1. Create a slice using a nil comparison +1. Subtract the second slice from the first slice using the [`collections.Complement`] function. This template: diff --git a/docs/content/en/functions/collections/_index.md b/docs/content/en/functions/collections/_index.md index c7b856f4f..0f07db527 100644 --- a/docs/content/en/functions/collections/_index.md +++ b/docs/content/en/functions/collections/_index.md @@ -1,7 +1,7 @@ --- title: Collections functions linkTitle: collections -description: Use these functions to work with arrays, slices, maps, and page collections. +description: Use these functions to manipulate and query maps, slices, and strings. categories: [] keywords: [] --- diff --git a/docs/content/en/functions/css/Quoted.md b/docs/content/en/functions/css/Quoted.md index ef3ff65a6..58784f3e6 100644 --- a/docs/content/en/functions/css/Quoted.md +++ b/docs/content/en/functions/css/Quoted.md @@ -15,7 +15,7 @@ params: > [!note] > This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function. -When when passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Quoted` function to explicitly indicate that the value must be treated as a quoted string. +When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Quoted` function to explicitly indicate that the value must be treated as a quoted string. For example: diff --git a/docs/content/en/functions/css/Sass.md b/docs/content/en/functions/css/Sass.md index c02b4ee42..407558c80 100644 --- a/docs/content/en/functions/css/Sass.md +++ b/docs/content/en/functions/css/Sass.md @@ -10,10 +10,11 @@ params: signatures: ['css.Sass [OPTIONS] RESOURCE'] --- -{{< new-in 0.128.0 />}} - 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. +> [!warning] +> The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead. + Sass has two forms of syntax: [SCSS][] and [indented][]. Hugo supports both. ## Options @@ -47,6 +48,9 @@ targetPath 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`. + > [!warning] + > The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead. + 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/). @@ -58,7 +62,7 @@ vars @use "hugo:vars" as v; ``` - When when passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the [`css.Quoted`][] or [`css.Unquoted`][] function to explicitly indicate a value's type. + When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the [`css.Quoted`][] or [`css.Unquoted`][] function to explicitly indicate a value's type. ## Example @@ -86,7 +90,7 @@ vars ## 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]. +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][]. Use the latest features of the Sass language by installing Dart Sass in your development and production environments. @@ -96,7 +100,7 @@ Dart Sass is compatible with Hugo v0.114.0 and later. If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass. -If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass. +If you install Hugo as a [Snap package][] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass. [^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. @@ -121,23 +125,24 @@ Run `hugo env` to list the active transpilers. ### Installing in a production environment -To use Dart Sass with Hugo on a CI/CD platform like GitHub Pages, GitLab Pages, or Netlify, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files. +To use Dart Sass with Hugo on a [CI/CD](g) platform, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files. There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if: - You have not changed Hugo's default asset cache location. - You have not set [`useResourceCacheWhen`][] to never in your sites configuration. -By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD service, so it doesn't need to run the Sass compilation itself. +By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD platform, so it doesn't need to run the Sass compilation itself. For examples of how to install Dart Sass in a production environment, see these hosting guides: -- [Cloudflare] -- [GitHub Pages] -- [GitLab Pages] -- [Netlify] -- [Render] -- [Vercel] +- [Cloudflare][] +- [GitHub Pages][] +- [GitLab Pages][] +- [Netlify][] +- [Render][] +- [SourceHut][] +- [Vercel][] [`css.Quoted`]: /functions/css/quoted/ [`css.Unquoted`]: /functions/css/unquoted/ @@ -146,6 +151,7 @@ For examples of how to install Dart Sass in a production environment, see these [brew.sh]: https://brew.sh/ [chocolatey.org]: https://community.chocolatey.org/packages/sass [Cloudflare]: /host-and-deploy/host-on-cloudflare/ +[Dart Sass]: https://sass-lang.com/dart-sass/ [GitHub Pages]: /host-and-deploy/host-on-github-pages/ [GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/ [indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax @@ -155,5 +161,8 @@ For examples of how to install Dart Sass in a production environment, see these [Render]: /host-and-deploy/host-on-render/ [scoop.sh]: https://scoop.sh/#/apps?q=sass [SCSS]: https://sass-lang.com/documentation/syntax#scss +[Snap package]: https://snapcraft.io/hugo [snapcraft.io]: https://snapcraft.io/dart-sass +[SourceHut]: /host-and-deploy/host-on-sourcehut-pages/ +[v0.153.0]: https://github.com/gohugoio/hugo/releases/tag/v0.153.0 [Vercel]: /host-and-deploy/host-on-vercel/ diff --git a/docs/content/en/functions/css/Unquoted.md b/docs/content/en/functions/css/Unquoted.md index c47059b7b..9800b9de0 100644 --- a/docs/content/en/functions/css/Unquoted.md +++ b/docs/content/en/functions/css/Unquoted.md @@ -15,7 +15,7 @@ params: > [!note] > This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function. -When when passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Unquoted` function to explicitly indicate that the value must not be treated as a quoted string. +When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Unquoted` function to explicitly indicate that the value must not be treated as a quoted string. For example: diff --git a/docs/content/en/functions/data/GetCSV.md b/docs/content/en/functions/data/GetCSV.md deleted file mode 100644 index 8d3f8a7d9..000000000 --- a/docs/content/en/functions/data/GetCSV.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: data.GetCSV -description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist. -categories: [] -keywords: [] -params: - functions_and_methods: - aliases: [getCSV] - returnType: '[][]string' - signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] -expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 ---- - -{{< deprecated-in 0.123.0 >}} -Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). - -See the [remote data example]. - -[`transform.Unmarshal`]: /functions/transform/unmarshal/ -[remote data example]: /functions/resources/getremote/#remote-data -{{< /deprecated-in >}} - -Given the following directory structure: - -```text -my-project/ -└── other-files/ - └── pets.csv -``` - -Access the data with either of the following: - -```go-html-template -{{ $data := getCSV "," "other-files/pets.csv" }} -{{ $data := getCSV "," "other-files/" "pets.csv" }} -``` - -> [!note] -> When working with local data, the file path is relative to the working directory. -> -> You must not place CSV files in the project's `data` directory. - -Access remote data with either of the following: - -```go-html-template -{{ $data := getCSV "," "https://example.org/pets.csv" }} -{{ $data := getCSV "," "https://example.org/" "pets.csv" }} -``` - -The resulting data structure is an array of arrays: - -```json -[ - ["name","type","breed","age"], - ["Spot","dog","Collie","3"], - ["Felix","cat","Malicious","7"] -] -``` - -## Options - -Add headers to the request by providing an options map: - -```go-html-template -{{ $opts := dict "Authorization" "Bearer abcd" }} -{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} -``` - -Add multiple headers using a slice: - -```go-html-template -{{ $opts := dict "X-List" (slice "a" "b" "c") }} -{{ $data := getCSV "," "https://example.org/pets.csv" $opts }} -``` - -## Global resource alternative - -Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource. - -```text -my-project/ -└── assets/ - └── data/ - └── pets.csv -``` - -```go-html-template -{{ $data := dict }} -{{ $p := "data/pets.csv" }} -{{ with resources.Get $p }} - {{ $opts := dict "delimiter" "," }} - {{ $data = . | transform.Unmarshal $opts }} -{{ else }} - {{ errorf "Unable to get resource %q" $p }} -{{ end }} -``` - -## Page resource alternative - -Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource. - -```text -my-project/ -└── content/ - └── posts/ - └── my-pets/ - ├── index.md - └── pets.csv -``` - -```go-html-template -{{ $data := dict }} -{{ $p := "pets.csv" }} -{{ with .Resources.Get $p }} - {{ $opts := dict "delimiter" "," }} - {{ $data = . | transform.Unmarshal $opts }} -{{ else }} - {{ errorf "Unable to get resource %q" $p }} -{{ end }} -``` - -## Remote resource alternative - -Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. - -```go-html-template -{{ $data := dict }} -{{ $url := "https://example.org/pets.csv" }} -{{ with try (resources.GetRemote $url) }} - {{ with .Err }} - {{ errorf "%s" . }} - {{ else with .Value }} - {{ $opts := dict "delimiter" "," }} - {{ $data = . | transform.Unmarshal $opts }} - {{ else }} - {{ errorf "Unable to get remote resource %q" $url }} - {{ end }} -{{ end }} -``` - -[`resources.GetRemote`]: /functions/resources/getremote/ - - -[`transform.Unmarshal`]: /functions/transform/unmarshal/ - diff --git a/docs/content/en/functions/data/GetJSON.md b/docs/content/en/functions/data/GetJSON.md deleted file mode 100644 index d3aafe94d..000000000 --- a/docs/content/en/functions/data/GetJSON.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: data.GetJSON -description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist. -categories: [] -keywords: [] -params: - functions_and_methods: - aliases: [getJSON] - returnType: any - signatures: ['data.GetJSON INPUT... [OPTIONS]'] -expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 ---- - -{{< deprecated-in 0.123.0 >}} -Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g). - -See the [remote data example]. - -[`transform.Unmarshal`]: /functions/transform/unmarshal/ -[remote data example]: /functions/resources/getremote/#remote-data -{{< /deprecated-in >}} - -Given the following directory structure: - -```text -my-project/ -└── other-files/ - └── books.json -``` - -Access the data with either of the following: - -```go-html-template -{{ $data := getJSON "other-files/books.json" }} -{{ $data := getJSON "other-files/" "books.json" }} -``` - -> [!note] -> When working with local data, the file path is relative to the working directory. - -Access remote data with either of the following: - -```go-html-template -{{ $data := getJSON "https://example.org/books.json" }} -{{ $data := getJSON "https://example.org/" "books.json" }} -``` - -The resulting data structure is a JSON object: - -```json -[ - { - "author": "Victor Hugo", - "rating": 5, - "title": "Les Misérables" - }, - { - "author": "Victor Hugo", - "rating": 4, - "title": "The Hunchback of Notre Dame" - } -] -``` - -## Options - -Add headers to the request by providing an options map: - -```go-html-template -{{ $opts := dict "Authorization" "Bearer abcd" }} -{{ $data := getJSON "https://example.org/books.json" $opts }} -``` - -Add multiple headers using a slice: - -```go-html-template -{{ $opts := dict "X-List" (slice "a" "b" "c") }} -{{ $data := getJSON "https://example.org/books.json" $opts }} -``` - -## Global resource alternative - -Consider using the [`resources.Get`](/functions/resources/get/) function with [`transform.Unmarshal`] when accessing a global resource. - -```text -my-project/ -└── assets/ - └── data/ - └── books.json -``` - -```go-html-template -{{ $data := dict }} -{{ $p := "data/books.json" }} -{{ with resources.Get $p }} - {{ $data = . | transform.Unmarshal }} -{{ else }} - {{ errorf "Unable to get resource %q" $p }} -{{ end }} -``` - -## Page resource alternative - -Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource. - -```text -my-project/ -└── content/ - └── posts/ - └── reading-list/ - ├── books.json - └── index.md -``` - -```go-html-template -{{ $data := dict }} -{{ $p := "books.json" }} -{{ with .Resources.Get $p }} - {{ $data = . | transform.Unmarshal }} -{{ else }} - {{ errorf "Unable to get resource %q" $p }} -{{ end }} -``` - -## Remote resource alternative - -Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control. - -```go-html-template -{{ $data := dict }} -{{ $url := "https://example.org/books.json" }} -{{ with try (resources.GetRemote $url) }} - {{ with .Err }} - {{ errorf "%s" . }} - {{ else with .Value }} - {{ $data = . | transform.Unmarshal }} - {{ else }} - {{ errorf "Unable to get remote resource %q" $url }} - {{ end }} -{{ end }} -``` - -[`resources.GetRemote`]: /functions/resources/getremote/ - - -[`transform.Unmarshal`]: /functions/transform/unmarshal/ - diff --git a/docs/content/en/functions/data/_index.md b/docs/content/en/functions/data/_index.md deleted file mode 100644 index 2177bc528..000000000 --- a/docs/content/en/functions/data/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Data functions -linkTitle: data -description: Use these functions to read local or remote data files. -categories: [] -keywords: [] ---- diff --git a/docs/content/en/functions/fmt/Warnidf.md b/docs/content/en/functions/fmt/Warnidf.md index 79ebf81e6..7b68cd88b 100644 --- a/docs/content/en/functions/fmt/Warnidf.md +++ b/docs/content/en/functions/fmt/Warnidf.md @@ -11,8 +11,6 @@ params: aliases: [/functions/warnidf] --- -{{< new-in 0.123.0 />}} - {{% include "/_common/functions/fmt/format-string.md" %}} The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration. diff --git a/docs/content/en/functions/go-template/and.md b/docs/content/en/functions/go-template/and.md index 77906df52..016a8cf84 100644 --- a/docs/content/en/functions/go-template/and.md +++ b/docs/content/en/functions/go-template/and.md @@ -12,6 +12,8 @@ params: {{% include "/_common/functions/truthy-falsy.md" %}} +The `and` function evaluates the arguments from left to right, and returns when the result is determined. + ```go-html-template {{ and 1 0 "" }} → 0 (int) {{ and 1 false 0 }} → false (bool) @@ -19,4 +21,8 @@ params: {{ and 1 2 3 }} → 3 (int) {{ and "a" "b" "c" }} → c (string) {{ and "a" 1 true }} → true (bool) + +{{ and false (math.Div 1 0) }} → false (bool) ``` + +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/or.md b/docs/content/en/functions/go-template/or.md index 2f55fe479..1b85a5df0 100644 --- a/docs/content/en/functions/go-template/or.md +++ b/docs/content/en/functions/go-template/or.md @@ -12,13 +12,17 @@ params: {{% include "/_common/functions/truthy-falsy.md" %}} -```go-html-template -{{ or 0 1 2 }} → 1 -{{ or false "a" 1 }} → a -{{ or 0 true "a" }} → true +The `or` function evaluates the arguments from left to right, and returns when the result is determined. -{{ or false "" 0 }} → 0 -{{ or 0 "" false }} → false +```go-html-template +{{ or 0 1 2 }} → 1 (int) +{{ or false "a" 1 }} → a (string) +{{ or 0 true "a" }} → true (bool) + +{{ or false "" 0 }} → 0 (int) +{{ or 0 "" false }} → false (bool) + +{{ or true (math.Div 1 0) }} → true (bool) ``` {{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index 3c50068f1..07d95259a 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -192,8 +192,6 @@ 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 diff --git a/docs/content/en/functions/hugo/Generator.md b/docs/content/en/functions/hugo/Generator.md index 1070d27ac..de3b5d46a 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 }} → +{{ hugo.Generator }} → ``` diff --git a/docs/content/en/functions/hugo/IsMultihost.md b/docs/content/en/functions/hugo/IsMultihost.md index 605afa79a..a84ae4940 100644 --- a/docs/content/en/functions/hugo/IsMultihost.md +++ b/docs/content/en/functions/hugo/IsMultihost.md @@ -10,8 +10,6 @@ params: signatures: [hugo.IsMultihost] --- -{{< new-in 0.124.0 />}} - Site configuration: {{< code-toggle file=hugo >}} diff --git a/docs/content/en/functions/hugo/IsMultilingual.md b/docs/content/en/functions/hugo/IsMultilingual.md index 85fc6550f..d8c73f7d5 100644 --- a/docs/content/en/functions/hugo/IsMultilingual.md +++ b/docs/content/en/functions/hugo/IsMultilingual.md @@ -10,8 +10,6 @@ params: signatures: [hugo.IsMultilingual] --- -{{< new-in 0.124.0 />}} - Site configuration: {{< code-toggle file=hugo >}} diff --git a/docs/content/en/functions/hugo/Version.md b/docs/content/en/functions/hugo/Version.md index babd4238a..380b21eba 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.152.2 +{{ hugo.Version }} → 0.155.3 ``` diff --git a/docs/content/en/functions/images/AutoOrient.md b/docs/content/en/functions/images/AutoOrient.md index 4563e69f2..d81dfbbab 100644 --- a/docs/content/en/functions/images/AutoOrient.md +++ b/docs/content/en/functions/images/AutoOrient.md @@ -1,6 +1,6 @@ --- title: images.AutoOrient -description: Returns an image filter that rotates and flips an image as needed per its EXIF orientation tag. +description: Returns an image filter that rotates and flips an image as needed per its Exif orientation tag. categories: [] keywords: [] params: diff --git a/docs/content/en/functions/images/Dither.md b/docs/content/en/functions/images/Dither.md index eab7743f7..0110a18f4 100644 --- a/docs/content/en/functions/images/Dither.md +++ b/docs/content/en/functions/images/Dither.md @@ -10,12 +10,10 @@ params: signatures: ['images.Dither [OPTIONS]'] --- -{{< new-in 0.123.0 />}} - ## Options colors -: (`string array`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`). +: (`[]string`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`). [hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color diff --git a/docs/content/en/functions/images/Filter.md b/docs/content/en/functions/images/Filter.md index 1f2c268be..57a1d5934 100644 --- a/docs/content/en/functions/images/Filter.md +++ b/docs/content/en/functions/images/Filter.md @@ -2,7 +2,7 @@ title: images.Filter description: Applies one or more image filters to the given image resource. categories: [] -keywords: [] +keywords: [filter] params: functions_and_methods: aliases: [] diff --git a/docs/content/en/functions/images/Process.md b/docs/content/en/functions/images/Process.md index a5aefc74c..04f109b40 100644 --- a/docs/content/en/functions/images/Process.md +++ b/docs/content/en/functions/images/Process.md @@ -1,98 +1,36 @@ --- title: images.Process -description: Returns an image filter that processes the given image using the given specification. +description: Returns an image filter that processes an image according to the given processing specification. categories: [] -keywords: [] +keywords: [process] params: functions_and_methods: aliases: [] returnType: images.filter - signatures: [images.Process SPEC] + signatures: [images.Process SPECIFICATION] --- -This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image. - -[`Process`]: /methods/resource/process/ - -The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: - -action -: Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. See [details](content-management/image-processing/#image-processing-methods). +Returns an image filter that processes an image according to the given [processing specification][]. This versatile filter supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string. Use this as an argument to the [`Filter`][] method or the [`images.Filter`][] function. ```go-html-template -{{ $filter := images.Process "resize 300x" }} +{{ with resources.Get "images/original.jpg" }} + {{ $filter := images.Process "crop 200x200 TopRight webp q50" }} + {{ with .Filter $filter }} + + {{ end }} +{{ end }} ``` -dimensions -: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). +In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_. -```go-html-template -{{ $filter := images.Process "crop 200x200" }} -``` - -anchor -: Use with the `crop` or `fill` action. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). - -```go-html-template -{{ $filter := images.Process "crop 200x200 center" }} -``` - -rotation -: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). - -```go-html-template -{{ $filter := images.Process "r90" }} -{{ $filter := images.Process "crop 200x200 center r90" }} -``` - -target format -: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). - -```go-html-template -{{ $filter := images.Process "webp" }} -{{ $filter := images.Process "crop 200x200 center r90 webp" }} -``` - -quality -: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). - -```go-html-template -{{ $filter := images.Process "q50" }} -{{ $filter := images.Process "crop 200x200 center r90 webp q50" }} -``` - -hint -: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). - -[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp - -```go-html-template -{{ $filter := images.Process "webp" "icon" }} -{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }} -``` - -background color -: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). - -```go-html-template -{{ $filter := images.Process "jpeg #000" }} -{{ $filter := images.Process "crop 200x200 center r90 q50 jpeg #000" }} -``` - -resampling filter -: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). - -```go-html-template -{{ $filter := images.Process "resize 300x lanczos" }} -{{ $filter := images.Process "resize 300x r90 q50 jpeg #000 lanczos" }} -``` +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Usage Create a filter: ```go-html-template -{{ $filter := images.Process "resize 256x q40 webp" }} +{{ $filter := images.Process "crop 200x200 TopRight webp q50" }} ``` {{% include "/_common/functions/images/apply-image-filter.md" %}} @@ -103,6 +41,10 @@ Create a filter: src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="resize 256x q40 webp" + filterArgs="crop 200x200 TopRight webp q50" example=true >}} + +[`Filter`]: /methods/resource/filter/ +[`images.Filter`]: /functions/images/filter +[processing specification]: #processing-specification diff --git a/docs/content/en/functions/lang/Translate.md b/docs/content/en/functions/lang/Translate.md index 92a10f016..29406bd1b 100644 --- a/docs/content/en/functions/lang/Translate.md +++ b/docs/content/en/functions/lang/Translate.md @@ -18,7 +18,7 @@ If the key is not found in the translation table for the current language, the ` If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string. > [!note] -> To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site. +> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your site configuration, or use the `--printI18nWarnings` flag when building your site. > > To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your site configuration. @@ -28,10 +28,10 @@ Create translation tables in the `i18n` directory, naming each file according to ```text i18n/en.toml -i18n/en-US.toml +i18n/pt-BR.toml ``` -The base name must match the [language key][] as defined in your site configuration. +The base name must match the [`languageCode`][] or [language key][] as defined in your site configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist. Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example: @@ -238,8 +238,10 @@ Then in your templates: [`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage [`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders +[`languageCode`]: /configuration/languages/#languagecode +[`printI18nWarnings`]: /configuration/all/#printi18nwarnings [CLDR]: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html [go-i18n]: https://github.com/nicksnyder/go-i18n [language key]: /configuration/languages/#language-keys -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md index ed15d4d6a..f64ee1147 100644 --- a/docs/content/en/functions/openapi3/Unmarshal.md +++ b/docs/content/en/functions/openapi3/Unmarshal.md @@ -1,44 +1,84 @@ --- title: openapi3.Unmarshal -description: Unmarshals the given resource into an OpenAPI 3 document. +description: Unmarshals the given resource into an OpenAPI 3 Description. categories: [] keywords: [] params: functions_and_methods: aliases: [] returnType: openapi3.OpenAPIDocument - signatures: ['openapi3.Unmarshal RESOURCE'] + signatures: ['openapi3.Unmarshal RESOURCE [OPTIONS]'] --- -Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g). +The resource passed to the `openapi3.Unmarshal` function must be an [OpenAPI Document][], typically in JSON or YAML format. This resource can be a [global resource](g) or a [remote resource](g). -[OpenAPI]: https://www.openapis.org/ +This function automatically resolves and includes all external references, both local and remote, and returns a complete [OpenAPI Description][] that fully describes the surface of an API and its semantics. -For example, to work with a remote [OpenAPI] definition: +## Options -```go-html-template -{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }} +{{< new-in 0.153.0 />}} + +getremote +: (`map`) This is a map of the options for the [`resources.GetRemote`][] function, useful when an OpenAPI Document includes remote external references. + +## Examples + +### Remote resource + +To work with a remote resource: + +```go-html-template {copy=true} {{ $api := "" }} -{{ with try (resources.GetRemote $url) }} +{{ $url := "https://petstore.swagger.io/v2/swagger.json" }} +{{ $opts := dict + "headers" (dict "Authorization" "Bearer abcd") +}} +{{ with try (resources.GetRemote $url $opts) }} {{ with .Err }} {{ errorf "%s" . }} {{ else with .Value }} - {{ $api = . | openapi3.Unmarshal }} + {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }} {{ else }} {{ errorf "Unable to get remote resource %q" $url }} {{ end }} {{ end }} ``` -To inspect the data structure: +In the example above, the same HTTP Authorization header is used for both the initial remote request made by the `resources.GetRemote` function and for subsequent requests by the `openapi.Unmarshal` function as it retrieve remote external references. -```go-html-template +### Global resource + +To work with a global resource: + +```go-html-template {copy=true} +{{ $api := "" }} +{{ $opts := dict + "method" "post" + "key" now.UnixNano +}} +{{ with resources.Get "api/petstore.json" }} + {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }} +{{ end }} +``` + +For global resources, local external reference paths starting with `/` are resolved relative to the `assets` directory. All other local paths are resolved relative to the entry point. In the example above, local paths are resolved relative to `assets/api/petstore.json`. + +## Inspection + +> [!note] +> 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. + +To inspect the unmarshaled data structure: + +```go-html-template {copy=true} 
{{ debug.Dump $api }}
``` To list the GET and POST operations for each of the API paths: -```go-html-template +```go-html-template {copy=true} {{ range $path, $details := $api.Paths.Map }}

{{ $path }}

@@ -54,11 +94,6 @@ 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 @@ -75,3 +110,7 @@ Hugo renders this to:
Info for a specific pet
``` + +[`resources.GetRemote`]: /functions/resources/getremote/#options +[OpenAPI Document]: https://swagger.io/specification/#openapi-document +[OpenAPI Description]: https://swagger.io/specification/#openapi-description diff --git a/docs/content/en/functions/reflect/IsImageResource.md b/docs/content/en/functions/reflect/IsImageResource.md new file mode 100644 index 000000000..42a128196 --- /dev/null +++ b/docs/content/en/functions/reflect/IsImageResource.md @@ -0,0 +1,71 @@ +--- +title: reflect.IsImageResource +description: Reports whether the given value is a Resource object representing a processable image. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsImageResource INPUT] +--- + +{{< new-in 0.154.0 />}} + +{{% glossary-term "processable image" %}} + +With this project structure: + +```text +project/ +├── assets/ +│ ├── a.json +│ ├── b.avif +│ └── c.jpg +└── content/ + └── example/ + ├── index.md + ├── d.json + ├── e.avif + └── f.jpg +``` + +These are the values returned by the `reflect.IsImageResource` function: + +```go-html-template {file="layouts/page.html"} +{{ with resources.Get "a.json" }} + {{ reflect.IsImageResource . }} → false +{{ end }} + +{{ with resources.Get "b.avif" }} + {{ reflect.IsImageResource . }} → false +{{ end }} + +{{ with resources.Get "c.jpg" }} + {{ reflect.IsImageResource . }} → true +{{ end }} +``` + +In the example above, the `b.avif` image is not a processable image because Hugo can neither decode nor encode the AVIF image format. + +```go-html-template {file="layouts/page.html"} +{{ with .Resources.Get "d.json" }} + {{ reflect.IsImageResource . }} → false +{{ end }} + +{{ with .Resources.Get "e.avif" }} + {{ reflect.IsImageResource . }} → false +{{ end }} + +{{ with .Resources.Get "f.jpg" }} + {{ reflect.IsImageResource . }} → true +{{ end }} +``` + +In the example above, the `e.avif` image is not a processable image because Hugo can neither decode nor encode the AVIF image format. + +```go-html-template {file="layouts/page.html"} +{{ with site.GetPage "/example" }} + {{ reflect.IsImageResource . }} → false +{{ end }} +``` diff --git a/docs/content/en/functions/reflect/IsPage.md b/docs/content/en/functions/reflect/IsPage.md new file mode 100644 index 000000000..eaf545ccf --- /dev/null +++ b/docs/content/en/functions/reflect/IsPage.md @@ -0,0 +1,23 @@ +--- +title: reflect.IsPage +description: Reports whether the given value is a Page object. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsPage INPUT] +--- + +{{< new-in 0.154.0 />}} + +```go-html-template {file="layouts/page.html"} +{{ with site.GetPage "/examples" }} + {{ reflect.IsPage . }} → true +{{ end }} + +{{ with .Site }} + {{ reflect.IsPage . }} → false +{{ end }} +``` diff --git a/docs/content/en/functions/reflect/IsResource.md b/docs/content/en/functions/reflect/IsResource.md new file mode 100644 index 000000000..ae86b4ecd --- /dev/null +++ b/docs/content/en/functions/reflect/IsResource.md @@ -0,0 +1,65 @@ +--- +title: reflect.IsResource +description: Reports whether the given value is a Resource object. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsResource INPUT] +--- + +{{< new-in 0.154.0 />}} + +With this project structure: + +```text +project/ +├── assets/ +│ ├── a.json +│ ├── b.avif +│ └── c.jpg +└── content/ + └── example/ + ├── index.md + ├── d.json + ├── e.avif + └── f.jpg +``` + +These are the values returned by the `reflect.IsResource` function: + +```go-html-template {file="layouts/page.html"} +{{ with resources.Get "a.json" }} + {{ reflect.IsResource . }} → true +{{ end }} + +{{ with resources.Get "b.avif" }} + {{ reflect.IsResource . }} → true +{{ end }} + +{{ with resources.Get "c.jpg" }} + {{ reflect.IsResource . }} → true +{{ end }} +``` + +```go-html-template {file="layouts/page.html"} +{{ with .Resources.Get "d.json" }} + {{ reflect.IsResource . }} → true +{{ end }} + +{{ with .Resources.Get "e.avif" }} + {{ reflect.IsResource . }} → true +{{ end }} + +{{ with .Resources.Get "f.jpg" }} + {{ reflect.IsResource . }} → true +{{ end }} +``` + +```go-html-template {file="layouts/page.html"} +{{ with site.GetPage "/example" }} + {{ reflect.IsResource . }} → true +{{ end }} +``` diff --git a/docs/content/en/functions/reflect/IsSite.md b/docs/content/en/functions/reflect/IsSite.md new file mode 100644 index 000000000..9170dd48a --- /dev/null +++ b/docs/content/en/functions/reflect/IsSite.md @@ -0,0 +1,23 @@ +--- +title: reflect.IsSite +description: Reports whether the given value is a Site object. +categories: [] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsSite INPUT] +--- + +{{< new-in 0.154.0 />}} + +```go-html-template {file="layouts/page.html"} +{{ with .Site }} + {{ reflect.IsSite . }} → true +{{ end }} + +{{ with site.GetPage "/examples" }} + {{ reflect.IsSite . }} → false +{{ end }} +``` diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md index 518511898..8761d1c99 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-07-08T13:12:19-07:00", - "hugo_version": "0.152.2", - "last_modified": "2025-07-07T22:09:13-07:00" + "build_date": "2026-01-11T11:27:49-08:00", + "hugo_version": "0.155.3", + "last_modified": "2026-01-11T11:27:59-08:00" } ``` diff --git a/docs/content/en/functions/resources/GetMatch.md b/docs/content/en/functions/resources/GetMatch.md index 8f1b004fe..bf6a95486 100644 --- a/docs/content/en/functions/resources/GetMatch.md +++ b/docs/content/en/functions/resources/GetMatch.md @@ -21,7 +21,7 @@ params: > > For page resources, use the [`Resources.GetMatch`] method on a `Page` object. -Hugo determines a match using a case-insensitive [glob](g) pattern. +Hugo determines a match using a case-insensitive [glob pattern](g). {{% include "/_common/glob-patterns.md" %}} diff --git a/docs/content/en/functions/strings/Diff/index.md b/docs/content/en/functions/strings/Diff/index.md index 1426764a9..31d348e8e 100644 --- a/docs/content/en/functions/strings/Diff/index.md +++ b/docs/content/en/functions/strings/Diff/index.md @@ -9,8 +9,6 @@ params: signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] --- -{{< new-in 0.125.0 />}} - Use `strings.Diff` to compare two strings and render a highlighted diff: ```go-html-template diff --git a/docs/content/en/functions/templates/Inner.md b/docs/content/en/functions/templates/Inner.md new file mode 100644 index 000000000..15fab2dc0 --- /dev/null +++ b/docs/content/en/functions/templates/Inner.md @@ -0,0 +1,71 @@ +--- +title: templates.Inner +description: Executes the content block enclosed by a partial call. +categories: [] +keywords: [decorator] +params: + functions_and_methods: + aliases: [inner] + returnType: any + signatures: ['templates.Inner [CONTEXT]'] +--- + +{{< new-in 0.154.0 />}} + +The `templates.Inner` function defines the injection point for code nested within a block style partial call. This is the core mechanism used to create a [partial decorator][]. + +## Overview + +The `templates.Inner` function acts as a placeholder within a partial template. When a partial is called as a decorator, it captures a block of code from the calling template rather than rendering it immediately. The `templates.Inner` function tells Hugo exactly where to inject that captured content. + +This signals a reversal of execution where the callee becomes the caller. The partial manages the outer structure while the calling template remains in control of the inner content. + +## Usage + +To use this function, the calling template must use the block style syntax with a [`with`][] statement. This allows decorators to be deeply nested. + +```go-html-template {file="layouts/home.html"} +{{ with partial "components/card.html" . }} +

This content is passed to the partial.

+{{ end }} +``` + +Inside the partial, call `templates.Inner` to render the captured block. + +```go-html-template {file="layouts/_partials/components/card.html"} +
+ {{ templates.Inner . }} +
+``` + +## Arguments + +The function accepts one optional argument: the [context](g). This argument determines the value of the dot (`.`) inside the captured block when it is rendered. + +- If you provide an argument, such as `{{ templates.Inner .SomeData }}`, the dot inside the captured block is rebound to that specific data. +- If you do not provide an argument, the captured block uses the context of the caller where the partial was first invoked. + +## Context and scope + +When using decorators, the `with` statement creates a new [scope](g). Variables defined outside the with block in the calling template are not automatically available inside the captured block. + +By passing a context to `templates.Inner`, you ensure that the injected content has access to the correct data even when nested inside multiple layers of wrappers. This is critical when the decorator is used inside a loop or a specific data overlay. + +## Repeated execution + +A decorator can execute the captured content zero or more times. This is useful when the wrapper needs to repeat the same decoration for a collection of items, such as a list or a grid. + +```go-html-template {file="layouts/_partials/list-decorator.html"} +
    + {{ range .items }} +
  • + {{ templates.Inner . }} +
    • + {{ end }} +
+``` + +In this example, the code provided by the caller is rendered once for every item in the .items collection, with the dot . updated to the current item in each iteration. + +[`with`]: /functions/go-template/with/ +[partial decorator]: /templates/partial-decorators/ diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md index 22ae04dd5..97689f5d5 100644 --- a/docs/content/en/functions/transform/ToMath.md +++ b/docs/content/en/functions/transform/ToMath.md @@ -150,6 +150,18 @@ Step 3 In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method. + > [!note] + > This conditional approach only identifies math on the current page. Mathematical expressions will not display correctly when one page's content is embedded within another. For example, if a [list page](g) calls the [`Content`][] or [`Summary`][] methods while ranging through its page collection, the list page will not load the KaTeX CSS. + > + > If this affects your site, use this conditional logic instead: + > + > ```go-html-template {file="layouts/baseof.html" copy=true} + > {{ $noop := .WordCount }} + > {{ if or (.Page.Store.Get "hasMath") .IsNode }} + > + > {{ end }} + > ``` + Step 4 : Add some mathematical markup to your content, then test. @@ -175,6 +187,8 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ +[`Content`]: /methods/page/content/ +[`Summary`]: /methods/page/summary/ [hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color [KaTeX]: https://katex.org/ [MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML diff --git a/docs/content/en/functions/urls/PathEscape.md b/docs/content/en/functions/urls/PathEscape.md new file mode 100644 index 000000000..ab570aa77 --- /dev/null +++ b/docs/content/en/functions/urls/PathEscape.md @@ -0,0 +1,20 @@ +--- +title: urls.PathEscape +description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [urls.PathEscape INPUT] +--- + +{{< new-in v0.153.0 />}} + +The `urls.PathEscape` function does the inverse transformation of [`urls.PathUnescape`][]. + +```go-html-template +{{ urls.PathEscape "A/b/c?d=é&f=g+h" }} → A%2Fb%2Fc%3Fd=%C3%A9&f=g+h +``` + +[`urls.PathUnescape`]: /functions/urls/PathUnescape/ diff --git a/docs/content/en/functions/urls/PathUnescape.md b/docs/content/en/functions/urls/PathUnescape.md new file mode 100644 index 000000000..f1432f02f --- /dev/null +++ b/docs/content/en/functions/urls/PathUnescape.md @@ -0,0 +1,20 @@ +--- +title: urls.PathUnescape +description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [urls.PathUnescape INPUT] +--- + +{{< new-in v0.153.0 />}} + +The `urls.PathUnescape` function does the inverse transformation of [`urls.PathEscape`][]. + +```go-html-template +{{ urls.PathUnescape "A%2Fb%2Fc%3Fd=%C3%A9&f=g+h" }} → A/b/c?d=é&f=g+h +``` + +[`urls.PathEscape`]: /functions/urls/PathEscape/ diff --git a/docs/content/en/getting-started/quick-start.md b/docs/content/en/getting-started/quick-start.md index e7494a924..cc800181c 100644 --- a/docs/content/en/getting-started/quick-start.md +++ b/docs/content/en/getting-started/quick-start.md @@ -4,7 +4,7 @@ description: Create a Hugo site in minutes. categories: [] keywords: [] params: - minVersion: v0.128.0 + minVersion: v0.146.0 weight: 10 aliases: [/quickstart/,/overview/quickstart/] --- diff --git a/docs/content/en/getting-started/usage.md b/docs/content/en/getting-started/usage.md index 8cbcc9b02..cc43c0cf0 100644 --- a/docs/content/en/getting-started/usage.md +++ b/docs/content/en/getting-started/usage.md @@ -18,7 +18,7 @@ hugo version You should see something like: ```text -hugo v0.152.2-6abdacad3f3fe944ea42177844469139e81feda6+extended linux/amd64 BuildDate=2025-10-24T15:31:49Z VendorInfo=gohugoio +hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio ``` ## Display available commands @@ -59,8 +59,6 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [ - The `publishDate` is in the future - The `expiryDate` is in the past -{{< new-in 0.123.0 />}} - > [!note] > Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages. @@ -142,9 +140,7 @@ public/ In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need. -Most of our users deploy their sites using a [CI/CD](g) workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]. - -Learn more in the [host and deploy] section. +Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy] section. [^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push. @@ -153,14 +149,8 @@ Learn more in the [host and deploy] section. [`hugo server`]: /commands/hugo_server/ [`hugo`]: /commands/hugo/ [`publishDir`]: /configuration/all/#publishdir -[AWS Amplify]: https://aws.amazon.com/amplify/ [build options]: /content-management/build-options/ -[CloudCannon]: https://cloudcannon.com/ -[Cloudflare Pages]: https://pages.cloudflare.com/ [front matter]: /content-management/front-matter/ -[GitHub Pages]: https://pages.github.com/ -[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/ [host and deploy]: /host-and-deploy/ [installing]: /installation/ [LiveReload]: https://github.com/livereload/livereload-js -[Netlify]: https://www.netlify.com/ diff --git a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md index 67a531af6..216b828fb 100644 --- a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md +++ b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -40,9 +40,9 @@ Step 2 env: variables: # Application versions - DART_SASS_VERSION: 1.96.0 - GO_VERSION: 1.25.5 - HUGO_VERSION: 0.152.2 + DART_SASS_VERSION: 1.97.3 + GO_VERSION: 1.25.6 + HUGO_VERSION: 0.155.3 # Time zone TZ: Europe/Oslo # Cache diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/index.md b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md index c5434f81d..1341ca325 100644 --- a/docs/content/en/host-and-deploy/host-on-cloudflare/index.md +++ b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md @@ -51,10 +51,10 @@ Step 2 main() { - DART_SASS_VERSION=1.96.0 - GO_VERSION=1.25.5 - HUGO_VERSION=0.152.2 - NODE_VERSION=24.12.0 + DART_SASS_VERSION=1.97.3 + GO_VERSION=1.25.6 + HUGO_VERSION=0.155.3 + NODE_VERSION=24.13.0 export TZ=Europe/Oslo diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/index.md b/docs/content/en/host-and-deploy/host-on-github-pages/index.md index 9974c8ac3..5e900cffe 100644 --- a/docs/content/en/host-and-deploy/host-on-github-pages/index.md +++ b/docs/content/en/host-and-deploy/host-on-github-pages/index.md @@ -77,24 +77,24 @@ Step 4 build: runs-on: ubuntu-latest env: - DART_SASS_VERSION: 1.96.0 - GO_VERSION: 1.25.5 - HUGO_VERSION: 0.152.2 - NODE_VERSION: 24.12.0 + DART_SASS_VERSION: 1.97.3 + GO_VERSION: 1.25.6 + HUGO_VERSION: 0.155.3 + NODE_VERSION: 24.13.0 TZ: Europe/Oslo steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: submodules: recursive fetch-depth: 0 - name: Setup Go - uses: actions/setup-go@v5 + uses: actions/setup-go@v6 with: go-version: ${{ env.GO_VERSION }} cache: false - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: ${{ env.NODE_VERSION }} - name: Setup Pages @@ -130,7 +130,7 @@ Step 4 git config core.quotepath false - name: Cache restore id: cache-restore - uses: actions/cache/restore@v4 + uses: actions/cache/restore@v5 with: path: ${{ runner.temp }}/hugo_cache key: hugo-${{ github.run_id }} @@ -145,7 +145,7 @@ Step 4 --cacheDir "${{ runner.temp }}/hugo_cache" - name: Cache save id: cache-save - uses: actions/cache/save@v4 + uses: actions/cache/save@v5 with: path: ${{ runner.temp }}/hugo_cache key: ${{ steps.cache-restore.outputs.cache-primary-key }} diff --git a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md index e10c3aca1..46832909e 100644 --- a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md +++ b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md @@ -24,9 +24,9 @@ Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of y ```yaml {file=".gitlab-ci.yml" copy=true} variables: # Application versions - DART_SASS_VERSION: 1.96.0 - HUGO_VERSION: 0.152.2 - NODE_VERSION: 24.12.0 + DART_SASS_VERSION: 1.97.3 + HUGO_VERSION: 0.155.3 + NODE_VERSION: 24.13.0 # Git GIT_DEPTH: 0 GIT_STRATEGY: clone @@ -35,7 +35,7 @@ variables: TZ: Europe/Oslo image: - name: golang:1.25.5-bookworm + name: golang:1.25.6-bookworm pages: stage: deploy diff --git a/docs/content/en/host-and-deploy/host-on-netlify/index.md b/docs/content/en/host-and-deploy/host-on-netlify/index.md index d2eeb2665..fcca62b72 100644 --- a/docs/content/en/host-and-deploy/host-on-netlify/index.md +++ b/docs/content/en/host-and-deploy/host-on-netlify/index.md @@ -30,10 +30,10 @@ Step 1 ```text {file="netlify.toml" copy=true} [build.environment] - DART_SASS_VERSION = "1.96.0" - GO_VERSION = "1.25.5" - HUGO_VERSION = "0.152.2" - NODE_VERSION = "24.12.0" + DART_SASS_VERSION = "1.97.3" + GO_VERSION = "1.25.6" + HUGO_VERSION = "0.155.3" + NODE_VERSION = "24.13.0" TZ = "Europe/Oslo" [build] @@ -48,10 +48,10 @@ Step 1 ```text {file="netlify.toml" copy=true} [build.environment] - DART_SASS_VERSION = "1.96.0" - GO_VERSION = "1.25.5" - HUGO_VERSION = "0.152.2" - NODE_VERSION = "24.12.0" + DART_SASS_VERSION = "1.97.3" + GO_VERSION = "1.25.6" + HUGO_VERSION = "0.155.3" + NODE_VERSION = "24.13.0" TZ = "Europe/Oslo" [build] diff --git a/docs/content/en/host-and-deploy/host-on-render/index.md b/docs/content/en/host-and-deploy/host-on-render/index.md index b8d597b15..bec42af64 100644 --- a/docs/content/en/host-and-deploy/host-on-render/index.md +++ b/docs/content/en/host-and-deploy/host-on-render/index.md @@ -35,13 +35,13 @@ Step 1 staticPublishPath: public envVars: - key: DART_SASS_VERSION - value: 1.96.0 + value: 1.97.3 - key: GO_VERSION - value: 1.25.5 + value: 1.25.6 - key: HUGO_VERSION - value: 0.152.2 + value: 0.155.3 - key: NODE_VERSION - value: 24.12.0 + value: 24.13.0 - key: TZ value: Europe/Oslo ``` diff --git a/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md b/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md index 1d278f0fe..70fd1bb96 100644 --- a/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md +++ b/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md @@ -8,9 +8,9 @@ aliases: [/hosting-and-deployment/hosting-on-sourcehut/] ## Assumptions -- Working familiarity with [Git] or [Mercurial] for version control -- Completion of the Hugo [Quick Start] -- A [SourceHut account] +- Working familiarity with [Git][] or [Mercurial][] for version control +- Completion of the Hugo [Quick Start][] +- A [SourceHut account][] - A Hugo website on your local machine that you are ready to publish [Git]: https://git-scm.com/ @@ -22,14 +22,14 @@ Any and all mentions of `` refer to your actual SourceHut username ## BaseURL -The [`baseURL`] in your site configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://.srht.site/`). If you want to use another domain, check the [custom domain section] of the official documentation. +The [`baseURL`][] in your site configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation. [`baseURL`]: /configuration/all/#baseurl [custom domain section]: https://srht.site/custom-domains ## Manual deployment -This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token] and install and configure the [hut] CLI tool: +This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token][] and install and configure the [hut][] CLI tool: [SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token [hut]: https://sr.ht/~xenrox/hut/ @@ -47,7 +47,7 @@ A TLS certificate will be automatically obtained for you, and your new website w This method requires a paid account and relies on the SourceHut build system. -First, define your [build manifest] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template: +First, define your [build manifest][] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template: [build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests @@ -68,6 +68,37 @@ tasks: hut pages publish -d $site site.tar.gz ``` +If your site requires [Dart Sass][] to transpile Sass to CSS, set the DART_SASS_VERSION to the [latest version number][] and include the Dart Sass installation lines before running the Hugo build step. Note that for Alpine, the `linux-x64-musl` version is used. + +[Dart Sass]: https://gohugo.io/functions/css/sass/#dart-sass +[latest version number]: https://github.com/sass/dart-sass/releases + +```yaml {file=".build.yml" copy=true} +image: alpine/edge +packages: + - hugo + - hut + - curl # For Dart Sass installation +oauth: pages.sr.ht/PAGES:RW +environment: + site: .srht.site +tasks: +- package: | + DART_SASS_VERSION=1.97.1 # Latest version as of 20/12/2025 + mkdir -p $HOME/.local + curl -L https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gz -o dart-sass.tar.gz + tar -xzf dart-sass.tar.gz -C $HOME/.local + rm dart-sass.tar.gz + chmod -R +x $HOME/.local/dart-sass/src + export PATH="$HOME/.local/dart-sass:$PATH" + sass --version # Verify installation + cd $site + hugo + tar -C public -cvz . > ../site.tar.gz +- upload: | + hut pages publish -d $site site.tar.gz +``` + Now what's left is creating a repository titled `.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git: ```sh diff --git a/docs/content/en/host-and-deploy/host-on-vercel/index.md b/docs/content/en/host-and-deploy/host-on-vercel/index.md index d93ab6040..fb1b8b7e7 100644 --- a/docs/content/en/host-and-deploy/host-on-vercel/index.md +++ b/docs/content/en/host-and-deploy/host-on-vercel/index.md @@ -47,10 +47,10 @@ Step 2 main() { - DART_SASS_VERSION=1.96.0 - GO_VERSION=1.25.5 - HUGO_VERSION=0.152.2 - NODE_VERSION=24.12.0 + DART_SASS_VERSION=1.97.3 + GO_VERSION=1.25.6 + HUGO_VERSION=0.155.3 + NODE_VERSION=24.13.0 export TZ=Europe/Oslo diff --git a/docs/content/en/hugo-modules/use-modules.md b/docs/content/en/hugo-modules/use-modules.md index 86d2ad1cc..6a0483e76 100644 --- a/docs/content/en/hugo-modules/use-modules.md +++ b/docs/content/en/hugo-modules/use-modules.md @@ -108,7 +108,7 @@ Note that: - You can run `hugo mod vendor` on any level in the module tree. - Vendoring will not store modules stored in your `themes` directory. -- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob](g) pattern. +- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob pattern](g). Also see the [CLI Doc](/commands/hugo_mod_vendor/). diff --git a/docs/content/en/installation/bsd.md b/docs/content/en/installation/bsd.md index a4f31bd5f..7b8e8c82c 100644 --- a/docs/content/en/installation/bsd.md +++ b/docs/content/en/installation/bsd.md @@ -6,12 +6,8 @@ keywords: [] weight: 40 --- -## Editions - {{% include "/_common/installation/01-editions.md" %}} -Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. - {{% include "/_common/installation/02-prerequisites.md" %}} {{% include "/_common/installation/03-prebuilt-binaries.md" %}} diff --git a/docs/content/en/installation/linux.md b/docs/content/en/installation/linux.md index 0ce751d43..31fcaa90d 100644 --- a/docs/content/en/installation/linux.md +++ b/docs/content/en/installation/linux.md @@ -6,18 +6,15 @@ keywords: [] weight: 20 --- -## Editions - {{% include "/_common/installation/01-editions.md" %}} -Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. - {{% include "/_common/installation/02-prerequisites.md" %}} {{% include "/_common/installation/03-prebuilt-binaries.md" %}} ## Package managers + + {{% include "/_common/installation/homebrew.md" %}} ## Repository packages @@ -205,14 +207,11 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch [Linux Lite]: https://www.linuxliteos.com/ [Linux Mint]: https://linuxmint.com/ [Manjaro]: https://manjaro.org/ -[most distributions]: https://snapcraft.io/docs/installing-snapd [MX Linux]: https://mxlinux.org/ [openSUSE]: https://www.opensuse.org/ [Pop!_OS]: https://pop.system76.com/ [Red Hat Enterprise Linux]: https://www.redhat.com/ -[Snap]: https://snapcraft.io/ [Solus]: https://getsol.us/ -[strictly confined]: https://snapcraft.io/docs/snap-confinement [Ubuntu]: https://ubuntu.com/ [USE]: https://packages.gentoo.org/packages/www-apps/hugo [Void Linux]: https://voidlinux.org/ diff --git a/docs/content/en/installation/macos.md b/docs/content/en/installation/macos.md index 0f1fc0d27..1984d1a8e 100644 --- a/docs/content/en/installation/macos.md +++ b/docs/content/en/installation/macos.md @@ -6,12 +6,8 @@ keywords: [] weight: 10 --- -## Editions - {{% include "/_common/installation/01-editions.md" %}} -Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. - {{% include "/_common/installation/02-prerequisites.md" %}} {{% include "/_common/installation/03-prebuilt-binaries.md" %}} diff --git a/docs/content/en/installation/windows.md b/docs/content/en/installation/windows.md index 0b7d89f6e..8563ab7ee 100644 --- a/docs/content/en/installation/windows.md +++ b/docs/content/en/installation/windows.md @@ -9,12 +9,8 @@ weight: 30 > [!note] > Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016. -## Editions - {{% include "/_common/installation/01-editions.md" %}} -Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition. - {{% include "/_common/installation/02-prerequisites.md" %}} {{% include "/_common/installation/03-prebuilt-binaries.md" %}} diff --git a/docs/content/en/methods/output-format/MediaType.md b/docs/content/en/methods/output-format/MediaType.md new file mode 100644 index 000000000..45f6267a1 --- /dev/null +++ b/docs/content/en/methods/output-format/MediaType.md @@ -0,0 +1,36 @@ +--- +title: MediaType +description: Returns the media type of the given output format. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: media.Type + signatures: [OUTPUTFORMAT.MediaType] +--- + +{{% include "/_common/methods/output-formats/to-use-this-method.md" %}} + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ with .MediaType }} + {{ .Type }} → application/rss+xml + {{ .MainType }} → application + {{ .SubType }} → rss + {{ end }} +{{ end }} +``` + +## Methods + +### MainType + +(`string`) Returns the main type of the output format's media type. + +### SubType + +(`string`) Returns the subtype of the current format's media type. + +### Type + +(`string`) Returns the the current format's media type. diff --git a/docs/content/en/methods/output-format/Name.md b/docs/content/en/methods/output-format/Name.md new file mode 100644 index 000000000..307f940e7 --- /dev/null +++ b/docs/content/en/methods/output-format/Name.md @@ -0,0 +1,18 @@ +--- +title: Name +description: Returns the identifier of the given output format. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [OUTPUTFORMAT.Name] +--- + +{{% include "/_common/methods/output-formats/to-use-this-method.md" %}} + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ .Name }} → rss +{{ end }} +``` diff --git a/docs/content/en/methods/output-format/Permalink.md b/docs/content/en/methods/output-format/Permalink.md new file mode 100644 index 000000000..09b98dc7c --- /dev/null +++ b/docs/content/en/methods/output-format/Permalink.md @@ -0,0 +1,18 @@ +--- +title: Permalink +description: Returns the permalink of the page generated by the current output format. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [OUTPUTFORMAT.Permalink] +--- + +{{% include "/_common/methods/output-formats/to-use-this-method.md" %}} + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ .Permalink }} → https://example.org/index.xml +{{ end }} +``` diff --git a/docs/content/en/methods/output-format/Rel.md b/docs/content/en/methods/output-format/Rel.md new file mode 100644 index 000000000..1dca4b10a --- /dev/null +++ b/docs/content/en/methods/output-format/Rel.md @@ -0,0 +1,18 @@ +--- +title: Rel +description: Returns the rel value of the given output format, either the default or as defined in the site configuration. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [OUTPUTFORMAT.Rel] +--- + +{{% include "/_common/methods/output-formats/to-use-this-method.md" %}} + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ .Rel }} → alternate +{{ end }} +``` diff --git a/docs/content/en/methods/output-format/RelPermalink.md b/docs/content/en/methods/output-format/RelPermalink.md new file mode 100644 index 000000000..434100c56 --- /dev/null +++ b/docs/content/en/methods/output-format/RelPermalink.md @@ -0,0 +1,18 @@ +--- +title: RelPermalink +description: Returns the relative permalink of the page generated by the current output format. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [OUTPUTFORMAT.RelPermalink] +--- + +{{% include "/_common/methods/output-formats/to-use-this-method.md" %}} + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ .RelPermalink }} → /index.xml +{{ end }} +``` diff --git a/docs/content/en/methods/output-format/_index.md b/docs/content/en/methods/output-format/_index.md new file mode 100644 index 000000000..dd374de14 --- /dev/null +++ b/docs/content/en/methods/output-format/_index.md @@ -0,0 +1,7 @@ +--- +title: Output format methods +linkTitle: Output format +description: Use these methods with an OutputFormat object. +categories: [] +keywords: [] +--- diff --git a/docs/content/en/methods/page/Aliases.md b/docs/content/en/methods/page/Aliases.md index 775404bd3..f549ad948 100644 --- a/docs/content/en/methods/page/Aliases.md +++ b/docs/content/en/methods/page/Aliases.md @@ -1,6 +1,6 @@ --- title: Aliases -description: Returns the URL aliases as defined in front matter. +description: Returns the aliases defined in front matter as server-relative URLs, resolved according to the current content dimension. categories: [] keywords: [] params: @@ -9,21 +9,131 @@ params: signatures: [PAGE.Aliases] --- -The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter. +The `Aliases` method on a `Page` object returns the values defined in the [`aliases`][] front matter field as server-relative URLs, resolved according to the current [content dimension](g). -For example: +The `Aliases` method is useful for generating a `_redirects` file, which contains a source URL, a target URL, and an HTTP status code for each alias. You can use a `_redirects` file with hosting services such as Cloudflare, GitLab Pages, and Netlify. -{{< code-toggle file=content/about.md fm=true >}} -title = 'About' -aliases = ['/old-url','/really-old-url'] -{{< /code-toggle >}} +## Redirects -To list the aliases: +By default, Hugo handles aliases by creating individual HTML files for each alias path. These files contain a `meta http-equiv="refresh"` tag to redirect the visitor via the browser. -```go-html-template -{{ range .Aliases }} - {{ . }} -{{ end }} +While functional, generating a single `_redirects` file allows your hosting provider to handle redirects at the server level. This is more efficient than client-side redirection and improves performance by eliminating the need to load a middle-man HTML page. + +> [!tip] +> You can use the same general approach to generate an `.htaccess` file. + +## Example + +The following example demonstrates how to configure your site and create a template to automate the generation of a `_redirects` file. + +### Content structure + +The content structure for this multilingual example looks like this: + +```text +content/ +├── examples/ +│ ├── a.de.md aliases = ['a-old'] +│ ├── a.en.md aliases = ['a-old', 'a-older'] +│ ├── b.de.md aliases = ['b-old'] +│ └── b.en.md aliases = ['b-old', 'b-older'] +└── _index.md ``` -[aliases]: /content-management/urls/#aliases +In the example above, the aliases are [page-relative](g). To specify a [site-relative](g) path, preface the entry with a slash (`/`). Both forms are resolved to [server-relative](g) paths. + +Page-relative paths can also include directory traversal: + +| Path type | File path | Alias | Server-relative path | +| :--- | :--- | :--- | :--- | +| page-relative | `content/examples/a.en.md` | `a-old` | `/en/examples/a-old/` | +| page-relative | `content/examples/a.en.md` | `../a-old` | `/en/a-old/` | +| site-relative | `content/examples/a.en.md` | `/a-old` | `/en/a-old/` | + +### Site configuration + +To implement this, you must update your site configuration to: + +1. Disable the generation of default HTML redirect files by setting `disableAliases` to `true`. +1. Define a [media type][] named `text/redirects` to handle the file format. +1. Define a custom [output format][] named `redirects` to set the filename to `_redirects` and place it at the root of the published site. +1. Configure the home page [outputs][] to include the `redirects` format in addition to `html`. + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +disableAliases = true + +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true + +[languages.en] + languageCode = 'en-US' + languageDirection = 'ltr' + languageName = 'English' + weight = 1 + title = 'My Site in English' + +[languages.de] + languageCode = 'de-DE' + languageDirection = 'ltr' + languageName = 'Deutsch' + weight = 2 + title = 'My Site in German' + +[mediaTypes] + [mediaTypes.'text/redirects'] + delimiter = '' + +[outputFormats] + [outputFormats.redirects] + baseName = '_redirects' + isPlainText = true + mediaType = 'text/redirects' + root = true + +[outputs] + home = ['html', 'redirects'] +{{< /code-toggle >}} + +### Template implementation + +Next, create a home page template specifically for the `redirects` output format. The following template iterates through every page in every language and extracts its aliases. + +To ensure the resulting `_redirects` file is valid, the template uses the [`strings.FindRE`][] function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file. + +```go-html-template {file="layouts/home.redirects" copy=true} +{{- if not (hugo.Store.Get "has_printed_redirects") -}} + {{- range .Sites -}} + {{- range $p := .Pages -}} + {{- range .Aliases -}} + {{- if findRE `\s` . -}} + {{- errorf "One of the front matter aliases in %q contains whitespace" $p.String -}} + {{- end -}} + {{- printf "%s %s 301\n" . $p.RelPermalink -}} + {{- end -}} + {{- end -}} + {{- end -}} + {{- hugo.Store.Set "has_printed_redirects" true -}} +{{- end -}} +``` + +### Generated output + +Once Hugo processes the template, it produces a clean list of redirect rules. Each line follows the required format: the source URL, the destination URL, and the HTTP status code. + +The resulting `_redirects` file looks like this: + +```text +/de/examples/a-old /de/examples/a/ 301 +/de/examples/b-old /de/examples/b/ 301 +/en/examples/b-old /en/examples/b/ 301 +/en/examples/b-older /en/examples/b/ 301 +/en/examples/a-old /en/examples/a/ 301 +/en/examples/a-older /en/examples/a/ 301 +``` + +[`aliases`]: /content-management/front-matter/#aliases +[`strings.FindRE`]: /functions/strings/findre/ +[media type]: /configuration/media-types/ +[output format]: /configuration/output-formats/ +[outputs]: /configuration/outputs/ diff --git a/docs/content/en/methods/page/AlternativeOutputFormats.md b/docs/content/en/methods/page/AlternativeOutputFormats.md index c4075d010..72ef9f5d0 100644 --- a/docs/content/en/methods/page/AlternativeOutputFormats.md +++ b/docs/content/en/methods/page/AlternativeOutputFormats.md @@ -13,30 +13,17 @@ params: The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/). -## Methods - -{{% include "/_common/methods/page/output-format-methods.md" %}} - -## Example - -Generate a `link` element in the `` of each page for each of the alternative output formats: +For example, to generate a `link` element for each of the alternative output formats: ```go-html-template - - ... - {{ $title := printf "%s | %s" .Title site.Title }} - {{ if .IsHome }} - {{ $title = site.Title }} - {{ end }} - {{ range .AlternativeOutputFormats }} - {{ printf `` .Rel .MediaType.Type .Permalink $title | safeHTML }} - {{ end }} - ... - +{{ range .AlternativeOutputFormats }} + {{ printf "" .Rel .MediaType.Type .Permalink | safeHTML }} +{{ end }} ``` -On the site's home page, Hugo renders this to: +Hugo renders this to something like: ```html - + + ``` diff --git a/docs/content/en/methods/page/GitInfo.md b/docs/content/en/methods/page/GitInfo.md index 2b620103e..f09eb76b4 100644 --- a/docs/content/en/methods/page/GitInfo.md +++ b/docs/content/en/methods/page/GitInfo.md @@ -153,7 +153,7 @@ You can change this behavior in your [site configuration]. ## Hosting considerations -In a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file. +On a [CI/CD](g) platform, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file. While some providers perform a deep clone by default, others require you to configure the depth yourself. diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md index 9fd604df3..8ccc578f6 100644 --- a/docs/content/en/methods/page/Language.md +++ b/docs/content/en/methods/page/Language.md @@ -9,13 +9,13 @@ params: signatures: [PAGE.Language] --- -The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration. +The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration. You can also use the `Language` method on a `Site` object. See [details]. ## Methods -The examples below assume the following in your site configuration: +The examples below assume the following in the site configuration: {{< code-toggle file=hugo >}} [languages.de] @@ -25,9 +25,19 @@ languageName = 'Deutsch' weight = 2 {{< /code-toggle >}} +### IsDefault + +{{< new-in 0.153.0 />}} + +(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration. + +```go-html-template +{{ .Language.IsDefault }} → true +``` + ### Lang -(`string`) The language tag as defined by [RFC 5646]. +(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. ```go-html-template {{ .Language.Lang }} → de @@ -57,6 +67,14 @@ weight = 2 {{ .Language.LanguageName }} → Deutsch ``` +### Name + +(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key used in the site configuration. This is an alias for `Lang`. + +```go-html-template +{{ .Site.Language.Name }} → de +``` + ### Weight (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. @@ -65,5 +83,6 @@ weight = 2 {{ .Language.Weight }} → 2 ``` +[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage [details]: /methods/site/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/docs/content/en/methods/page/OutputFormats.md b/docs/content/en/methods/page/OutputFormats.md index 0e648efaa..19377feef 100644 --- a/docs/content/en/methods/page/OutputFormats.md +++ b/docs/content/en/methods/page/OutputFormats.md @@ -15,11 +15,51 @@ The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` ## Methods -{{% include "/_common/methods/page/output-format-methods.md" %}} +### Canonical -## Example +{{< new-in "0.154.4" />}} -To link to the RSS feed for the current page: +(`page.OutputFormat`) Returns the [canonical output format](g) for the current page, if defined. Once you have captured the object, use any of its [associated methods][]. + +```go-html-template +{{ with .Site.Home.OutputFormats.Canonical }} + {{ .MediaType.Type }} → text/html + {{ .MediaType.MainType }} → text + {{ .MediaType.SubType }} → html + {{ .Name }} → html + {{ .Permalink }} → https://example.org/ + {{ .Rel }} → canonical + {{ .RelPermalink }} → / +{{ end }} +``` + +### Get + +(`page.OutputFormat`) Returns the `OutputFormat` object with the given identifier. Once you have captured the object, use any of its [associated methods][]. + +```go-html-template +{{ with .Site.Home.OutputFormats.Get "rss" }} + {{ .MediaType.Type }} → application/rss+xml + {{ .MediaType.MainType }} → application + {{ .MediaType.SubType }} → rss + {{ .Name }} → rss + {{ .Permalink }} → https://example.org/index.xml + {{ .Rel }} → alternate + {{ .RelPermalink }} → /index.xml +{{ end }} +``` + +## Examples + +To render a `link` element pointing to the [canonical output format](g) for the current page: + +```go-html-template +{{ with .OutputFormats.Canonical }} + {{ printf "" .Rel .MediaType.Type .Permalink | safeHTML }} +{{ end }} +``` + +To render an anchor element pointing to the `rss` output format for the current page: ```go-html-template {{ with .OutputFormats.Get "rss" }} @@ -27,12 +67,7 @@ To link to the RSS feed for the current page: {{ end }} ``` -On the site's home page, Hugo renders this to: - -```html -RSS Feed -``` - Please see the [link to output formats] section to understand the importance of the construct above. +[associated methods]: /methods/output-format/ [link to output formats]: /configuration/output-formats/#link-to-output-formats diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md index df565f716..1ff9cd601 100644 --- a/docs/content/en/methods/page/Path.md +++ b/docs/content/en/methods/page/Path.md @@ -9,8 +9,6 @@ params: signatures: [PAGE.Path] --- -{{< new-in 0.123.0 />}} - The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file. {{% glossary-term "logical path" %}} diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md index dd472de88..a99ca2f21 100644 --- a/docs/content/en/methods/page/Resources.md +++ b/docs/content/en/methods/page/Resources.md @@ -41,7 +41,7 @@ When working with global resources instead of page resources, use the [`resource ### GetMatch -(`resource.Resource`) Returns the first page resource from paths matching the given [glob](g) pattern, or nil if none found. +(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern](g), or nil if none found. ```go-html-template {{ with .Resources.GetMatch "images/*.jpg" }} @@ -53,7 +53,7 @@ When working with global resources instead of page resources, use the [`resource ### Match -(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob](g) pattern, or nil if none found. +(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern](g), or nil if none found. ```go-html-template {{ range .Resources.Match "images/*.jpg" }} @@ -78,7 +78,7 @@ This method is currently only useful in [js.Batch](/functions/js/batch/#import-c ## Pattern matching -With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob](g) pattern. +With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern](g). {{% include "/_common/glob-patterns.md" %}} diff --git a/docs/content/en/methods/page/Rotate.md b/docs/content/en/methods/page/Rotate.md new file mode 100644 index 000000000..99cb69cc8 --- /dev/null +++ b/docs/content/en/methods/page/Rotate.md @@ -0,0 +1,46 @@ +--- +title: Rotate +description: Returns a collection of all pages sharing the same identity across the specified dimension, including the current page, sorted by the dimension's weight. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Rotate DIMENSION] +--- + +{{< new-in 0.153.0 />}} + +The `Rotate` method on a `Page` object returns a collection of all pages sharing the same identity across the specified [dimension](g), including the current page, sorted by the dimension's weight. + +The `DIMENSION` argument must be one of `language`, `role`, or `version`. + +To render a list of all translations of the current page, including the current page: + +```go-html-template +{{ with .Rotate "language" }} + {{ range . }} +

{{ .LinkTitle }}

+ {{ end }} +{{ end }} +``` + +To render a list of all [roles](g) of the current page, including the current page: + +```go-html-template +{{ with .Rotate "role" }} + {{ range . }} +

{{ .LinkTitle }}

+ {{ end }} +{{ end }} +``` + +To render a list of all versions of the current page, including the current page: + +```go-html-template +{{ with .Rotate "version" }} + {{ range . }} +

{{ .LinkTitle }}

+ {{ end }} +{{ end }} +``` diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md index 3a4f2ad62..5dafb86b2 100644 --- a/docs/content/en/methods/page/Sitemap.md +++ b/docs/content/en/methods/page/Sitemap.md @@ -23,8 +23,6 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp ### Disable -{{< new-in 0.125.0 />}} - (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. ```go-html-template diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md index 8677226d7..308376680 100644 --- a/docs/content/en/methods/page/Sites.md +++ b/docs/content/en/methods/page/Sites.md @@ -51,7 +51,7 @@ Produces a list of links to each home page: ``` -To render a link to the home page of the site corresponding to the default content language: +To render a link to the home page of the [default site](g): ```go-html-template {{ with .Sites.Default }} diff --git a/docs/content/en/methods/resource/Colors.md b/docs/content/en/methods/resource/Colors.md index 14d0a40d8..3006c6a20 100644 --- a/docs/content/en/methods/resource/Colors.md +++ b/docs/content/en/methods/resource/Colors.md @@ -11,7 +11,7 @@ params: {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. +The `Colors` method on a `Resource` image object returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. ## Methods @@ -19,14 +19,10 @@ Each color is an object with the following methods: ### ColorHex -{{< new-in 0.125.0 />}} - (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign. ### Luminance -{{< new-in 0.125.0 />}} - (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. > [!note] diff --git a/docs/content/en/methods/resource/Crop.md b/docs/content/en/methods/resource/Crop.md index 97b3b95d3..d476803d9 100644 --- a/docs/content/en/methods/resource/Crop.md +++ b/docs/content/en/methods/resource/Crop.md @@ -1,33 +1,35 @@ --- title: Crop -description: Applicable to images, returns an image resource cropped to the given dimensions without resizing. +description: Applicable to images, returns a new image resource cropped according to the given processing specification. categories: [] keywords: [] params: functions_and_methods: returnType: images.ImageResource - signatures: [RESOURCE.Crop SPEC] + signatures: [RESOURCE.Crop SPECIFICATION] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Crop an image to match the given dimensions without resizing. You must provide both width and height. +Crop an image according to the given [processing specification][]. When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any. ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Crop "200x200" }} + {{ with .Crop "200x200 TopRight" }} {{ end }} {{ end }} ``` +In the example above, `"200x200 TopRight"` is the _processing specification_. + {{% include "/_common/methods/resource/processing-spec.md" %}} ## Example ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Crop "200x200 topright webp q85 lanczos" }} + {{ with .Crop "200x200 TopRight" }} {{ end }} {{ end }} @@ -37,6 +39,8 @@ Crop an image to match the given dimensions without resizing. You must provide b src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="crop 200x200 topright webp q85 lanczos" + filterArgs="crop 200x200 TopRight" example=true >}} + +[processing specification]: #processing-specification diff --git a/docs/content/en/methods/resource/Exif.md b/docs/content/en/methods/resource/Exif.md index 443a0ee1a..4df1eef5b 100644 --- a/docs/content/en/methods/resource/Exif.md +++ b/docs/content/en/methods/resource/Exif.md @@ -1,17 +1,22 @@ --- title: Exif -description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an EXIF object containing image metadata. +description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata. categories: [] -keywords: [] +keywords: ['metadata'] params: functions_and_methods: - returnType: exif.ExifInfo + returnType: meta.ExifInfo signatures: [RESOURCE.Exif] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metadata. +Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an object containing [Exif][Exif_Definition] metadata. + +To extract [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata, use the [`Meta`] method instead. + +> [!note] +> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images. ## Methods @@ -21,62 +26,63 @@ Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `R ### Lat -(`float64`) Returns the GPS latitude in degrees. +(`float64`) Returns the GPS latitude in degrees from Exif metadata. ### Long -(`float64`) Returns the GPS longitude in degrees. +(`float64`) Returns the GPS longitude in degrees from Exif metadata. ### Tags -(`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection. See [configure imaging]. - -[configure imaging]: /configuration/imaging/#exif-data +(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your site configuration. ## Examples -To list the creation date, location, and EXIF tags: +To list the creation date, latitude, and longitude: ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ with .Exif }} -

Date: {{ .Date }}

-

Lat/Long: {{ .Lat }}/{{ .Long }}

- {{ with .Tags }} -

Tags

- - - - - - {{ range $k, $v := . }} - - {{ end }} - -
TagValue
{{ $k }}{{ $v }}
- {{ end }} + 
+      {{ printf "%-25s %v\n" "Date" .Date }}
+      {{ printf "%-25s %v\n" "Latitude" .Lat }}
+      {{ printf "%-25s %v\n" "Longitude" .Long }}
+
{{ end }} {{ end }} ``` -To list specific values: +To list the available Exif fields: ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ with .Exif }} -
    - {{ with .Date }}
  • Date: {{ .Format "January 02, 2006" }}
    • {{ end }} - {{ with .Tags.ApertureValue }}
  • Aperture: {{ lang.FormatNumber 2 . }}
    • {{ end }} - {{ with .Tags.BrightnessValue }}
  • Brightness: {{ lang.FormatNumber 2 . }}
    • {{ end }} - {{ with .Tags.ExposureTime }}
  • Exposure Time: {{ . }}
    • {{ end }} - {{ with .Tags.FNumber }}
  • F Number: {{ . }}
    • {{ end }} - {{ with .Tags.FocalLength }}
  • Focal Length: {{ . }}
    • {{ end }} - {{ with .Tags.ISOSpeedRatings }}
  • ISO Speed Ratings: {{ . }}
    • {{ end }} - {{ with .Tags.LensModel }}
  • Lens Model: {{ . }}
    • {{ end }} -
+ 
+      {{ range $k, $v := .Tags -}}
+        {{ printf "%-25s %v\n" $k $v }}
+      {{ end }}
+
{{ end }} {{ end }} ``` -[exif]: https://en.wikipedia.org/wiki/Exif +To list specific Exif fields: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Exif }} + 
+      {{ with .Tags.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
+      {{ with .Tags.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
+
+ {{ end }} +{{ end }} +``` + +[`excludeFields`]: /configuration/imaging/#excludefields +[`includeFields`]: /configuration/imaging/#includefields +[`Meta`]: /methods/resource/meta/ [`time.Format`]: /functions/time/format/ +[Exif_Definition]: https://en.wikipedia.org/wiki/Exif +[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model +[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform diff --git a/docs/content/en/methods/resource/Fill.md b/docs/content/en/methods/resource/Fill.md index 82c696c91..ba6577ff1 100644 --- a/docs/content/en/methods/resource/Fill.md +++ b/docs/content/en/methods/resource/Fill.md @@ -1,33 +1,35 @@ --- title: Fill -description: Applicable to images, returns an image resource cropped and resized to the given dimensions. +description: Applicable to images, returns a new image resource cropped and resized according to the given processing specification. categories: [] keywords: [] params: functions_and_methods: returnType: images.ImageResource - signatures: [RESOURCE.Fill SPEC] + signatures: [RESOURCE.Fill SPECIFICATION] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Crop and resize an image to match the given dimensions. You must provide both width and height. +Crop and resize an image according to the given [processing specification][]. You must provide both width and height (such as `500x200`) within the specification. Unlike [`Resize`][], which may stretch the image, `Fill` maintains the original aspect ratio by cropping the image to the target ratio before resizing. The operation uses the [anchor](#anchor) and [resampling filter](#resampling-filter) provided, if any. ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Fill "200x200" }} + {{ with .Fill "500x200 TopRight lanczos" }} {{ end }} {{ end }} ``` +In the example above, `"500x200 TopRight lanczos"` is the _processing specification_. + {{% include "/_common/methods/resource/processing-spec.md" %}} ## Example ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Fill "200x200 top webp q85 lanczos" }} + {{ with .Fill "500x200 TopRight lanczos webp q85" }} {{ end }} {{ end }} @@ -37,6 +39,9 @@ Crop and resize an image to match the given dimensions. You must provide both wi src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="fill 200x200 top webp q85 lanczos" + filterArgs="fill 500x200 TopRight lanczos webp q85" example=true >}} + +[`Resize`]: /methods/resource/resize/ +[processing specification]: #processing-specification diff --git a/docs/content/en/methods/resource/Filter.md b/docs/content/en/methods/resource/Filter.md index b83c3d8cb..37fc656d1 100644 --- a/docs/content/en/methods/resource/Filter.md +++ b/docs/content/en/methods/resource/Filter.md @@ -2,8 +2,9 @@ title: Filter description: Applicable to images, applies one or more image filters to the given image resource. categories: [] -keywords: [] +keywords: [filter] params: + alt_title: RESOURCE.Filter functions_and_methods: returnType: images.ImageResource signatures: [RESOURCE.Filter FILTER...] diff --git a/docs/content/en/methods/resource/Fit.md b/docs/content/en/methods/resource/Fit.md index 7b416c4a1..c7991f4a6 100644 --- a/docs/content/en/methods/resource/Fit.md +++ b/docs/content/en/methods/resource/Fit.md @@ -1,33 +1,35 @@ --- title: Fit -description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. +description: Applicable to images, returns a new image resource downscaled to fit according to the given processing specification. categories: [] keywords: [] params: functions_and_methods: returnType: images.ImageResource - signatures: [RESOURCE.Fit SPEC] + signatures: [RESOURCE.Fit SPECIFICATION] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. +Downscale an image to fit according to the given [processing specification][] while maintaining the aspect ratio. You must provide both width and height (such as `600x400`) within the specification. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, it remains its original size. The operation uses the [resampling filter](#resampling-filter) provided, if any. ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Fit "200x200" }} + {{ with .Fit "300x175 lanczos" }} {{ end }} {{ end }} ``` +In the example above, `"300x175 lanczos"` is the _processing specification_. + {{% include "/_common/methods/resource/processing-spec.md" %}} ## Example ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Fit "300x175 webp q85 lanczos" }} + {{ with .Fit "300x175 lanczos" }} {{ end }} {{ end }} @@ -37,6 +39,10 @@ Downscale an image to fit the given dimensions while maintaining aspect ratio. Y src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="fit 300x175 webp q85 lanczos" + filterArgs="fit 300x175 lanczos" example=true >}} + +[`Resize`]: /methods/resource/resize/ +[`Fill`]: /methods/resource/fill/ +[processing specification]: #processing-specification diff --git a/docs/content/en/methods/resource/Meta.md b/docs/content/en/methods/resource/Meta.md new file mode 100644 index 000000000..a1c8a9010 --- /dev/null +++ b/docs/content/en/methods/resource/Meta.md @@ -0,0 +1,167 @@ +--- +title: Meta +description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata. +categories: [] +keywords: ['metadata'] +params: + functions_and_methods: + returnType: meta.MetaInfo + signatures: [RESOURCE.Meta] +--- + +{{< new-in 0.155.3 />}} + +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + +Applicable to JPEG, PNG, TIFF, and WebP images, the `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata. + +To extract Exif metadata only, use the [`Exif`] method instead. + +> [!note] +> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images. + +## Methods + +### Date + +(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. + +### Lat + +(`float64`) Returns the GPS latitude in degrees from Exif metadata, with a fallback to XMP metadata. + +### Long + +(`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata. + +### Orientation + +(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values: + +Value|Description +:--|:-- +`1`|Horizontal (normal) +`2`|Mirrored horizontal +`3`|Rotated 180 degrees +`4`|Mirrored vertical +`5`|Mirrored horizontal and rotated 270 degrees clockwise +`6`|Rotated 90 degrees clockwise +`7`|Mirrored horizontal and rotated 90 degrees clockwise +`8`|Rotated 270 degrees clockwise +{class="!mt-0"} + +> [!tip] +> Use the [`images.AutoOrient`] image filter to rotate and flip an image as needed per its Exif orientation tag + +### Exif + +(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. + +### IPTC + +(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. + +### XMP + +(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your site configuration. + +## Examples + +To list the creation date, latitude, longitude, and orientation: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ printf "%-25s %v\n" "Date" .Date }}
+      {{ printf "%-25s %v\n" "Latitude" .Lat }}
+      {{ printf "%-25s %v\n" "Longitude" .Long }}
+      {{ printf "%-25s %v\n" "Orientation" .Orientation }}
+
+ {{ end }} +{{ end }} +``` + +To list the available Exif fields: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ range $k, $v := .Exif -}}
+        {{ printf "%-25s %v\n" $k $v }}
+      {{ end }}
+
+ {{ end }} +{{ end }} +``` + +To list the available IPTC fields: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ range $k, $v := .IPTC -}}
+        {{ printf "%-25s %v\n" $k $v }}
+      {{ end }}
+
+ {{ end }} +{{ end }} +``` + +To list the available XMP fields: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ range $k, $v := .XMP -}}
+        {{ printf "%-25s %v\n" $k $v }}
+      {{ end }}
+
+ {{ end }} +{{ end }} +``` + +To list the available Exif, IPTC, and XMP fields together: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ range $k, $v := merge .Exif .IPTC .XMP -}}
+        {{ printf "%-25s %v\n" $k $v }}
+      {{ end }}
+
+ {{ end }} +{{ end }} +``` + +To list specific values: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ with .Meta }} + 
+      {{ with .Exif.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
+      {{ with .Exif.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
+
+      {{ with .IPTC.Headline }}{{ printf "%-25s %v\n" "Headline" . }}{{ end }}
+      {{ with index .IPTC "Province-State" }}{{ printf "%-25s %v\n" "Province-State" . }}{{ end }}
+
+      {{ with .XMP.Creator }}{{ printf "%-25s %v\n" "Creator" . }}{{ end }}
+      {{ with .XMP.Subject }}{{ printf "%-25s %v\n" "Subject" . }}{{ end }}
+
+ {{ end }} +{{ end }} +``` + +[`Exif`]: /methods/resource/exif/ +[`fields`]: /configuration/imaging/#fields +[`images.AutoOrient`]: /functions/images/autoorient/ +[`sources`]: /configuration/imaging/#sources +[`time.Format`]: /functions/time/format/ +[Exif_Definition]: https://en.wikipedia.org/wiki/Exif +[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model +[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform diff --git a/docs/content/en/methods/resource/Process.md b/docs/content/en/methods/resource/Process.md index fb27da54e..e006d23ce 100644 --- a/docs/content/en/methods/resource/Process.md +++ b/docs/content/en/methods/resource/Process.md @@ -1,26 +1,29 @@ --- title: Process -description: Applicable to images, returns an image resource processed with the given specification. +description: Applicable to images, returns a new image resource processed according to the given processing specification. categories: [] -keywords: [] +keywords: [process] params: + alt_title: RESOURCE.Process functions_and_methods: returnType: images.ImageResource - signatures: [RESOURCE.Process SPEC] + signatures: [RESOURCE.Process SPECIFICATION] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Process an image with the given specification. The specification can contain an optional action, one of `crop`, `fill`, `fit`, or `resize`. This means that you can use this method instead of [`Crop`], [`Fill`], [`Fit`], or [`Resize`]. +Process an image according to the given [processing specification][]. This versatile method supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string. ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Process "crop 200x200" }} + {{ with .Process "crop 200x200 TopRight webp q50" }} {{ end }} {{ end }} ``` +In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_. + You can also use this method to apply simple transformations such as rotation and conversion: ```go-html-template @@ -39,7 +42,7 @@ The `Process` method is also available as a filter, which is more effective if y ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Process "crop 200x200 topright webp q85 lanczos" }} + {{ with .Process "crop 200x200 TopRight webp q50" }} {{ end }} {{ end }} @@ -49,12 +52,9 @@ The `Process` method is also available as a filter, which is more effective if y src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="crop 200x200 topright webp q85 lanczos" + filterArgs="crop 200x200 TopRight webp q50" example=true >}} -[`Crop`]: /methods/resource/crop/ -[`Fill`]: /methods/resource/fill/ -[`Fit`]: /methods/resource/fit/ -[`Resize`]: /methods/resource/resize/ [`images.Process`]: /functions/images/process/ +[processing specification]: #processing-specification diff --git a/docs/content/en/methods/resource/Resize.md b/docs/content/en/methods/resource/Resize.md index 93c029ba6..c26017abf 100644 --- a/docs/content/en/methods/resource/Resize.md +++ b/docs/content/en/methods/resource/Resize.md @@ -1,35 +1,35 @@ --- title: Resize -description: Applicable to images, returns an image resource resized to the given width and/or height. +description: Applicable to images, returns a new image resource resized according to the given processing specification. categories: [] keywords: [] params: functions_and_methods: returnType: images.ImageResource - signatures: [RESOURCE.Resize SPEC] + signatures: [RESOURCE.Resize SPECIFICATION] --- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -Resize an image to the given width and/or height. - -If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. +Resize an image according to the given [processing specification][]. You may specify only the width (such as `300x`) or only the height (`such as x150`) for proportional scaling. If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions; if the aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed). The operation uses the [resampling filter](#resampling-filter) provided, if any. ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Resize "300x" }} + {{ with .Resize "300x lanczos" }} {{ end }} {{ end }} ``` +In the example above, `"300x lanczos"` is the _processing specification_. + {{% include "/_common/methods/resource/processing-spec.md" %}} ## Example ```go-html-template {{ with resources.Get "images/original.jpg" }} - {{ with .Resize "300x webp q85 lanczos" }} + {{ with .Resize "300x lanczos" }} {{ end }} {{ end }} @@ -39,6 +39,8 @@ If you specify both width and height, the resulting image will be disproportiona src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Process" - filterArgs="resize 300x webp q85 lanczos" + filterArgs="resize 300x lanczos" example=true >}} + +[processing specification]: #processing-specification diff --git a/docs/content/en/methods/site/Dimension.md b/docs/content/en/methods/site/Dimension.md new file mode 100644 index 000000000..67297a353 --- /dev/null +++ b/docs/content/en/methods/site/Dimension.md @@ -0,0 +1,36 @@ +--- +title: Dimension +description: Returns the dimension object for the given dimension for the given site. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: page.SiteDimension + signatures: [SITE.Dimension DIMENSION] +--- + +{{< new-in 0.153.0 />}} + +The `Dimension` method on a `Site` object returns the dimension object for the given [dimension](g). + +The `DIMENSION` argument must be one of `language`, `role`, or `version`. + +Example|Returns|Equivalent to +:--|:--|:-- +`{{ .Site.Dimension "language" }}`|`langs.Language`|`{{ .Site.Language }}` +`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}` +`{{ .Site.Dimension "version" }}`|`version.Version`|`{{ .Site.Version }}` + +```go-html-template +{{ $languageObject := .Site.Dimension "language" }} +{{ $languageObject.IsDefault }} → true +{{ $languageObject.Name }} → en + +{{ $roleObject := .Site.Dimension "role" }} +{{ $roleObject.IsDefault }} → true +{{ $roleObject.Name }} → guest + +{{ $versionObject := .Site.Dimension "version" }} +{{ $versionObject.IsDefault }} → true +{{ $versionObject.Name }} → v1.0.0 +``` diff --git a/docs/content/en/methods/site/DisqusShortname.md b/docs/content/en/methods/site/DisqusShortname.md deleted file mode 100644 index de679fd7e..000000000 --- a/docs/content/en/methods/site/DisqusShortname.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: DisqusShortname -description: Returns the Disqus shortname as defined in the site configuration. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: string - signatures: [SITE.DisqusShortname] -expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 ---- - -{{< deprecated-in 0.120.0 >}} -Use [`Site.Config.Services.Disqus.Shortname`] instead. - -[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/GoogleAnalytics.md b/docs/content/en/methods/site/GoogleAnalytics.md deleted file mode 100644 index e4d28bcce..000000000 --- a/docs/content/en/methods/site/GoogleAnalytics.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: GoogleAnalytics -description: Returns the Google Analytics tracking ID as defined in the site configuration. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: string - signatures: [SITE.GoogleAnalytics] -expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 ---- - -{{< deprecated-in 0.120.0 >}} -Use [`Site.Config.Services.GoogleAnalytics.ID`] instead. - -[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/IsDevelopment.md b/docs/content/en/methods/site/IsDevelopment.md deleted file mode 100644 index cddd18818..000000000 --- a/docs/content/en/methods/site/IsDevelopment.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: IsDevelopment -description: Reports whether the current running environment is “development”. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: bool - signatures: [SITE.IsDevelopment] -expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 ---- - -{{< deprecated-in 0.120.0 >}} -Use [`hugo.IsDevelopment`] instead. - -[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/IsMultiLingual.md b/docs/content/en/methods/site/IsMultiLingual.md deleted file mode 100644 index 3f9723f1c..000000000 --- a/docs/content/en/methods/site/IsMultiLingual.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: IsMultiLingual -description: Reports whether there are two or more configured languages. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: bool - signatures: [SITE.IsMultiLingual] -expiryDate: 2026-03-16 # deprecated 2024-03-16 in 0.124.0 ---- - -{{< deprecated-in 0.124.0 >}} -Use [`hugo.IsMultilingual`] instead. - -[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/IsServer.md b/docs/content/en/methods/site/IsServer.md deleted file mode 100644 index 8b09c8492..000000000 --- a/docs/content/en/methods/site/IsServer.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: IsServer -description: Reports whether the built-in development server is running. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: bool - signatures: [SITE.IsServer] -expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0 ---- - -{{< deprecated-in 0.120.0 >}} -Use [`hugo.IsServer`] instead. - -[`hugo.IsServer`]: /functions/hugo/isserver/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/Language.md b/docs/content/en/methods/site/Language.md index 73a64e4cc..2550ad585 100644 --- a/docs/content/en/methods/site/Language.md +++ b/docs/content/en/methods/site/Language.md @@ -9,13 +9,13 @@ params: signatures: [SITE.Language] --- -The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration. +The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration. You can also use the `Language` method on a `Page` object. See [details]. ## Methods -The examples below assume the following in your site configuration: +The examples below assume the following in the site configuration: {{< code-toggle file=hugo >}} [languages.de] @@ -25,9 +25,19 @@ languageName = 'Deutsch' weight = 1 {{< /code-toggle >}} +### IsDefault + +{{< new-in 0.153.0 />}} + +(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration. + +```go-html-template +{{ .Site.Language.IsDefault }} → true +``` + ### Lang -(`string`) The language tag as defined by [RFC 5646]. +(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. ```go-html-template {{ .Site.Language.Lang }} → de @@ -57,6 +67,14 @@ weight = 1 {{ .Site.Language.LanguageName }} → Deutsch ``` +### Name + +(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. This is an alias for `Lang`. + +```go-html-template +{{ .Site.Language.Name }} → de +``` + ### Weight (`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object. @@ -76,5 +94,6 @@ Some of the methods above are commonly used in a base template as attributes for > ``` +[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage [details]: /methods/page/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/docs/content/en/methods/site/LastChange.md b/docs/content/en/methods/site/LastChange.md deleted file mode 100644 index e02937bf1..000000000 --- a/docs/content/en/methods/site/LastChange.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: LastChange -description: Returns the last modification date of site content. -categories: [] -keywords: [] -params: - functions_and_methods: - returnType: time.Time - signatures: [SITE.LastChange] -expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 ---- - -{{< deprecated-in 0.123.0 >}} -Use [`.Site.Lastmod`] instead. - -[`.Site.Lastmod`]: /methods/site/lastmod/ -{{< /deprecated-in >}} diff --git a/docs/content/en/methods/site/Lastmod.md b/docs/content/en/methods/site/Lastmod.md index 38f6da2fa..2dec75001 100644 --- a/docs/content/en/methods/site/Lastmod.md +++ b/docs/content/en/methods/site/Lastmod.md @@ -9,8 +9,6 @@ params: signatures: [SITE.Lastmod] --- -{{< new-in 0.123.0 />}} - The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example: ```go-html-template diff --git a/docs/content/en/methods/site/Role.md b/docs/content/en/methods/site/Role.md new file mode 100644 index 000000000..cec6f8ffa --- /dev/null +++ b/docs/content/en/methods/site/Role.md @@ -0,0 +1,34 @@ +--- +title: Role +description: Returns the role object for the given site. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: roles.RoleSite + signatures: [SITE.Role] +--- + +{{< new-in 0.153.0 />}} + +The `Role` method on a `Site` object returns the role object for the given site. The role object is derived from the role definition in the site configuration. + +## Methods + +### IsDefault + +(`bool`) Reports whether this is the default role object as defined by the [`defaultContentRole`][] setting in the site configuration. + +```go-html-template +{{ .Site.Role.IsDefault }} → true +``` + +### Name + +(`string`) Returns the role name. This is the lower cased key from the site configuration. + +```go-html-template +{{ .Site.Role.Name }} → guest +``` + +[`defaultContentRole`]: /configuration/all/#defaultcontentrole diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md index cca71a40a..7d5d02724 100644 --- a/docs/content/en/methods/site/Sites.md +++ b/docs/content/en/methods/site/Sites.md @@ -49,7 +49,7 @@ Produces a list of links to each home page: ``` -To render a link to the home page of the site corresponding to the default content language: +To render a link to the home page of the [default site](g): ```go-html-template {{ with .Site.Sites.Default }} diff --git a/docs/content/en/methods/site/Version.md b/docs/content/en/methods/site/Version.md new file mode 100644 index 000000000..1c8870cc5 --- /dev/null +++ b/docs/content/en/methods/site/Version.md @@ -0,0 +1,34 @@ +--- +title: Version +description: Returns the version object for the given site. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: versions.Version + signatures: [SITE.Version] +--- + +{{< new-in 0.153.0 />}} + +The `Version` method on a `Site` object returns the version object for the given site. The version object is derived from the version definition in the site configuration. + +## Methods + +### IsDefault + +(`bool`) Reports whether this is the default version object as defined by the [`defaultContentVersion`][] setting in the site configuration. + +```go-html-template +{{ .Site.Version.IsDefault }} → true +``` + +### Name + +(`string`) Returns the version name. This is the lower cased key from the site configuration. + +```go-html-template +{{ .Site.Version.Name }} → v1.0.0 +``` + +[`defaultContentVersion`]: /configuration/all/#defaultcontentversion diff --git a/docs/content/en/methods/taxonomy/Page.md b/docs/content/en/methods/taxonomy/Page.md index b0b5d3aff..628148e4d 100644 --- a/docs/content/en/methods/taxonomy/Page.md +++ b/docs/content/en/methods/taxonomy/Page.md @@ -9,8 +9,6 @@ params: signatures: [TAXONOMY.Page] --- -{{< new-in 0.125.0 />}} - This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively: ```go-html-template diff --git a/docs/content/en/quick-reference/glob-patterns.md b/docs/content/en/quick-reference/glob-patterns.md new file mode 100644 index 000000000..13cd01f54 --- /dev/null +++ b/docs/content/en/quick-reference/glob-patterns.md @@ -0,0 +1,38 @@ +--- +title: Glob patterns +description: A quick reference guide to glob pattern syntax and matching rules for wildcards, character sets, and delimiters, featuring illustrative examples. +categories: [] +keywords: [] +--- + +{{% glossary-term "glob pattern" %}} + +The table below details the supported glob pattern syntax and its matching behavior. Each example illustrates a specific match type, the pattern used, and the expected boolean result when evaluated against a test string. + +| Match type | Glob pattern | Test string | Match? | +| :--- | :--- | :--- | :--- | +| Simple wildcard | `a/*.md` | `a/page.md` | true | +| Literal match | `'a/*.md'` | `a/*.md` | true | +| Single-level wildcard | `a/*/page.md` | `a/b/page.md` | true | +| Single-level wildcard | `a/*/page.md` | `a/b/c/page.md` | false | +| Multi-level wildcard | `a/**/page.md` | `a/b/c/page.md` | true | +| Single character | `file.???` | `file.txt` | true | +| Single character | `file.???` | `file.js` | false | +| Delimiter exclusion | `?at` | `f/at` | false | +| Character list | `f.[jt]xt` | `f.txt` | true | +| Negated list | `f.[!j]xt` | `f.txt` | true | +| Character range | `f.[a-c].txt` | `f.b.txt` | true | +| Character range | `f.[a-c].txt` | `f.z.txt` | false | +| Negated range | `f.[!a-c].txt` | `f.z.txt` | true | +| Pattern alternates | `*.{jpg,png}` | `logo.png` | true | +| No match | `*.{jpg,png}` | `logo.webp` | false | + +The matching logic follows these rules: + +- Standard wildcard (`*`) matches any character except for a delimiter. +- Super wildcard (`**`) matches any character including delimiters. +- Single character (`?`) matches exactly one character, excluding delimiters. +- Negation (`!`) matches any character except those specified in a list or range when used inside brackets. +- Character ranges (`[a-z]`) match any single character within the specified range. + +The delimiter is a slash (`/`), except when matching semantic version strings, where the delimiter is a dot (`.`). diff --git a/docs/content/en/quick-reference/glossary/build.md b/docs/content/en/quick-reference/glossary/build.md index 79b7ec74a..9a4df3bb1 100644 --- a/docs/content/en/quick-reference/glossary/build.md +++ b/docs/content/en/quick-reference/glossary/build.md @@ -2,4 +2,4 @@ title: build --- -To _build_ a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations. +To _build_ (verb) a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations. diff --git a/docs/content/en/quick-reference/glossary/bundle.md b/docs/content/en/quick-reference/glossary/bundle.md index f30187811..fddc28ef8 100644 --- a/docs/content/en/quick-reference/glossary/bundle.md +++ b/docs/content/en/quick-reference/glossary/bundle.md @@ -2,4 +2,4 @@ title: bundle --- -See [page bundle](g). +See [_page bundle_](g). diff --git a/docs/content/en/quick-reference/glossary/canonical-output-format.md b/docs/content/en/quick-reference/glossary/canonical-output-format.md new file mode 100644 index 000000000..88842a11f --- /dev/null +++ b/docs/content/en/quick-reference/glossary/canonical-output-format.md @@ -0,0 +1,14 @@ +--- +title: canonical output format +--- + +The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your site configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`. + + By default, `html` is the only predefined _output format_ with this setting; the `rel` property for all others is set to `alternate`. If two or more _output formats_ for the current page have their `rel` property set to `canonical`, the _canonical output format_ is the first one specified in: + + - The [`outputs`][outputs_front_matter] front matter field of the current page, or + - The [`outputs`][outputs_site_config] section of your site configuration for the current [_page kind_](g). + + [`rel`]: /configuration/output-formats/#rel + [outputs_front_matter]: /configuration/outputs/#outputs-per-page + [outputs_site_config]: /configuration/outputs/#outputs-per-page-kind diff --git a/docs/content/en/quick-reference/glossary/chain.md b/docs/content/en/quick-reference/glossary/chain.md index bbbc14f49..c5d19b1b2 100644 --- a/docs/content/en/quick-reference/glossary/chain.md +++ b/docs/content/en/quick-reference/glossary/chain.md @@ -2,4 +2,4 @@ title: chain --- -To _chain_ is to connect one or more [_identifiers_](g) with a dot. An identifier can represent a [_method_](g), [_object_](g), or [_field_](g). For example, `.Site.Params.author.name` or `.Date.UTC.Hour`. +To _chain_ (verb) is to connect one or more [_identifiers_](g) with a dot. An identifier can represent a [_method_](g), [_object_](g), or [_field_](g). For example, `.Site.Params.author.name` or `.Date.UTC.Hour`. diff --git a/docs/content/en/quick-reference/glossary/cicd.md b/docs/content/en/quick-reference/glossary/cicd.md index 355097b1b..594a60e19 100644 --- a/docs/content/en/quick-reference/glossary/cicd.md +++ b/docs/content/en/quick-reference/glossary/cicd.md @@ -5,3 +5,12 @@ params: --- The term _CI/CD_ is an abbreviation for Continuous Integration and Continuous Delivery or Continuous Deployment depending on context. + + Popular _CI/CD_ platforms for building and deploying Hugo sites include [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], and [Vercel][]. + + [Cloudflare]: /host-and-deploy/host-on-cloudflare/ + [GitHub Pages]: /host-and-deploy/host-on-github-pages/ + [GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/ + [Netlify]: /host-and-deploy/host-on-netlify/ + [Render]: /host-and-deploy/host-on-render/ + [Vercel]: /host-and-deploy/host-on-vercel/ diff --git a/docs/content/en/quick-reference/glossary/component.md b/docs/content/en/quick-reference/glossary/component.md index 3c3c0236b..11820608b 100644 --- a/docs/content/en/quick-reference/glossary/component.md +++ b/docs/content/en/quick-reference/glossary/component.md @@ -15,3 +15,4 @@ A _component_ is a collection of related files, housed within the [_unified file templates|`layouts` translation tables|`i18n` static files|`static` + {class="!mt-0"} diff --git a/docs/content/en/quick-reference/glossary/content-dimension.md b/docs/content/en/quick-reference/glossary/content-dimension.md new file mode 100644 index 000000000..7317740e0 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/content-dimension.md @@ -0,0 +1,5 @@ +--- +title: content dimension +--- + +See [_dimension_](g). diff --git a/docs/content/en/quick-reference/glossary/content-type.md b/docs/content/en/quick-reference/glossary/content-type.md index ce2a59e17..758800ccf 100644 --- a/docs/content/en/quick-reference/glossary/content-type.md +++ b/docs/content/en/quick-reference/glossary/content-type.md @@ -2,4 +2,4 @@ title: content type --- -A _content type_ is a classification of content inferred from the top-level directory name or the `type` set in [front matter](g). Pages in the root of the `content` directory, including the home page, are of type "page". The content type is a contributing factor in the template lookup order and determines which [archetype](/content-management/archetypes/) template to use when creating new content. +A _content type_ is a classification of content inferred from the top-level directory name or the `type` set in [_front matter_](g). Pages in the root of the `content` directory, including the home page, are of type "page". The content type is a contributing factor in the template lookup order and determines which [_archetype_](g) template to use when creating new content. diff --git a/docs/content/en/quick-reference/glossary/default-site.md b/docs/content/en/quick-reference/glossary/default-site.md new file mode 100644 index 000000000..664643cf9 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/default-site.md @@ -0,0 +1,7 @@ +--- +title: default site +--- + +The _default site_ is the [_site_](g) identified by the primary value in each [_content dimension_](g). Specifically, it is the site that combines the first language, the first [_role_](g), and the first version defined in your site configuration. + + The "first" language and role are those with the lowest [weight](g). If weights are tied or undefined, Hugo defaults to lexicographical order. Similarly, the "first" version is the one with the lowest weight; if weights are tied or undefined, it is identified as the last version when sorted semantically. diff --git a/docs/content/en/quick-reference/glossary/dimension.md b/docs/content/en/quick-reference/glossary/dimension.md new file mode 100644 index 000000000..ba0bc5e8c --- /dev/null +++ b/docs/content/en/quick-reference/glossary/dimension.md @@ -0,0 +1,5 @@ +--- +title: dimension +--- + +A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, [_role_](g), and version. For example, a logical page may exist in 6 languages, 4 versions, and 2 _roles_. diff --git a/docs/content/en/quick-reference/glossary/glob-pattern.md b/docs/content/en/quick-reference/glossary/glob-pattern.md new file mode 100644 index 000000000..c57b452c1 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/glob-pattern.md @@ -0,0 +1,6 @@ +--- +title: glob pattern +reference: /quick-reference/glob-patterns/ +--- + +A _glob pattern_ is a pattern used to match sets of values. It is a shorthand for specifying multiple targets at once, making it easier to work with groups of data or configurations. diff --git a/docs/content/en/quick-reference/glossary/glob-slice.md b/docs/content/en/quick-reference/glossary/glob-slice.md new file mode 100644 index 000000000..faaa64581 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/glob-slice.md @@ -0,0 +1,16 @@ +--- +title: glob slice +--- + +A _glob slice_ is a [_slice_](g) of [_glob patterns_](g). Within the _slice_, a _glob_ can be negated by prefixing it with an exclamation mark (`!`) and one space. Matches in negated patterns short-circuit the evaluation of the rest of the _slice_, and are useful for early coarse grained exclusions. + + The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your site configuration: + + ```toml + [sites.matrix] + languages = [ "! no", "**" ] + versions = [ "! v1.2.3", "v1.*.*", "v2.*.*" ] + roles = [ "{member, guest}" ] + ``` + + The `versions` example above evaluates as: `(not v1.2.3) AND (v1.*.* OR v2.*.*)`. diff --git a/docs/content/en/quick-reference/glossary/glob.md b/docs/content/en/quick-reference/glossary/glob.md deleted file mode 100644 index bb9c5a4d8..000000000 --- a/docs/content/en/quick-reference/glossary/glob.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: glob -reference: https://github.com/gobwas/glob?tab=readme-ov-file#example ---- - -A _glob_ is a pattern used to match file names and paths. It's a shorthand for specifying a set of files, making it easier to work with multiple files at once. diff --git a/docs/content/en/quick-reference/glossary/interpreted-string-literal.md b/docs/content/en/quick-reference/glossary/interpreted-string-literal.md index a5d2cd326..fa92c976f 100644 --- a/docs/content/en/quick-reference/glossary/interpreted-string-literal.md +++ b/docs/content/en/quick-reference/glossary/interpreted-string-literal.md @@ -3,4 +3,4 @@ title: interpreted string literal reference: https://go.dev/ref/spec#String_literals --- -An _interpreted string literal_ is a character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. +An _interpreted string literal_ is a character sequence between double quotes, as in `"foo"`. Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. diff --git a/docs/content/en/quick-reference/glossary/list-page.md b/docs/content/en/quick-reference/glossary/list-page.md index b58ee4a35..d18efcfe7 100644 --- a/docs/content/en/quick-reference/glossary/list-page.md +++ b/docs/content/en/quick-reference/glossary/list-page.md @@ -2,4 +2,4 @@ title: list page --- -A list page is any [_page kind_](g) that receives a page [_collection_](g) in [_context_](g). This includes the home page, [section pages](g), [taxonomy pages](g), and [term pages](g). +A list page is any [_page kind_](g) that receives a page [_collection_](g) in [_context_](g). This includes the home page, [_section pages_](g), [_taxonomy pages_](g), and [_term pages_](g). diff --git a/docs/content/en/quick-reference/glossary/marshal.md b/docs/content/en/quick-reference/glossary/marshal.md index 3bb1623f5..ce7d769b5 100644 --- a/docs/content/en/quick-reference/glossary/marshal.md +++ b/docs/content/en/quick-reference/glossary/marshal.md @@ -3,4 +3,4 @@ title: marshal reference: /functions/transform/remarshal/ --- -To _marshal_ is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string. +To _marshal_ (verb) is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string. diff --git a/docs/content/en/quick-reference/glossary/output-format.md b/docs/content/en/quick-reference/glossary/output-format.md index df042d06b..aa5ddbdd7 100644 --- a/docs/content/en/quick-reference/glossary/output-format.md +++ b/docs/content/en/quick-reference/glossary/output-format.md @@ -3,4 +3,4 @@ title: output format reference: /configuration/output-formats/ --- -An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [page kind](g), or by enabling one or more output formats for specific pages. +An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [_page kind_](g), or by enabling one or more output formats for specific pages. diff --git a/docs/content/en/quick-reference/glossary/page-relative.md b/docs/content/en/quick-reference/glossary/page-relative.md new file mode 100644 index 000000000..11c485aa0 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/page-relative.md @@ -0,0 +1,7 @@ +--- +title: page-relative +--- + + A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`. + + See also: [_site-relative_](g), [_server-relative_](g). diff --git a/docs/content/en/quick-reference/glossary/paginate.md b/docs/content/en/quick-reference/glossary/paginate.md index d2467e098..1caf9a07f 100644 --- a/docs/content/en/quick-reference/glossary/paginate.md +++ b/docs/content/en/quick-reference/glossary/paginate.md @@ -2,4 +2,4 @@ title: paginate --- -To _paginate_ is to split a list page into two or more subsets. +To _paginate_ (verb) is to split a list page into two or more subsets. diff --git a/docs/content/en/quick-reference/glossary/partial-decorator.md b/docs/content/en/quick-reference/glossary/partial-decorator.md new file mode 100644 index 000000000..149e17ef2 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/partial-decorator.md @@ -0,0 +1,8 @@ +--- +title: partial decorator +reference: /templates/partial-decorators/ +--- + +A _partial decorator_ is specific type of [_partial_](g) that functions as a [_wrapper component_](g). While a standard partial simply renders data within a fixed template, a decorator uses composition to enclose an entire block of content. It utilizes the [`templates.Inner`][] function as a placeholder to define exactly where that external content should be injected within the wrapper's layout. + + [`templates.Inner`]: /functions/templates/inner/ diff --git a/docs/content/en/quick-reference/glossary/primary-output-format.md b/docs/content/en/quick-reference/glossary/primary-output-format.md index c40c0176c..d89fe2563 100644 --- a/docs/content/en/quick-reference/glossary/primary-output-format.md +++ b/docs/content/en/quick-reference/glossary/primary-output-format.md @@ -3,7 +3,7 @@ title: primary output format details: /configuration/outputs/ --- -A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [page kind](g). It is specified as the first entry within the [outputs configuration] for that page kind. +A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [_page kind_](g). It is specified as the first entry within the [outputs configuration] for that page kind. [`Permalink`]: /methods/page/permalink/ [`RelPermalink`]: /methods/page/relpermalink/ diff --git a/docs/content/en/quick-reference/glossary/processable-image.md b/docs/content/en/quick-reference/glossary/processable-image.md new file mode 100644 index 000000000..4359e4f7f --- /dev/null +++ b/docs/content/en/quick-reference/glossary/processable-image.md @@ -0,0 +1,15 @@ +--- +title: processable image +--- + +A _processable image_ is an image file characterized by one of the following [_media types_](g): + + - `image/gif` + - `image/jpeg` + - `image/png` + - `image/tiff` + - `image/webp` + + Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Resize`, etc. + + [resource methods]: /methods/resource diff --git a/docs/content/en/quick-reference/glossary/raw-string-literal.md b/docs/content/en/quick-reference/glossary/raw-string-literal.md index a3ceabe10..056c0e6fc 100644 --- a/docs/content/en/quick-reference/glossary/raw-string-literal.md +++ b/docs/content/en/quick-reference/glossary/raw-string-literal.md @@ -3,4 +3,4 @@ title: raw string literal reference: https://go.dev/ref/spec#String_literals --- -A _raw string literal_ is a character sequence between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value. +A _raw string literal_ is a character sequence between backticks, as in `` `bar` ``. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value. diff --git a/docs/content/en/quick-reference/glossary/resource-type.md b/docs/content/en/quick-reference/glossary/resource-type.md index 9a2412fb9..b10cd5925 100644 --- a/docs/content/en/quick-reference/glossary/resource-type.md +++ b/docs/content/en/quick-reference/glossary/resource-type.md @@ -2,4 +2,4 @@ title: resource type --- -A _resource type_ is the main type of a resource's [media type](/methods/resource/mediatype/). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object. +A _resource type_ is the main type of a resource's [_media type_](g). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object. diff --git a/docs/content/en/quick-reference/glossary/role.md b/docs/content/en/quick-reference/glossary/role.md new file mode 100644 index 000000000..be85f656d --- /dev/null +++ b/docs/content/en/quick-reference/glossary/role.md @@ -0,0 +1,5 @@ +--- +title: role +--- + +A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. Common use cases include user personas, access control, and intended audience. diff --git a/docs/content/en/quick-reference/glossary/rune-literal.md b/docs/content/en/quick-reference/glossary/rune-literal.md new file mode 100644 index 000000000..8a19b489b --- /dev/null +++ b/docs/content/en/quick-reference/glossary/rune-literal.md @@ -0,0 +1,10 @@ +--- +title: rune literal +reference: https://go.dev/ref/spec#Rune_literals +--- + +A _rune literal_ is the textual representation of a [_rune_](g) within a [_template_](g). It consists of a character sequence enclosed in single quotes, such as `'x'`, `'\n'`, or `'ü'`. + + Unlike [_interpreted string literals_](g) or [_raw string literals_](g), which represent a sequence of characters, a _rune literal_ represents a single [_integer_](g) value identifying a Unicode [code point][]. Within the quotes, any character may appear except a newline or an unescaped single quote. Multi-character sequences starting with a backslash (`\`) can be used to encode specific values, such as `\n` for a newline or `\u00FC` for the letter `ü`. + + [code point]: https://en.wikipedia.org/wiki/Code_point diff --git a/docs/content/en/quick-reference/glossary/rune.md b/docs/content/en/quick-reference/glossary/rune.md new file mode 100644 index 000000000..74dfa4b5b --- /dev/null +++ b/docs/content/en/quick-reference/glossary/rune.md @@ -0,0 +1,11 @@ +--- +title: rune +--- + +A _rune_ is a way to represent a single character as a number. In Hugo and Go, text is stored as a sequence of bytes. However, while a basic letter like `x` uses only one byte, a single character such as the German `ü` is made up of multiple bytes. A _rune_ represents the entire character as one single value, no matter how many bytes it takes to store it. + + Technically, a _rune_ is just another name for a 32-bit [_integer_](g). It stores the Unicode [code point][], which is the official number assigned to that specific character. + + When you want to manipulate text character-by-character rather than by raw data size, you are working with _runes_. You write a _rune_ in a [_template_](g) using a [_rune literal_](g), such as `'x'`, `'\n'`, or `'ü'`. + + [code point]: https://en.wikipedia.org/wiki/Code_point diff --git a/docs/content/en/quick-reference/glossary/scope.md b/docs/content/en/quick-reference/glossary/scope.md index 5a13312a6..5230340bd 100644 --- a/docs/content/en/quick-reference/glossary/scope.md +++ b/docs/content/en/quick-reference/glossary/scope.md @@ -2,4 +2,4 @@ title: scope --- -The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one [template](g) is not available within another. +The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one [_template_](g) is not available within another. diff --git a/docs/content/en/quick-reference/glossary/segment.md b/docs/content/en/quick-reference/glossary/segment.md index 5851a8825..612b16651 100644 --- a/docs/content/en/quick-reference/glossary/segment.md +++ b/docs/content/en/quick-reference/glossary/segment.md @@ -2,4 +2,4 @@ title: segment --- -A _segment_ is a subset of a site, filtered by [_logical path_](g), language, [_page kind_](g), or [_output format_](g). +A _segment_ is a subset of a site, filtered by [_logical path_](g), [_sites matrix_](g), [_page kind_](g), or [_output format_](g). diff --git a/docs/content/en/quick-reference/glossary/server-relative.md b/docs/content/en/quick-reference/glossary/server-relative.md new file mode 100644 index 000000000..4420ba504 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/server-relative.md @@ -0,0 +1,9 @@ +--- +title: server-relative +--- + + A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path. + + See also: [_page-relative_](g), [_site-relative_](g). + + [`baseURL`]: /configuration/all/#baseurl diff --git a/docs/content/en/quick-reference/glossary/site-relative.md b/docs/content/en/quick-reference/glossary/site-relative.md new file mode 100644 index 000000000..c6536a165 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/site-relative.md @@ -0,0 +1,7 @@ +--- +title: site-relative +--- + + A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path. + + See also: [_page-relative_](g), [_server-relative_](g). diff --git a/docs/content/en/quick-reference/glossary/site-root.md b/docs/content/en/quick-reference/glossary/site-root.md new file mode 100644 index 000000000..71c4477a8 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/site-root.md @@ -0,0 +1,13 @@ +--- +title: site root +--- + +The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as language, [_role_](g), or version. + + Project description|Site root examples + :--|:--|:-- + Monolingual|`/`, `/guest`, `/guest/v1.2.3` + Multilingual single-host|`/en`, `/guest/en`, `/guest/v1.2.3/en` + Multilingual multihost|`/en`, `/en/guest`, `/en/guest/v1.2.3` + + [`publishDir`]: /configuration/all/#publishdir diff --git a/docs/content/en/quick-reference/glossary/site.md b/docs/content/en/quick-reference/glossary/site.md new file mode 100644 index 000000000..1d2d016dc --- /dev/null +++ b/docs/content/en/quick-reference/glossary/site.md @@ -0,0 +1,5 @@ +--- +title: site +--- + +A _site_ is a specific instance of your project representing a unique combination of language, [_role_](g), and version. While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously. Each site operates with its own configuration, set of pages, and output destination, allowing you to serve tailored content to different audiences from one unified source. diff --git a/docs/content/en/quick-reference/glossary/sites-complements.md b/docs/content/en/quick-reference/glossary/sites-complements.md new file mode 100644 index 000000000..5854f288c --- /dev/null +++ b/docs/content/en/quick-reference/glossary/sites-complements.md @@ -0,0 +1,5 @@ +--- +title: sites complements +--- + +_sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary sites. The configuration is structured as a map of [_glob slices_](g). diff --git a/docs/content/en/quick-reference/glossary/sites-matrix.md b/docs/content/en/quick-reference/glossary/sites-matrix.md new file mode 100644 index 000000000..5900334e1 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/sites-matrix.md @@ -0,0 +1,9 @@ +--- +title: sites matrix +--- + +_sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which sites the content should be generated for. When defined in a file mount for [_templates_](g), it controls which sites the template will be applied to. + + In Hugo's multidimensional content model, the matrix defines the intersection of three dimensions: language, role, and version. The configuration is structured as a map of [_glob slices_](g). + + See also [_sites complements_](g), [front matter: sites](/content-management/front-matter/#sites), [module mounts: sites](/configuration/module/#sites), and [segments: sites](/configuration/segments/#sites). diff --git a/docs/content/en/quick-reference/glossary/taxonomic-weight.md b/docs/content/en/quick-reference/glossary/taxonomic-weight.md index 682bc056c..90bd804e0 100644 --- a/docs/content/en/quick-reference/glossary/taxonomic-weight.md +++ b/docs/content/en/quick-reference/glossary/taxonomic-weight.md @@ -1,6 +1,6 @@ --- title: taxonomic weight -reference: content-management/taxonomies/#order-taxonomies +reference: /content-management/taxonomies/#taxonomic-weight --- Defined in front matter and unique to each taxonomy, a _taxonomic weight_ is a [_weight_](g) that determines the sort order of page collections contained within a [`Taxonomy`](g) object. diff --git a/docs/content/en/quick-reference/glossary/taxonomy-object.md b/docs/content/en/quick-reference/glossary/taxonomy-object.md index 590490377..525446a8e 100644 --- a/docs/content/en/quick-reference/glossary/taxonomy-object.md +++ b/docs/content/en/quick-reference/glossary/taxonomy-object.md @@ -2,4 +2,4 @@ title: taxonomy object --- -A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [weighted pages](g) associated with each term. +A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [_weighted pages_](g) associated with each term. diff --git a/docs/content/en/quick-reference/glossary/theme.md b/docs/content/en/quick-reference/glossary/theme.md index fca98572d..4c6d15ecb 100644 --- a/docs/content/en/quick-reference/glossary/theme.md +++ b/docs/content/en/quick-reference/glossary/theme.md @@ -2,4 +2,4 @@ title: theme --- -A _theme_ is a [_module_](g) that delivers a complete set of [components](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme. +A _theme_ is a [_module_](g) that delivers a complete set of [_components_](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme. diff --git a/docs/content/en/quick-reference/glossary/type.md b/docs/content/en/quick-reference/glossary/type.md index dbc692e5a..18b9ab559 100644 --- a/docs/content/en/quick-reference/glossary/type.md +++ b/docs/content/en/quick-reference/glossary/type.md @@ -2,4 +2,4 @@ title: type --- -See [content type](g). +See [_content type_](g). diff --git a/docs/content/en/quick-reference/glossary/unmarshal.md b/docs/content/en/quick-reference/glossary/unmarshal.md index 0ed548a21..d449b0b8c 100644 --- a/docs/content/en/quick-reference/glossary/unmarshal.md +++ b/docs/content/en/quick-reference/glossary/unmarshal.md @@ -3,4 +3,4 @@ title: unmarshal reference: /functions/transform/unmarshal/ --- -To _unmarshal_ is to transform a serialized object into a data structure. For example, transforming a JSON file into a [_map_](g) that you can access within a template. +To _unmarshal_ (verb) is to transform a serialized object into a data structure. For example, transforming a JSON file into a [_map_](g) that you can access within a template. diff --git a/docs/content/en/quick-reference/glossary/vendor.md b/docs/content/en/quick-reference/glossary/vendor.md new file mode 100644 index 000000000..f745a4e15 --- /dev/null +++ b/docs/content/en/quick-reference/glossary/vendor.md @@ -0,0 +1,7 @@ +--- +title: vendor +--- + +To _vendor_ (verb) in a software context is the process of including the source code of third-party dependencies directly within your own project's repository, rather than downloading them on the fly from an external package manager. + + When you are asked to "vendor the dependencies into the project root," you are being told to move those external libraries from a temporary cache into a dedicated folder that gets committed to your version control system. diff --git a/docs/content/en/quick-reference/glossary/walk.md b/docs/content/en/quick-reference/glossary/walk.md index 09f9ecb20..2b2a84462 100644 --- a/docs/content/en/quick-reference/glossary/walk.md +++ b/docs/content/en/quick-reference/glossary/walk.md @@ -2,4 +2,4 @@ title: walk --- -To _walk_ is to recursively traverse a nested data structure. For example, rendering a multilevel menu. +To _walk_ (verb) is to recursively traverse a nested data structure. For example, rendering a multilevel menu. diff --git a/docs/content/en/quick-reference/glossary/weight.md b/docs/content/en/quick-reference/glossary/weight.md index deb9e6dc0..01b91fe52 100644 --- a/docs/content/en/quick-reference/glossary/weight.md +++ b/docs/content/en/quick-reference/glossary/weight.md @@ -2,4 +2,4 @@ title: weight --- -A _weight_ is a numeric value used to position an element within a sorted [collection](g). Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats. +A _weight_ is a numeric value used to position an element within a sorted [_collection_](g). Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, [_roles_](g), versions, and output formats. diff --git a/docs/content/en/quick-reference/glossary/wrapper-component.md b/docs/content/en/quick-reference/glossary/wrapper-component.md new file mode 100644 index 000000000..938a0271d --- /dev/null +++ b/docs/content/en/quick-reference/glossary/wrapper-component.md @@ -0,0 +1,7 @@ +--- +title: wrapper component +--- + +A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior. + + See also: [_partial decorator_](g) diff --git a/docs/content/en/render-hooks/code-blocks.md b/docs/content/en/render-hooks/code-blocks.md index f6af66d59..136c3b6d7 100755 --- a/docs/content/en/render-hooks/code-blocks.md +++ b/docs/content/en/render-hooks/code-blocks.md @@ -59,7 +59,6 @@ Page : (`page`) A reference to the current page. PageInner -: {{< new-in 0.125.0 />}} : (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). Position diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md index 44281bb3d..75c57d3d6 100755 --- a/docs/content/en/render-hooks/headings.md +++ b/docs/content/en/render-hooks/headings.md @@ -28,7 +28,6 @@ Page : (`page`) A reference to the current page. PageInner -: {{< new-in 0.125.0 />}} : (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). PlainText diff --git a/docs/content/en/render-hooks/images.md b/docs/content/en/render-hooks/images.md index 9f2625fee..e5f631cdc 100755 --- a/docs/content/en/render-hooks/images.md +++ b/docs/content/en/render-hooks/images.md @@ -45,7 +45,6 @@ Page : (`page`) A reference to the current page. PageInner -: {{< new-in 0.125.0 />}} : (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). PlainText @@ -99,8 +98,6 @@ wrapStandAloneImageWithinParagraph = false ## Embedded -{{< new-in 0.123.0 />}} - Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your site configuration. This is the default setting: {{< code-toggle file=hugo >}} diff --git a/docs/content/en/render-hooks/links.md b/docs/content/en/render-hooks/links.md index 623678ee1..d35869160 100755 --- a/docs/content/en/render-hooks/links.md +++ b/docs/content/en/render-hooks/links.md @@ -29,7 +29,6 @@ Page : (`page`) A reference to the current page. PageInner -: {{< new-in 0.125.0 />}} : (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details). PlainText @@ -72,8 +71,6 @@ To include a `rel` attribute set to `external` for external links: ## Embedded -{{< new-in 0.123.0 />}} - Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your site configuration. This is the default setting: {{< code-toggle file=hugo >}} diff --git a/docs/content/en/shortcodes/gist.md b/docs/content/en/shortcodes/gist.md deleted file mode 100755 index 03314da0f..000000000 --- a/docs/content/en/shortcodes/gist.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Gist shortcode -linkTitle: Gist -description: Embed a GitHub Gist in your content using the gist shortcode. -categories: [] -keywords: [] -expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0 ---- - -{{< deprecated-in 0.143.0 >}} -The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode: - -1. Create a new file: Create a file named `gist.html` within the `layouts/_shortcodes` directory. -1. Copy the source code: Paste the [original source code]({{% eturl gist %}}) of the gist shortcode into the newly created `gist.html` file. - -This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode. -{{< /deprecated-in >}} - -To display a GitHub gist with this URL: - -```text -https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b -``` - -Include this in your Markdown: - -```text -{{}} -``` - -To display a specific file within the gist: - -```text -{{}} -``` diff --git a/docs/content/en/shortcodes/youtube.md b/docs/content/en/shortcodes/youtube.md index d9f5fb739..1e72ee284 100755 --- a/docs/content/en/shortcodes/youtube.md +++ b/docs/content/en/shortcodes/youtube.md @@ -33,38 +33,30 @@ id : (`string`) The video `id`. Optional if the `id` is the first and only positional argument. allowFullScreen -: {{< new-in 0.125.0 />}} : (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`. autoplay -: {{< new-in 0.125.0 />}} : (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`. class : (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element. controls -: {{< new-in 0.125.0 />}} : (`bool`) Whether to display the video controls. Default is `true`. end -: {{< new-in 0.125.0 />}} : (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video. loading -: {{< new-in 0.125.0 />}} : (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`. loop -: {{< new-in 0.125.0 />}} : (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`. mute -: {{< new-in 0.125.0 />}} : (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`. start -: {{< new-in 0.125.0 />}} : (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video. title diff --git a/docs/content/en/showcase/1password-support/index.md b/docs/content/en/showcase/1password-support/index.md index 54a30f849..b75e54ecc 100644 --- a/docs/content/en/showcase/1password-support/index.md +++ b/docs/content/en/showcase/1password-support/index.md @@ -9,7 +9,7 @@ aliases: [/showcase/1password/] At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did. -### Not all static site generators are created equal +## Not all static site generators are created equal Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo: diff --git a/docs/content/en/showcase/forestry/index.md b/docs/content/en/showcase/forestry/index.md index 5b8872316..58ff8ee06 100644 --- a/docs/content/en/showcase/forestry/index.md +++ b/docs/content/en/showcase/forestry/index.md @@ -8,7 +8,7 @@ siteSource: https://github.com/forestryio/forestry.io It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us? -### Why Hugo? +## Why Hugo? In our early research we looked at Ionic's [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn't fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast. diff --git a/docs/content/en/templates/404.md b/docs/content/en/templates/404.md index 1a1a3c146..9704d40cd 100644 --- a/docs/content/en/templates/404.md +++ b/docs/content/en/templates/404.md @@ -4,7 +4,7 @@ linkTitle: 404 templates description: Create a template to render a 404 error page. categories: [] keywords: [] -weight: 190 +weight: 200 --- To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example: diff --git a/docs/content/en/templates/embedded.md b/docs/content/en/templates/embedded.md index daba32c3e..1ab5e04e7 100644 --- a/docs/content/en/templates/embedded.md +++ b/docs/content/en/templates/embedded.md @@ -3,7 +3,7 @@ title: Embedded partial templates description: Hugo provides embedded partial templates for common use cases. categories: [] keywords: [] -weight: 170 +weight: 180 aliases: [/templates/internal] --- @@ -90,7 +90,7 @@ disable : (`bool`) Whether to disable the template. Default is `false`. respectDoNotTrack -: (`bool`) Whether to respect the browser's "do not track" setting. Default is `false`. +: (`bool`) Whether to respect the browser's "do not track" setting. Default is `true`. ## Open Graph diff --git a/docs/content/en/templates/introduction.md b/docs/content/en/templates/introduction.md index 207cfc4a7..57a1ac1b7 100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@ -138,6 +138,30 @@ Hugo renders this to: Whitespace includes spaces, horizontal tabs, carriage returns, and newlines. +### Quote characters + +Hugo templates use different quote characters to define how text and characters are processed. + +Use double quotes for [interpreted string literals](g). These interpret backslashes as special instructions: + +```go-html-template +{{ print "Hello world\u0021" }} → Hello world! +``` + +Use backticks for [raw string literals](g). These ignore backslashes and treat every character literally: + +```go-html-template +{{ print `Hello world\u0021` }} → Hello world\u0021 +``` + +Use single quotes for [rune literals](g). Unlike strings, these represent a single character as its numerical Unicode value: + +```go-html-template +{{ print '!' }} → 33 +``` + +In practical terms, you will rarely, if ever, use rune literals in your template code. They are most commonly used in low-level programming; in a Hugo template, you will almost always want a string instead. + ### Pipes Within a template action you may [pipe](g) a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent: diff --git a/docs/content/en/templates/new-templatesystem-overview.md b/docs/content/en/templates/new-templatesystem-overview.md index a3b53197b..6f3f93f44 100644 --- a/docs/content/en/templates/new-templatesystem-overview.md +++ b/docs/content/en/templates/new-templatesystem-overview.md @@ -13,19 +13,19 @@ We have aimed to maintain as much backward compatibility as possible by mapping ## Changes to the `layouts` folder -| Description | Action required | -| ------------- | ------------- | -| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root.| -| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. | -| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. | -| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree.| No action required.| -| The above also means that there's no top-level `layouts/taxonomy` or `layouts/section` folders anymore, unless it represents a [Page path].|Move them up to `layouts/` with one of the [Page kinds] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. | -|A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`.|Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`.| -| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword.|Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`.| -| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering.|| -| We have removed the concept of `_internal` Hugo templates.[^internal]|Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`.| -| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`.|| -| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`.| +| Description | Action required | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root. | +| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. | +| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. | +| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree. | No action required. | +| The above also means that there's no top-level `layouts/taxonomy` or `layouts/section` folders anymore, unless it represents a [Page path]. | Move them up to `layouts/` with one of the [Page kinds] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. | +| A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`. | Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`. | +| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword. | Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`. | +| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering. | | +| We have removed the concept of `_internal` Hugo templates.[^internal] | Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`. | +| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`. | | +| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`. | Also, see the [Example folder structure] below for a more concrete example of the new layout system. @@ -35,17 +35,17 @@ We have consolidated the template lookup so it works the same across all [templa The identifiers used in the template weighting, in order of importance, are: -| Identifier | Description | -| ---------- | ----------- | -| Layout custom | The custom `layout` set in front matter. | -| [Page kinds] | One of `home`, `section`, `taxonomy`, `term`, `page`. | -| Layouts standard 1 | `list` or `single`. | -| Output format | The output format (e.g., `html`, `rss`). | -| Layouts standard 2 | `all`. | -| Language | The language (e.g., `en`). | -| Media type | The media type (e.g., `text/html`). | -| [Page path] | The page path (e.g., `/blog/mypost`). | -| Type | `type` set in front matter.[^type]| +| Identifier | Description | +|--------------------|-------------------------------------------------------| +| Layout custom | The custom `layout` set in front matter. | +| [Page kinds][] | One of `home`, `section`, `taxonomy`, `term`, `page`. | +| Layouts standard 1 | `list` or `single`. | +| Output format | The output format (e.g., `html`, `rss`). | +| Layouts standard 2 | `all`. | +| Language | The language (e.g., `en`). | +| Media type | The media type (e.g., `text/html`). | +| [Page path][] | The page path (e.g., `/blog/mypost`). | +| Type | `type` set in front matter.[^type] | For templates placed in a `layouts` folder partly or completely matching a [Page path], a closer match upwards will be considered _better_. In the [Example folder structure] below, this means that: diff --git a/docs/content/en/templates/partial-decorators.md b/docs/content/en/templates/partial-decorators.md new file mode 100644 index 000000000..ff703530e --- /dev/null +++ b/docs/content/en/templates/partial-decorators.md @@ -0,0 +1,125 @@ +--- +title: Partial decorators +description: Use partial decorators to create reusable wrapper components that enclose and compose template content. +categories: [] +keywords: [decorator] +weight: 170 +--- + +{{< new-in "0.154.0" />}} + +## Overview + +{{% glossary-term "partial decorator" %}} + +This approach creates a connection between two files. The calling template provides a block of code and the partial decorator determines where that code appears. This allows the partial to wrap around content without needing to know the specific markup or internal logic of the enclosed block. + +## Implementation + +To use a partial decorator, use a block-style call in your templates. The [`with`][] statement is required to initiate the partial and create a container for the content. This block can include any valid template code including page methods and functions. + +```go-html-template {file="layouts/home.html" copy=true} +{{ with partial "components/wrapper.html" . }} +

Everything in this block will be wrapped.

+

{{ .Content | transform.Plainify | strings.Truncate 200 }}

+{{ end }} +``` + +Inside the partial template, place the `templates.Inner` function call where the wrapped content should appear. + +```go-html-template {file="layouts/_partials/components/wrapper.html" copy=true} +
+ {{ templates.Inner . }} +
+``` + +The `with` statement creates a new [scope](g). Variables defined outside of the `with` block are not available inside it. To use external data within the wrapped content, you must ensure it is part of the [context](g) passed in the partial call. + +A key feature of the `templates.Inner` function is its ability to accept a context argument. By passing a context to the function, you define what the dot (`.`) represents inside the wrapped block. This ensures that the injected content has access to the correct data even when nested inside multiple layers of wrappers. + +## Benefits of composition + +Using partial decorators to build wrapper components provides several advantages: + +- It eliminates the need to use separate partials for opening and closing tags when encapsulating a block of code. +- It prevents parameter bloat because a standard partial no longer requires an extensive list of arguments to account for every possible variation of the content inside it. +- It enables clean composition where the wrapped block can execute any template logic without the wrapper needing to receive or process that data. + +This approach separates container logic from content logic. The wrapper handles structural requirements like specific class hierarchies or CSS grid containers. The calling template retains control over the inner markup and how data is displayed. + +## Example + +The following templates illustrate how to nest three wrapper components including a section, a column, and a card while passing context through each layer. + +The home template initiates the structure by calling the section, column, and card partials as decorators: + +```go-html-template {file="layouts/home.html" copy=true} +{{ $ctx := dict + "page" . + "label" "Recent Posts" + "pageCollection" ((site.GetPage "/posts").RegularPages) +}} + +{{ with partial "components/section.html" $ctx }} +
+ {{ range .pageCollection }} + {{ with partial "components/column.html" (dict "page" . "class" "col-half") }} + {{ with partial "components/card.html" (dict "page" .page "url" .page.RelPermalink "title" .page.LinkTitle) }} +

+ {{ .page.Content | plainify | strings.Truncate 240 }} +

+ {{ end }} + {{ end }} + {{ end }} +
+{{ end }} +``` + +The section component provides a semantic container and an optional heading: + +```go-html-template {file="layouts/_partials/components/section.html" copy=true} +
+ {{ with .label }} +

{{ . }}

+ {{ end }} +
+ {{ templates.Inner . }} +
+
+``` + +The column component manages layout width by applying a CSS class: + +```go-html-template {file="layouts/_partials/components/column.html" copy=true} +
+ {{ templates.Inner . }} +
+``` + +The card component defines the visual boundary for the content: + +```go-html-template {file="layouts/_partials/components/card.html" copy=true} +
+ {{ with .title }} +

+ {{ if $.url }} + {{ . }} + {{ else }} + {{ . }} + {{ end }} +

+ {{ end }} + +
+ {{ templates.Inner . }} +
+ + {{ with .url }} +
+ Read more +
+ {{ end }} +
+``` + +[`with`]: /functions/go-template/with/ diff --git a/docs/content/en/templates/robots.md b/docs/content/en/templates/robots.md index 8183d316f..75bd8bbce 100644 --- a/docs/content/en/templates/robots.md +++ b/docs/content/en/templates/robots.md @@ -4,7 +4,7 @@ linkTitle: robots.txt templates description: Hugo can generate a customized robots.txt in the same way as any other template. categories: [] keywords: [] -weight: 180 +weight: 190 aliases: [/extras/robots-txt/] --- diff --git a/docs/data/docs.yaml b/docs/data/docs.yaml index 3810eb96e..6815c0661 100644 --- a/docs/data/docs.yaml +++ b/docs/data/docs.yaml @@ -1148,12 +1148,6 @@ config: assets: dir: :resourceDir/_gen maxAge: -1 - getcsv: - dir: :cacheDir/:project - maxAge: -1 - getjson: - dir: :cacheDir/:project - maxAge: -1 getresource: dir: :cacheDir/:project maxAge: -1 @@ -1921,8 +1915,6 @@ config: page: nextPrevInSectionSortOrder: desc nextPrevSortOrder: desc - paginate: 0 - paginatePath: '' pagination: disableAliases: false pagerSize: 10 @@ -2189,12 +2181,12 @@ tpl: Description: |- Append appends args up to the last one to the slice in the last argument. This construct allows template constructs like this: - + {{ $pages = $pages | append $p2 $p1 }} - + Note that with 2 arguments where both are slices of the same type, the first slice will be appended to the second: - + {{ $pages = $pages | append .Site.RegularPages }} Examples: [] Apply: @@ -2215,11 +2207,11 @@ tpl: Description: |- Complement gives the elements in the last element of ls that are not in any of the others. - + All elements of ls must be slices or arrays of comparable types. - + The reasoning behind this rather clumsy API is so we can do this in the templates: - + {{ $c := .Pages | complement $last4 }} Examples: - - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}' @@ -2294,9 +2286,9 @@ tpl: Index returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array. - + Adapted from Go stdlib src/text/template/funcs.go. - + We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751. Examples: [] Intersect: @@ -2346,7 +2338,7 @@ tpl: Description: |- Merge creates a copy of the final parameter in params and merges the preceding parameters into it in reverse order. - + Currently only maps are supported. Key handling is case insensitive. Examples: - - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") | sort }}' @@ -2393,9 +2385,9 @@ tpl: - args Description: |- Seq creates a sequence of integers from args. It's named and used as GNU's seq. - + Examples: - + 3 => 1, 2, 3 1 2 4 => 1, 3 -3 => -1, -2, -3 @@ -2484,7 +2476,7 @@ tpl: - v2 Description: |- Conditional can be used as a ternary operator. - + It returns v1 if cond is true, else v2. Examples: - - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}' @@ -2569,12 +2561,6 @@ tpl: Description: Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3 && arg1 != arg4. Examples: [] crypto: - FNV32a: - Aliases: null - Args: - - v - Description: 'FNV32a hashes v using fnv32a algorithm.\n{"newIn": "0.98.0" }' - Examples: [] HMAC: Aliases: - hmac @@ -2649,30 +2635,6 @@ tpl: - v Description: Unquoted returns a string that does not need to be quoted in CSS. Examples: [] - data: - GetCSV: - Aliases: - - getCSV - Args: - - sep - - args - Description: |- - GetCSV expects the separator sep and one or n-parts of a URL to a resource which - can either be a local or a remote one. - The data separator can be a comma, semi-colon, pipe, etc, but only one character. - If you provide multiple parts for the URL they will be joined together to the final URL. - GetCSV returns nil or a slice slice to use in a short code. - Examples: [] - GetJSON: - Aliases: - - getJSON - Args: - - args - Description: |- - GetJSON expects one or n-parts of a URL in args to a resource which can either be a local or a remote one. - If you provide multiple parts they will be joined together to the final URL. - GetJSON returns nil or parsed JSON to use in a short code. - Examples: [] debug: Dump: Aliases: null @@ -2682,10 +2644,10 @@ tpl: Dump returns a object dump of val as a string. Note that not every value passed to Dump will print so nicely, but we'll improve on that. - + We recommend using the "go" Chroma lexer to format the output nicely. - + Also note that the output from Dump may change from Hugo version to the next, so don't depend on a specific output. Examples: @@ -3087,7 +3049,7 @@ tpl: - v Description: |- Humanize returns the humanized form of v. - + If v is either an integer or a string containing an integer value, the behavior is to add the appropriate ordinal. Examples: @@ -3151,7 +3113,7 @@ tpl: Description: |- FormatAccounting returns the currency representation of number for the given currency and precision for the current language in accounting notation. - + The return value is formatted with at least two decimal places. Examples: - - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}' @@ -3165,7 +3127,7 @@ tpl: Description: |- FormatCurrency returns the currency representation of number for the given currency and precision for the current language. - + The return value is formatted with at least two decimal places. Examples: - - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}' @@ -3687,12 +3649,6 @@ tpl: - - '{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}' - Slice resources: - Babel: - Aliases: null - Args: - - args - Description: 'Babel processes the given Resource with Babel.\nDeprecated: Moved to the js namespace in Hugo 0.128.0.' - Examples: [] ByType: Aliases: null Args: @@ -3769,16 +3725,16 @@ tpl: so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "**.png", and to match all PNG images below the images folder, use "images/**.jpg". - + The matching is case insensitive. - + Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". - + See https://github.com/gobwas/glob for the full rules set. - + It looks for files in the assets file system. - + See Match for a more complete explanation about the rules used. Examples: [] Minify: @@ -3790,24 +3746,12 @@ tpl: Minify minifies the given Resource using the MediaType to pick the correct minifier. Examples: [] - PostCSS: - Aliases: null - Args: - - args - Description: 'PostCSS processes the given Resource with PostCSS.\nDeprecated: Moved to the css namespace in Hugo 0.128.0.' - Examples: [] PostProcess: Aliases: null Args: - r Description: PostProcess processes r after the build. Examples: [] - ToCSS: - Aliases: null - Args: - - args - Description: 'ToCSS converts the given Resource to CSS. You can optional provide an Options object\nas second argument. As an option, you can e.g. specify e.g. the target path (string)\nfor the converted CSS resource.\nDeprecated: Moved to the css namespace in Hugo 0.128.0.' - Examples: [] safe: CSS: Aliases: @@ -3867,16 +3811,6 @@ tpl: Args: null Description: '' Examples: null - Author: - Aliases: null - Args: null - Description: '' - Examples: null - Authors: - Aliases: null - Args: null - Description: '' - Examples: null BaseURL: Aliases: null Args: null @@ -3937,11 +3871,6 @@ tpl: Args: null Description: '' Examples: null - IsMultiLingual: - Aliases: null - Args: null - Description: '' - Examples: null Key: Aliases: null Args: null @@ -3967,11 +3896,6 @@ tpl: Args: null Description: '' Examples: null - LastChange: - Aliases: null - Args: null - Description: '' - Examples: null Lastmod: Aliases: null Args: null @@ -4027,11 +3951,6 @@ tpl: Args: null Description: '' Examples: null - Social: - Aliases: null - Args: null - Description: '' - Examples: null Store: Aliases: null Args: null @@ -4156,7 +4075,7 @@ tpl: expression in content. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. - + By default all matches will be included. The number of matches can be limited with the optional limit parameter. A return value of nil indicates no match. @@ -4516,7 +4435,7 @@ tpl: - s Description: |- Emojify returns a copy of s with all emoji codes replaced with actual emojis. - + See http://www.emoji-cheat-sheet.com/ Examples: - - '{{ "I :heart: Hugo" | emojify }}' diff --git a/docs/data/keywords.yaml b/docs/data/keywords.yaml index cd021bbdb..5cc0e9325 100644 --- a/docs/data/keywords.yaml +++ b/docs/data/keywords.yaml @@ -7,7 +7,11 @@ # will decrease over time, though the initial implementation will require some # effort. +- decorator +- filter - highlight - menu +- metadata +- process - random - resource diff --git a/docs/data/sponsors.toml b/docs/data/sponsors.toml index c8eda5883..be2945023 100644 --- a/docs/data/sponsors.toml +++ b/docs/data/sponsors.toml @@ -1,10 +1,3 @@ -[[banners]] - name = "Linode" - link = "https://www.linode.com/" - logo = "images/sponsors/linode-logo.svg" - utm_campaign = "hugosponsor" - bgcolor = "#ffffff" - [[banners]] name = "GoLand" title = "The complete IDE crafted for professional Go developers." @@ -19,3 +12,11 @@ logo = "images/sponsors/cloudcannon-cms-logo.svg" no_query_params = true bgcolor = "#ffffff" + +[[banners]] + name = "Your Company?" + link = "https://bep.is/en/hugo-sponsor-2023-01/" + utm_campaign = "hugosponsor" + show_on_hover = true + bgcolor = "#4e4f4f" + link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'" diff --git a/docs/hugo.toml b/docs/hugo.toml index 5e0b697ef..1bc50ce1b 100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@ -8,9 +8,6 @@ title = "Hugo" # We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). disableAliases = true -# See https://github.com/gohugoio/hugo/issues/13806. -ignoreLogs = ['warning-frontmatter-params-overrides'] - [build] [build.buildStats] disableIDs = true @@ -63,8 +60,6 @@ ignoreLogs = ['warning-frontmatter-params-overrides'] [markup] [markup.goldmark] [markup.goldmark.extensions] - [markup.goldmark.extensions.typographer] - disable = false [markup.goldmark.extensions.passthrough] enable = true [markup.goldmark.extensions.passthrough.delimiters] @@ -72,6 +67,7 @@ ignoreLogs = ['warning-frontmatter-params-overrides'] inline = [['\(', '\)']] [markup.goldmark.parser] autoDefinitionTermID = true + wrapStandAloneImageWithinParagraph = false [markup.goldmark.parser.attribute] block = true [markup.highlight] @@ -91,9 +87,10 @@ ignoreLogs = ['warning-frontmatter-params-overrides'] source = "assets" target = "assets" [[module.mounts]] - lang = 'en' source = 'content/en' target = 'content' + [module.mounts.sites.matrix] + languages = ['en'] [[module.mounts]] disableWatch = true source = "hugo_stats.json" @@ -156,6 +153,7 @@ ignoreLogs = ['warning-frontmatter-params-overrides'] category = 'categories' ######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ######## + [menus] [[menus.global]] identifier = 'news' diff --git a/docs/layouts/_partials/layouts/header/header.html b/docs/layouts/_partials/layouts/header/header.html index 5d27a20b3..6130f45cb 100644 --- a/docs/layouts/_partials/layouts/header/header.html +++ b/docs/layouts/_partials/layouts/header/header.html @@ -13,7 +13,7 @@ {{ end }}
+ class="relative hidden sm:flex flex-grow basis-0 items-center min-w-24 max-w-3xl overflow-x-auto"> {{ range .Site.Menus.global }}
-
+
{{/* Search. */}} {{ partial "layouts/search/input.html" . }} + {{/* Theme selector - shown inline on mobile */}} +
+ {{ partial "layouts/header/theme.html" . }} +
+ class="relative hidden sm:flex ml-0 md:ml-8 content-center basis-0 justify-end gap-0 sm:gap-1 xl:grow-1"> {{/* QR code. */}} {{ partial "layouts/header/qr.html" . }} - {{/* Theme selector. */}} + {{/* Theme selector - hidden on mobile (shown above) */}} {{ partial "layouts/header/theme.html" . }} {{/* Social. */}} @@ -62,4 +66,18 @@ {{ partial "layouts/header/mastodon.html" . }}
+ + {{/* Mobile menu hamburger button - only visible on small screens */}} + + +{{/* Mobile menu panel */}} +{{ partial "layouts/header/mobilemenu.html" . }} diff --git a/docs/layouts/_partials/layouts/header/mobilemenu.html b/docs/layouts/_partials/layouts/header/mobilemenu.html new file mode 100644 index 000000000..7950c3f9e --- /dev/null +++ b/docs/layouts/_partials/layouts/header/mobilemenu.html @@ -0,0 +1,106 @@ +{{/* Mobile menu overlay and panel - only visible on small screens */}} +
+
+ +{{/* Mobile menu panel */}} +
+ + {{/* Header with close button */}} +
+ Menu + +
+ + {{/* Navigation links */}} + + + {{/* Divider */}} +
+ + {{/* Search trigger */}} +
+ +
+ + {{/* Divider */}} +
+ + {{/* Social links */}} +
+ {{/* GitHub */}} + {{ with partialCached "helpers/funcs/get-github-info.html" . "-" }} + + + + + GitHub + {{ .stargazers_count }} stars + + {{ end }} + + {{/* Mastodon */}} + {{ with site.Params.social.mastodon.url }} + + + + + Mastodon + + {{ end }} +
+
diff --git a/docs/layouts/_partials/layouts/icons.html b/docs/layouts/_partials/layouts/icons.html index b05adef00..d98ca6d65 100644 --- a/docs/layouts/_partials/layouts/icons.html +++ b/docs/layouts/_partials/layouts/icons.html @@ -68,3 +68,17 @@ + +{{/* https://heroicons.com/outline bars-3 (hamburger menu) */}} + + + + +{{/* https://heroicons.com/outline x-mark (close) */}} + + + diff --git a/docs/layouts/_shortcodes/glossary.html b/docs/layouts/_shortcodes/glossary.html index ec08cf311..2384a983d 100644 --- a/docs/layouts/_shortcodes/glossary.html +++ b/docs/layouts/_shortcodes/glossary.html @@ -2,7 +2,7 @@ Renders the glossary of terms. When you call this shortcode using the {{% %}} notation, the glossary terms are -Markdown headings (level 6) which means they are members of .Fragments. This +description term (dt) elements which means they are members of .Fragments. This allows the link render hook to verify links to glossary terms. Yes, the terms themselves are pages, but we don't want to link to the pages, at @@ -39,7 +39,11 @@ shortcode. {{- $destination = $u.String }} {{- else }} {{- with site.GetPage $u.Path }} - {{- $destination = .Path }} + {{- if $u.Fragment }} + {{- $destination = printf "%s#%s" .Path $u.Fragment }} + {{ else }} + {{- $destination = .Path }} + {{- end }} {{- else }} {{- errorf "The %q shortcode was unable to find the reference link %s: see %s" $.Name . $p.String }} {{- end }} diff --git a/docs/netlify.toml b/docs/netlify.toml index 2df6ab894..290bbd32d 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -1,25 +1,25 @@ [build] publish = "public" - command = "hugo --gc --minify" + command = "npm ls && hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.152.2" + HUGO_VERSION = "0.155.3" [context.production.environment] HUGO_ENV = "production" HUGO_ENABLEGITINFO = "true" [context.split1] - command = "hugo --gc --minify --enableGitInfo" + command = "npm ls && hugo --gc --minify --enableGitInfo" [context.split1.environment] HUGO_ENV = "production" [context.deploy-preview] - command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo" + command = "npm ls && hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo" [context.branch-deploy] - command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + command = "npm ls && hugo --gc --minify -b $DEPLOY_PRIME_URL" [context.next.environment] HUGO_ENABLEGITINFO = "true" diff --git a/docs/package.json b/docs/package.json index 1fda5ee85..5b6357997 100644 --- a/docs/package.json +++ b/docs/package.json @@ -17,9 +17,9 @@ "tailwindcss": "~4.1.18" }, "dependencies": { - "@alpinejs/focus": "~3.15.3", - "@alpinejs/persist": "~3.15.3", - "@hotwired/turbo": "~8.0.20", - "alpinejs": "~3.15.3" + "@alpinejs/focus": "3.15.3", + "@alpinejs/persist": "3.15.3", + "@hotwired/turbo": "8.0.20", + "alpinejs": "3.15.3" } }