--- /dev/null
- skip = *.ai,chroma.css,chroma_dark.css,.cspell.json
+# Config file for codespell.
+# https://github.com/codespell-project/codespell#using-a-config-file
+
+[codespell]
+
+# Comma separated list of dirs to be skipped.
++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
+
+# Check file names as well.
+check-filenames = true
--- /dev/null
- "**/tools/*",
- "data/docs.yaml"
+{
+ "version": "0.2",
+ "allowCompoundWords": true,
+ "overrides": [
+ {
+ "filename": "**/*",
+ "enabled": false
+ },
+ {
+ "filename": "**/*.md",
+ "enabled": true
+ }
+ ],
+ "flagWords": [
+ "alot",
+ "hte",
+ "langauge",
+ "reccommend",
+ "seperate",
+ "teh"
+ ],
+ "ignorePaths": [
+ "**/emojis.md",
+ "**/commands/*",
+ "**/showcase/*",
++ "**/tools/*"
+ ],
+ "ignoreRegExpList": [
+ "# cspell: ignore fenced code blocks",
+ "^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
+ "# cspell: ignore words joined with dot",
+ "\\w+\\.\\w+",
+ "# cspell: ignore strings within backticks",
+ "`.+`",
+ "# cspell: ignore strings within double quotes",
+ "\".+\"",
+ "# cspell: ignore strings within brackets",
+ "\\[.+\\]",
+ "# cspell: ignore strings within parentheses",
+ "\\(.+\\)",
+ "# cspell: ignore words that begin with a slash",
+ "/\\w+",
+ "# cspell: ignore everything within action delimiters",
+ "\\{\\{.+\\}\\}",
+ "# cspell: ignore everything after a right arrow",
+ "\\s+→\\s+.+"
+ ],
+ "language": "en",
+ "words": [
+ "composability",
+ "configurators",
+ "defang",
+ "deindent",
+ "downscale",
+ "downscaling",
+ "exif",
+ "geolocalized",
+ "grayscale",
+ "marshal",
+ "marshaling",
+ "multihost",
+ "multiplatform",
+ "performantly",
+ "preconfigured",
+ "prerendering",
+ "redirection",
+ "redirections",
+ "slugified",
+ "slugify",
+ "subexpression",
+ "suppressible",
+ "synchronisation",
+ "templating",
+ "transpile",
+ "unmarshal",
+ "unmarshaled",
+ "unmarshaling",
+ "unmarshals",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore hugo terminology",
+ "# ----------------------------------------------------------------------",
+ "alignx",
+ "aligny",
+ "attrlink",
+ "canonify",
+ "codeowners",
+ "dynacache",
+ "eturl",
+ "getenv",
+ "gohugo",
+ "gohugoio",
+ "keyvals",
+ "leftdelim",
+ "linkify",
+ "numworkermultiplier",
+ "rightdelim",
+ "shortcode",
+ "stringifier",
+ "struct",
+ "toclevels",
+ "unmarshal",
+ "unpublishdate",
+ "zgotmplz",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore foreign language words",
+ "# ----------------------------------------------------------------------",
+ "bezpieczeństwo",
+ "blatt",
+ "buch",
+ "descripción",
+ "dokumentation",
+ "erklärungen",
+ "español",
+ "français",
+ "libros",
+ "mercredi",
+ "miesiąc",
+ "miesiąca",
+ "miesiące",
+ "miesięcy",
+ "misérables",
+ "mittwoch",
+ "muchos",
+ "novembre",
+ "otro",
+ "pocos",
+ "produkte",
+ "projekt",
+ "prywatność",
+ "referenz",
+ "régime",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore names",
+ "# ----------------------------------------------------------------------",
+ "Atishay",
+ "Cosette",
+ "Eliott",
+ "Furet",
+ "Gregor",
+ "Jaco",
+ "Lanczos",
+ "Ninke",
+ "Noll",
+ "Pastorius",
+ "Samsa",
+ "Stucki",
+ "Thénardier",
+ "Vitter",
+ "WASI",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore operating systems and software packages",
+ "# ----------------------------------------------------------------------",
+ "asciidoctor",
+ "brotli",
+ "cifs",
+ "corejs",
+ "disqus",
+ "docutils",
+ "dpkg",
+ "doas",
+ "eopkg",
+ "forgejo",
+ "gitee",
+ "goldmark",
+ "katex",
+ "kubuntu",
+ "lubuntu",
+ "mathjax",
+ "nosql",
+ "pandoc",
+ "pkgin",
+ "rclone",
+ "xubuntu",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore miscellaneous",
+ "# ----------------------------------------------------------------------",
+ "achristie",
+ "ccpa",
+ "cpra",
+ "ddmaurier",
+ "dring",
+ "fleqn",
+ "inor",
++ "iptc",
+ "jausten",
+ "jdoe",
+ "jsmith",
+ "leqno",
+ "milli",
+ "monokai",
+ "mysanityprojectid",
+ "rgba",
+ "rsmith",
+ "tdewolff",
+ "tjones",
+ "vcard",
+ "wcag",
+ "xfeff"
+ ]
+}
--- /dev/null
+.DS_Store
+.hugo_build.lock
++.hvm
+/.idea
+/.vscode
+/dist
+/public
+/resources
+hugo_stats.json
+node_modules/
+nohup.out
+package-lock.json
+trace.out
--- /dev/null
- MD056: true
+# Glob patterns to include
+globs:
+ - "content/**/*.md"
+
+# Glob patterns to exclude
+ignores:
+ - "content/**/commands/**"
+ - "content/en/about/license.md"
+ - "content/LICENSE.md"
+
+# Markdownlint rules and configuration
+# https://github.com/DavidAnson/markdownlint?tab=readme-ov-file#rules--aliases
+config:
+ MD001: true
+ # MD002 deprecated
+ MD003:
+ style: atx
+ MD004:
+ style: dash
+ MD005: true
+ # MD006 deprecated
+ MD007: false # if enabled, throws errors when definition descriptions contain list items
+ # MD008 deprecated
+ MD009: true
+ MD010: true
+ MD011: true
+ MD012: true
+ MD013: false
+ MD014: true
+ # MD015 deprecated
+ # MD016 deprecated
+ # MD017 deprecated
+ MD018: true
+ MD019: true
+ MD020: true
+ MD021: true
+ MD022: true
+ MD023: true
+ MD024: true
+ MD025: true
+ MD026: true
+ MD027: true
+ MD028: false
+ MD029:
+ style: one
+ MD030: true
+ MD031: true
+ MD032: true
+ MD033: true
+ MD034: false
+ MD035:
+ style: ---
+ MD036: true
+ MD037: true
+ MD038: true
+ MD039: true
+ MD040: true
+ MD041: false
+ MD042: true
+ MD043: false
+ MD044: false
+ MD045: true
+ MD046: false
+ MD047: true
+ MD048:
+ style: backtick
+ MD049:
+ style: underscore
+ MD050:
+ style: asterisk
+ MD051: false
+ MD052: true
+ MD053: true
+ MD054:
+ autolink: true
+ collapsed: true
+ full: true
+ inline: true
+ shortcut: true
+ url_inline: false
+ MD055:
+ style: consistent
++ MD056: false # interferes with Markdown attributes
+ # MD057 deprecated
+ MD058: true
+ MD059:
+ prohibited_texts:
+ - click here
+ - here
+ - link
+ - more
++ MD060:
++ aligned_delimiter: false
++ style: any
--- /dev/null
--- /dev/null
++## 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., `<div style="...">`).
++
++### 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.
++
++
++
++
--- /dev/null
--- /dev/null
++@AGENTS.md
--- /dev/null
-
- **Note:** We're working on removing the need to run `npm i` for local development. Stay tuned.
+<a href="https://gohugo.io/"><img src="https://raw.githubusercontent.com/gohugoio/gohugoioTheme/master/static/images/hugo-logo-wide.svg?sanitize=true" alt="Hugo" width="565"></a>
+
+A fast and flexible static site generator built with love by [bep], [spf13], and [friends] in [Go].
+
+---
+
+[](https://app.netlify.com/sites/gohugoio/deploys)
+[](https://gohugo.io/contribute/documentation/)
+
+This is the repository for the [Hugo](https://github.com/gohugoio/hugo) documentation site.
+
+Please see the [contributing] section for guidelines, examples, and process.
+
+[bep]: https://github.com/bep
+[spf13]: https://github.com/spf13
+[friends]: https://github.com/gohugoio/hugo/graphs/contributors
+[go]: https://go.dev/
+[contributing]: https://gohugo.io/contribute/documentation
+
+# Install
+
+```sh
+npm i
+hugo server
+```
--- /dev/null
- "Mulish", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
- "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+@import "tailwindcss";
+@plugin "@tailwindcss/typography";
+@variant dark (&:where(.dark, .dark *));
+
+@import "components/all.css";
+
+/* TailwindCSS ignores files in .gitignore, so make it explicit. */
+@source "hugo_stats.json";
+
+@theme {
+ /* Breakpoints. */
+ --breakpoint-sm: 40rem;
+ --breakpoint-md: 48rem;
+ --breakpoint-lg: 68rem; /* Default 64rem; */
+ --breakpoint-xl: 80rem;
+ --breakpoint-2xl: 96rem;
+
+ /* Colors. */
+ --color-primary: var(--color-blue-600);
+ --color-dark: #000;
+ --color-light: var(--color-gray-50);
+ --color-accent: var(--color-orange-500);
+ --color-accent-light: var(--color-pink-500);
+ --color-accent-dark: var(--color-green-500);
+
+ /* https://www.tints.dev/blue/0594CB */
+ --color-blue-50: #e1f6fe;
+ --color-blue-100: #c3edfe;
+ --color-blue-200: #88dbfc;
+ --color-blue-300: #4cc9fb;
+ --color-blue-400: #15b9f9;
+ --color-blue-500: #0594cb;
+ --color-blue-600: #0477a4;
+ --color-blue-700: #035677;
+ --color-blue-800: #023a50;
+ --color-blue-900: #011d28;
+ --color-blue-950: #000e14;
+
+ /* https://www.tints.dev/orange/EBB951 */
+ --color-orange-50: #fdf8ed;
+ --color-orange-100: #fbf1da;
+ --color-orange-200: #f7e4ba;
+ --color-orange-300: #f3d596;
+ --color-orange-400: #efc976;
+ --color-orange-500: #ebb951;
+ --color-orange-600: #e5a51a;
+ --color-orange-700: #a97a13;
+ --color-orange-800: #72520d;
+ --color-orange-900: #372806;
+ --color-orange-950: #1b1403;
+
+ /* https://www.tints.dev/pink/FF4088 */
+ --color-pink-50: #ffebf2;
+ --color-pink-100: #ffdbe9;
+ --color-pink-200: #ffb3d0;
+ --color-pink-300: #ff8fba;
+ --color-pink-400: #ff66a1;
+ --color-pink-500: #ff4088;
+ --color-pink-600: #ff0062;
+ --color-pink-700: #c2004a;
+ --color-pink-800: #800031;
+ --color-pink-900: #420019;
+ --color-pink-950: #1f000c;
+
+ /* https://www.tints.dev/green/33BA91 */
+ --color-green-50: #ebfaf5;
+ --color-green-100: #d3f3e9;
+ --color-green-200: #abe8d6;
+ --color-green-300: #7fdcc0;
+ --color-green-400: #53d0aa;
+ --color-green-500: #33ba91;
+ --color-green-600: #299474;
+ --color-green-700: #1f7058;
+ --color-green-800: #154c3b;
+ --color-green-900: #0a241c;
+ --color-green-950: #051410;
+
+ /* Fonts. */
+ --font-sans:
++ "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 {
+ scroll-padding-top: 100px;
+}
+
+body {
+ @apply antialiased font-sans text-black dark:text-gray-100;
+}
+
+.p-safe-area-x {
+ padding-left: env(safe-area-inset-left);
+ padding-right: env(safe-area-inset-right);
+}
+
+.p-safe-area-y {
+ padding-top: env(safe-area-inset-top);
+ padding-bottom: env(safe-area-inset-bottom);
+}
+
+.px-main {
+ padding-left: max(env(safe-area-inset-left), 1rem);
+ padding-right: max(env(safe-area-inset-right), 1rem);
+}
+
+@media screen(md) {
+ .px-main {
+ padding-left: max(env(safe-area-inset-left), 2rem);
+ padding-right: max(env(safe-area-inset-right), 2rem);
+ }
+}
+
+@media screen(lg) {
+ .px-main {
+ padding-left: max(env(safe-area-inset-left), 3rem);
+ padding-right: max(env(safe-area-inset-right), 3rem);
+ }
+}
+
+/* Algolia DocSearch */
+.algolia-docsearch-suggestion--highlight {
+ color: var(--color-primary);
+}
+
+/* Footnotes */
+.footnote-backref,
+.footnote-ref {
+ text-decoration: none;
+ padding-left: .0625em;
+}
+
+/* Code spans within paragraphs, tables cells, list items, etc. */
+: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;
++}
--- /dev/null
+var debug = 1 ? console.log.bind(console, '[navStore]') : function () {};
+
+var ColorScheme = {
+ System: 1,
+ Light: 2,
+ Dark: 3,
+};
+
+const localStorageUserSettingsKey = 'hugoDocsUserSettings';
+
+export const navStore = (Alpine) => ({
+ init() {
+ // There is no $watch available in Alpine stores,
+ // but this has the same effect.
+ this.userSettings.onColorSchemeChanged = Alpine.effect(() => {
+ if (this.userSettings.settings.colorScheme) {
+ this.userSettings.isDark = isDark(this.userSettings.settings.colorScheme);
+ toggleDarkMode(this.userSettings.isDark);
+ }
+ });
+
+ // Also react to changes in system settings.
+ window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+ this.userSettings.setColorScheme(ColorScheme.System);
+ });
+ },
+
+ destroy() {},
+
+ scroll: {
+ atTop: true,
+ },
+
++ mobileMenu: {
++ open: false,
++ toggle() {
++ this.open = !this.open;
++ },
++ close() {
++ this.open = false;
++ },
++ },
++
+ userSettings: {
+ // settings gets persisted between page navigations.
+ settings: Alpine.$persist({
+ // light, dark or system mode.
+ // If not set, we use the OS setting.
+ colorScheme: ColorScheme.System,
+ // Used to show the most relevant tab in config listings etc.
+ configFileType: 'toml',
+ }).as(localStorageUserSettingsKey),
+
+ isDark: false,
+
+ setColorScheme(colorScheme) {
+ this.settings.colorScheme = colorScheme;
+ this.isDark = isDark(colorScheme);
+ },
+
+ toggleColorScheme() {
+ let next = this.settings.colorScheme + 1;
+ if (next > ColorScheme.Dark) {
+ next = ColorScheme.System;
+ }
+ this.setColorScheme(next);
+ },
+ colorScheme() {
+ return this.settings.colorScheme ? this.settings.colorScheme : ColorScheme.System;
+ },
+ },
+});
+
+function isMediaDark() {
+ return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+function isDark(colorScheme) {
+ if (!colorScheme || colorScheme == ColorScheme.System) {
+ return isMediaDark();
+ }
+
+ return colorScheme == ColorScheme.Dark;
+}
+
+export function initColorScheme() {
+ // The AlpineJS store has not have been initialized yet, so access the
+ // localStorage directly.
+ let settingsJSON = localStorage[localStorageUserSettingsKey];
+ if (settingsJSON) {
+ let settings = JSON.parse(settingsJSON);
+ toggleDarkMode(isDark(settings.colorScheme));
+ return;
+ }
+ toggleDarkMode(isDark(null));
+}
+
+const toggleDarkMode = function (dark) {
+ if (dark) {
+ document.documentElement.classList.add('dark');
+ } else {
+ document.documentElement.classList.remove('dark');
+ }
+};
--- /dev/null
- : {{< new-in 0.124.0 />}}
+---
+_comment: Do not remove front matter.
+---
+
+params
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+ ```
+
+ And then in your JS file:
+
+ ```js
+ import * as params from '@params';
+ ```
+
+ Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
+
+minify
+: (`bool`) Whether to let `js.Build` handle the minification.
+
+loaders
+: {{< new-in 0.140.0 />}}
+: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See <https://esbuild.github.io/api/#loader>.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See <https://esbuild.github.io/api/#inject>.
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+ ```go-html-template
+ {{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+ {{ $js = $js | js.Build dict "shims" $shims }}
+ ```
+
+ The _shim_ files may look like these:
+
+ ```js
+ // js/shims/react.js
+ module.exports = window.React;
+ ```
+
+ ```js
+ // js/shims/react-dom.js
+ module.exports = window.ReactDOM;
+ ```
+
+ With the above, these imports should work in both scenarios:
+
+ ```js
+ import * as React from 'react';
+ import * as ReactDOM from 'react-dom/client';
+ ```
+
+target
+: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
+
+platform
+: {{< new-in 0.140.0 />}}
+: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See <https://esbuild.github.io/api/#platform>.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See <https://esbuild.github.io/api/#external>.
+
+defines
+: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
+
+ ```go-html-template
+ {{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+ ```
+
+drop
+: {{< new-in 0.144.0 />}}
+: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
+: See <https://esbuild.github.io/api/#drop>
+
+sourceMap
+: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
+
+sourcesContent
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
+
+JSX
- : {{< new-in 0.124.0 />}}
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See <https://esbuild.github.io/api/#jsx>.
+
+JSXImportSource
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See <https://esbuild.github.io/api/#jsx-import-source>.
+
+ The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+ ```
+
+ With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+ ```jsx
+ import { render } from 'preact';
+
+ const App = () => <>Hello world!</>;
+
+ const container = document.getElementById('app');
+ if (container) render(<App />, container);
+ ```
--- /dev/null
- 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.
+---
+_comment: Do not remove front matter.
+---
+
- 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:
++## 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.
++
++<!-- TODO Remove the transpiler row somewhere around v0.166.0 -->
+
+Feature|extended edition|extended/deploy edition
+:--|:-:|:-:
- [processing images]: /content-management/image-processing/
++[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
+[transpile sass to css]: /functions/css/sass/
+[details]: /host-and-deploy/deploy-with-hugo-deploy/
--- /dev/null
- - Host your site with services such as [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]
+---
+_comment: Do not remove front matter.
+---
+
+## Prerequisites
+
+Although not required in all cases, [Git], [Go], and [Dart Sass] are commonly used when working with Hugo.
+
+Git is required to:
+
+- Build Hugo from source
+- Use the [Hugo Modules] feature
+- Install a theme as a Git submodule
+- Access [commit information] from a local Git repository
- [cloudcannon]: https://cloudcannon.com/
- [cloudflare pages]: https://pages.cloudflare.com/
++- Host your site on [CI/CD](g) platforms such as [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], or [Vercel][]
+
+Go is required to:
+
+- Build Hugo from source
+- Use the Hugo Modules feature
+
+Dart Sass is required to transpile Sass to CSS when using the latest features of the Sass language.
+
+Please refer to the relevant documentation for installation instructions:
+
+- [Git][git install]
+- [Go][go install]
+- [Dart Sass][dart sass install]
+
- [github pages]: https://pages.github.com/
- [gitlab pages]: https://docs.gitlab.com/ee/user/project/pages/
++[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/
- [netlify]: https://www.netlify.com/
++[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]: /host-and-deploy/host-on-netlify/
++[Render]: /host-and-deploy/host-on-render/
++[Vercel]: /host-and-deploy/host-on-vercel/
--- /dev/null
--- /dev/null
++---
++_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/
--- /dev/null
- ## Process specification
+---
+_comment: Do not remove front matter.
+---
+
- The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
++## Processing specification
+
- : 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).
++The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:
+
+action
- : 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).
++: 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
- rotation
- : Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation).
++: 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.
+
- target format
- : Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format).
++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.
+
- 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).
++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.
+
- : 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).
++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
- [`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
++: 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.
+
- 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).
++ 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
+
- : 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).
++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
++: 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
--- /dev/null
- {{< new-in 0.125.0 />}}
-
+---
+_comment: Do not remove front matter.
+---
+
+## PageInner details
+
+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}
+{{ with .Get 0 }}
+ {{ with $.Page.GetPage . }}
+ {{- .RenderShortcodes }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
+{{ end }}
+```
+
+Then call the shortcode in your Markdown:
+
+```text {file="content/posts/post-1.md"}
+{{%/* include "/posts/post-2" */%}}
+```
+
+Any render hook triggered while rendering `/posts/post-2` will get:
+
+- `/posts/post-1` when calling `Page`
+- `/posts/post-2` when calling `PageInner`
+
+`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
+
+> [!note]
+> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation].
+
+As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
+
+- [Embedded link render hook]
+- [Embedded image render hook]
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[Markdown notation]: /content-management/shortcodes/#notation
+[Embedded link render hook]: <{{% eturl render-link %}}>
+[Embedded image render hook]: <{{% eturl render-image %}}>
--- /dev/null
- : Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
+---
+title: Features
+description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
+categories: []
+keywords: []
+weight: 20
+---
+
+## Framework
+
+[Multiplatform]
+: Install Hugo's single executable on Linux, macOS, Windows, and more.
+
+[Multilingual]
+: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+
+[Output formats]
+: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+
+[Templates]
+: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
+
+[Themes]
+: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
+
+[Modules]
+: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site.
+
+[Privacy]
+: Configure your site to help comply with regional privacy regulations.
+
+[Security]
+: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
+
+## Content authoring
+
+[Content formats]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+
+[Markdown attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Markdown extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Markdown render hooks]
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
+
+[Diagrams]
+: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
+
+[Syntax highlighting]
+: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
+
+[Shortcodes]
+: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
+
+## 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.
+
+[Taxonomies]
+: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
+
+[Data]
+: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
+
+[Menus]
+: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
+
+[URL management]
+: Serve any page from any path via global configuration or on a page-by-page basis.
+
+## Asset pipelines
+
+[Image processing]
++: 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.
+
+[Sass processing]
+: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[Tailwind CSS processing]
+: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS.
+
+## Performance
+
+[Caching]
+: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+
+[Segmentation]
+: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
+
+[Minification]
+: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
+
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /configuration/output-formats/
+[Templates]: /templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[Modules]: /hugo-modules/
+[Privacy]: /configuration/privacy/
+[Security]: /about/security/
+
+[Content formats]: /content-management/formats/
+[CommonMark]: https://spec.commonmark.org/current/
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Markdown attributes]: /content-management/markdown-attributes/
+[Markdown extensions]: /configuration/markup/#extensions
+[Markdown render hooks]: /render-hooks/introduction/
+[Diagrams]: /content-management/diagrams/
+[Mathematics]: /content-management/mathematics/
+[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/
+[Menus]: /content-management/menus/
+[URL management]: /content-management/urls/
+
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
+[Sass processing]: /functions/css/Sass/
+[Tailwind CSS processing]: /functions/css/tailwindcss/
+
+[Caching]: /functions/partials/includecached/
+[Segmentation]: /configuration/segments/
+[Minification]: /configuration/minify/
--- /dev/null
- : See [configure build](/configuration/build/).
+---
+title: All settings
+description: The complete list of Hugo configuration settings.
+categories: []
+keywords: []
+weight: 20
+aliases: [/getting-started/configuration/]
+---
+
+## Settings
+
+archetypeDir
+: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
+
+assetDir
+: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
+
+baseURL
+: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
+
+build
- : See [configure file caches](/configuration/caches/).
++: See [configure build][].
+
+buildDrafts
+: (`bool`) Whether to include draft content when building a site. Default is `false`.
+
+buildExpired
+: (`bool`) Whether to include expired content when building a site. Default is `false`.
+
+buildFuture
+: (`bool`) Whether to include future content when building a site. Default is `false`.
+
+cacheDir
+: (`string`) The designated cache directory. See [details](#cache-directory).
+
+caches
- : {{< 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.
++: See [configure file caches][].
+
+canonifyURLs
+: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+
+capitalizeListTitles
- : See [configure cascade](/configuration/cascade/).
++: (`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
- : (`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`.
++: See [configure cascade][].
+
+cleanDestinationDir
- : (`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`.
++: (`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 %}}
+
+copyright
+: (`string`) The copyright notice for a site, typically displayed in the footer.
+
+dataDir
+: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
+
+defaultContentLanguage
- : (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
++: (`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
- : See [configure deployment](/configuration/deployment/).
++: (`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
- : (`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`.
++: See [configure deployment][].
+
+disableAliases
- : (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. 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 />}}
- : (`[]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.
++: (`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 `<meta name="generator">` tag into the home page. Default is `false`.
+
+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
- : (`bool`) Whether to disable transformation of page URLs to lower case.
++: (`[]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`) 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`) 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
- : See [configure front matter](/configuration/front-matter/).
++: (`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`.
+
+enableRobotsTXT
+: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
+
+environment
+: (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`.
+
+frontmatter
- : (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`] and [`FuzzyWordCount`] methods. Default is `false`.
++: See [configure front matter][].
+
+hasCJKLanguage
- : See [configure HTTP cache](/configuration/http-cache/).
++: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`][] and [`FuzzyWordCount`][] methods. Default is `false`.
+
+HTTPCache
- : (`[]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].
++: See [configure HTTP cache][].
+
+i18nDir
+: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
+
+ignoreCache
+: (`bool`) Whether to ignore the cache directory. Default is `false`.
+
+ignoreFiles
- : (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`].
++: (`[]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 [glob](g) pattern matching the module paths to exclude from the `_vendor` directory.
++: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
+
+ignoreVendorPaths
- : See [configure imaging](/configuration/imaging/).
++: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
+
+imaging
- : (`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:
++: See [configure imaging][].
+
+languageCode
- - 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]
++: (`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:
+
- : See [configure languages](/configuration/languages/).
++ - 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
- : (`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.
++: See [configure languages][].
+
+layoutDir
+: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}}
+
+mainSections
- : See [configure markup](/configuration/markup/).
++: (`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 media types](/configuration/media-types/).
++: See [configure markup][].
+
+mediaTypes
- : See [configure menus](/configuration/menus/).
++: See [configure media types][].
+
+menus
- : See [configure minify](/configuration/minify/).
++: See [configure menus][].
+
+minify
- : See [configure modules](/configuration/module/).
++: See [configure minify][].
+
+module
- : See [configure output formats](/configuration/output-formats/).
++: See [configure modules][].
+
+newContentEditor
+: (`string`) The editor to use when creating new content.
+
+noBuildLock
+: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`.
+
+noChmod
+: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`.
+
+noTimes
+: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
+
+outputFormats
- : See [configure outputs](/configuration/outputs/).
++: See [configure output formats][].
+
+outputs
- : See [configure page](/configuration/page/).
++: See [configure outputs][].
+
+page
- : See [configure pagination](/configuration/pagination/).
++: See [configure page][].
+
+pagination
- : See [configure params](/configuration/params/).
++: See [configure pagination][].
+
+panicOnWarning
+: (`bool`) Whether to panic on the first WARNING. Default is `false`.
+
+params
- : See [configure permalinks](/configuration/permalinks/).
++: See [configure params][].
+
+permalinks
- : See [configure privacy](/configuration/privacy/).
++: See [configure permalinks][].
+
+pluralizeListTitles
+: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
+
+printI18nWarnings
+: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`.
+
+printPathWarnings
+: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`.
+
+printUnusedTemplates
+: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
+
+privacy
- : See [configure related content](/configuration/related-content/).
++: See [configure privacy][].
+
+publishDir
+: (`string`) The designated directory for publishing the site. Default is `public`.
+
+refLinksErrorLevel
+: (`string`) The logging error level to use when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. Either `ERROR` or `WARNING`. Any `ERROR` will fail the build. Default is `ERROR`.
+
+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
- : (`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`.
++: See [configure related content][].
+
+relativeURLs
+: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
+
+removePathAccents
- : {{< 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.
++: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
+
+renderSegments
- : See [configure security](/configuration/security/).
++: (`[]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 segments](/configuration/segments/).
++: 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 server](/configuration/server/).
++: See [configure segments][].
+
+server
- : See [configure services](/configuration/services/).
++: See [configure server][].
+
+services
- : See [configure sitemap](/configuration/sitemap/).
++: See [configure services][].
+
+sitemap
- : (`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`.
++: See [configure sitemap][].
+
+staticDir
+: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}}
+
+summaryLength
- : See [configure taxonomies](/configuration/taxonomies/).
++: (`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
- : (`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`.
++: See [configure taxonomies][].
+
+templateMetrics
+: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+templateMetricsHints
+: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+theme
+: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details](/hugo-modules/theme-components/).
+
+themesDir
+: (`string`) The designated directory for themes. Default is `themes`.
+
+timeout
- : (`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 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 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 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
- : See [configure ugly URLs](/configuration/ugly-urls/).
++: (`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
- 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:
++: See [configure ugly URLs][].
++
++versions
++: See [configure versions][].
+
+## Cache directory
+
- 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`.
++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 [`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.
++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`:
+
+```sh
+hugo config | grep cachedir
+```
+
+## Title case style
+
- : Use the capitalization rules published in the [Associated Press Stylebook]. This is the default.
++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 [Chicago Manual of Style].
++: Use the capitalization rules published in the [Associated Press Stylebook][]. This is the default.
+
+chicago
- Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings).
++: Use the capitalization rules published in the [Chicago Manual of Style][].
+
+go
+: Capitalize the first letter of every word.
+
+firstupper
+: Capitalize the first letter of the first word.
+
+none
+: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
+
+## 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/
+[`time.Format`]: /functions/time/format/
+[`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
+[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
--- /dev/null
- : (`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.
+---
+title: Configure file caches
+linkTitle: Caches
+description: Configure file caches.
+categories: []
+keywords: []
+---
+
+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 [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 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 designated cache directory. See [details](/configuration/all/#cachedir).
++: (`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 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 designated cache directory. See [details](/configuration/all/#cachedir).
+
+`:project`
- : (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
++: (`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).
++
++## 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/
--- /dev/null
- We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2026-03-10 (15 months after deprecation).
+---
+title: Configure cascade
+linkTitle: Cascade
+description: Configure cascade.
+categories: []
+keywords: []
+---
+
+You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor [node](g) has already cascaded a value for the same field through its front matter's `cascade` key.
+
+> [!note]
+> You can also configure cascading behavior within a page's front matter. See [details].
+
+For example, to cascade a "color" parameter to the home page and all its descendants:
+
+{{< code-toggle file=hugo >}}
+[cascade.params]
+color = 'red'
+{{< /code-toggle >}}
+
+## Target
+
+<!-- TODO
+Update the <version> and <date> below when we actually get around to deprecating _target.
+
- : (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
++We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (15 months after deprecation).
+-->
+
+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:
+
+[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=hugo >}}
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/articles,/articles/**}'
+{{< /code-toggle >}}
+
+Use any combination of these keywords to target pages and/or environments:
+
+environment
- : (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
++: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
+
+kind
- : (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
++: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+lang
- : (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
++: (`string`) A [glob pattern](g) matching the [page language]. For example: `{en,de}`.
+
+path
++: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+## Array
+
+Define an array of cascade parameters to apply different values to different targets. For example:
+
+{{< code-toggle file=hugo >}}
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '/books/**'
+kind = 'page'
+lang = '{en,de}'
+[[cascade]]
+[cascade.params]
+color = 'blue'
+[cascade.target]
+path = '/films/**'
+kind = 'page'
+environment = 'production'
+{{< /code-toggle >}}
+
+[details]: /content-management/front-matter/#cascade-1
+[page language]: /methods/page/language/
--- /dev/null
- : (`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.
+---
+title: Configure deployment
+linkTitle: Deployment
+description: Configure deployments to Amazon S3, Azure Blob Storage, or Google Cloud Storage.
+categories: []
+keywords: []
+---
+
+> [!note]
+> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
+
+## Top-level options
+
+These settings control the overall behavior of the deployment process. This is the default configuration:
+
+{{< code-toggle file=hugo config=deployment />}}
+
+confirm
+: (`bool`) Whether to prompt for confirmation before deploying. Default is `false`.
+
+dryRun
+: (`bool`) Whether to simulate the deployment without any remote changes. Default is `false`.
+
+force
+: (`bool`) Whether to re-upload all files. Default is `false`.
+
+invalidateCDN
+: (`bool`) Whether to invalidate the CDN cache listed in the deployment target. Default is `true`.
+
+maxDeletes
+: (`int`) The maximum number of files to delete, or `-1` to disable. Default is `256`.
+
+matchers
+: (`[]*Matcher`) A slice of [matchers](#matchers-1).
+
+order
+: (`[]string`) An ordered slice of [regular expressions](g) that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary order.
+
+target
+: (`string`) The target deployment [`name`](#name). Defaults to the first target.
+
+targets
+: (`[]*Target`) A slice of [targets](#targets-1).
+
+workers
+: (`int`) The number of concurrent workers to use when uploading files. Default is `10`.
+
+## Targets
+
+A target represents a deployment target such as "staging" or "production".
+
+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 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 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 `<project>/<origin>`.
+
+include
++: (`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.
+
+stripIndexHTML
+: (`bool`) Whether to map files named `<dir>/index.html` to `<dir>` on the remote (except for the root `index.html`). This is useful for key-value cloud storage (e.g., Amazon S3, Google Cloud Storage, Azure Blob Storage) to align canonical URLs with object keys. Default is `false`.
+
+url
+: (`string`) The [destination URL](#destination-urls) for deployment.
+
+## Matchers
+
+A Matcher represents a configuration to be applied to files whose paths match
+the specified pattern.
+
+cacheControl
+: (`string`) The caching attributes to use when serving the blob. See [details][cacheControl].
+
+contentEncoding
+: (`string`) The encoding used for the blob's content, if any. See [details][contentEncoding].
+
+contentType
+: (`string`) The media type of the blob being written. See [details][contentType].
+
+force
+: (`bool`) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., `contentType`) has changed. Default is `false`.
+
+gzip
+: (`bool`) Whether the file should be gzipped before upload. If so, the `ContentEncoding` field will automatically be set to `gzip`. Default is `false`.
+
+pattern
+: (`string`) A [regular expression](g) used to match paths. Paths are converted to use forward slashes (`/`) before matching.
+
+[cacheControl]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+[contentEncoding]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
+[contentType]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+
+## Destination URLs
+
+Service|URL example
+:--|:--
+Amazon Simple Storage Service (S3)|`s3://my-bucket?region=us-west-1`
+Azure Blob Storage|`azblob://my-container`
+Google Cloud Storage (GCS)|`gs://my-bucket`
+
+With Google Cloud Storage you can target a subdirectory:
+
+```text
+gs://my-bucket?prefix=a/subdirectory
+```
+
+You can also to deploy to storage servers compatible with Amazon S3 such as:
+
+- [Ceph]
+- [MinIO]
+- [SeaweedFS]
+
+[Ceph]: https://ceph.com/
+[Minio]: https://www.minio.io/
+[SeaweedFS]: https://github.com/chrislusf/seaweedfs
+
+For example, the `url` for a MinIO deployment target might resemble this:
+
+```text
+s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false
+```
+
+## Example
+
+{{< code-toggle file=hugo >}}
+[deployment]
+ order = ['.jpg$', '.gif$']
+ [[deployment.matchers]]
+ cacheControl = 'max-age=31536000, no-transform, public'
+ gzip = true
+ pattern = '^.+\.(js|css|svg|ttf)$'
+ [[deployment.matchers]]
+ cacheControl = 'max-age=31536000, no-transform, public'
+ gzip = false
+ pattern = '^.+\.(png|jpg)$'
+ [[deployment.matchers]]
+ contentType = 'application/xml'
+ gzip = true
+ pattern = '^sitemap\.xml$'
+ [[deployment.matchers]]
+ gzip = true
+ pattern = '^.+\.(html|xml|json)$'
+ [[deployment.targets]]
+ url = 's3://my_production_bucket?region=us-west-1'
+ cloudFrontDistributionID = 'E1234567890ABCDEF0'
+ exclude = '**.{heic,psd}'
+ name = 'production'
+ [[deployment.targets]]
+ url = 's3://my_staging_bucket?region=us-west-1'
+ exclude = '**.{heic,psd}'
+ name = 'staging'
+{{< /code-toggle >}}
--- /dev/null
- : (`string`) A list of [glob](g) patterns to exclude from caching. In its default configuration HTTP caching excludes all files.
+---
+title: Configure the HTTP cache
+linkTitle: HTTP cache
+description: Configure the HTTP cache.
+categories: []
+keywords: []
+---
+
+> [!note]
+> This configuration is only relevant when using the [`resources.GetRemote`] function.
+
+## Layered caching
+
+Hugo employs a layered caching system.
+
+```goat {.w-40}
+ .-----------.
+| dynacache |
+ '-----+-----'
+ |
+ v
+ .----------.
+| HTTP cache |
+ '-----+----'
+ |
+ v
+ .----------.
+| file cache |
+ '-----+----'
+```
+
+Dynacache
+: An in-memory cache employing a Least Recently Used (LRU) eviction policy. Entries are removed from the cache when changes occur, when they match [cache-busting] patterns, or under low-memory conditions.
+
+HTTP Cache
+: An HTTP cache for remote resources as specified in [RFC 9111]. Optimal performance is achieved when resources include appropriate HTTP cache headers. The HTTP cache utilizes the file cache for storage and retrieval of cached resources.
+
+File cache
+: See [configure file caches].
+
+The HTTP cache involves two key aspects: determining which content to cache (the caching process itself) and defining the frequency with which to check for updates (the polling strategy).
+
+## HTTP caching
+
+The HTTP cache behavior is defined for a configured set of resources. Stale resources will be refreshed from the file cache, even if their configured Time-To-Live (TTL) has not expired. If HTTP caching is disabled for a resource, Hugo will bypass the cache and access the file directly.
+
+This is the default configuration for HTTP caching:
+
+{{< code-toggle config=HTTPCache />}}
+
+respectCacheControlNoStoreInRequest
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` request header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `true`.
+
+respectCacheControlNoStoreInResponse
+: {{< new-in 0.151.0 />}}
+: (`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 cache.
++: (`[]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 exclude from polling for this configuration.
++: (`[]string`) A slice of [glob patterns](g) to cache.
+
+polls
+: A slice of polling configurations.
+
+polls.disable
+: (`bool`) Whether to disable polling for this configuration. Default is `true`.
+
+polls.high
+: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
+
+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 include in 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 exclude from polling for this configuration.
++: (`[]string`) A slice of [glob patterns](g) to include in polling for this configuration.
+
+## HTTP polling
+
+Polling is used in watch mode (e.g., `hugo server`) to detect changes in remote resources. Polling can be enabled even if HTTP caching is disabled. Detected changes trigger a rebuild of pages using the affected resource. Polling can be disabled for specific resources, typically those known to be static.
+
+The default configuration disables everything:
+
+{{< code-toggle file=hugo >}}
+[[HTTPCache.polls]]
+disable = true
+high = '0s'
+low = '0s'
+[HTTPCache.polls.for]
+includes = ['**']
+excludes = []
+{{< /code-toggle >}}
+
+polls
+: A slice of polling configurations.
+
+polls.disable
+: (`bool`) Whether to disable polling for this configuration. Default is `true`.
+
+polls.high
+: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
+
+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 include in 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 patterns](g) to include in polling for this configuration.
+
+## Behavior
+
+Polling and HTTP caching interact as follows:
+
+- With polling enabled, rebuilds are triggered only by actual changes, detected via `eTag` changes (Hugo generates an MD5 hash if the server doesn't provide one).
+- If polling is enabled but HTTP caching is disabled, the remote is checked for changes only after the file cache's TTL expires (e.g., a `maxAge` of `10h` with a `1s` polling interval is inefficient).
+- If both polling and HTTP caching are enabled, changes are checked for even before the file cache's TTL expires. Cached `eTag` and `last-modified` values are sent in `if-none-match` and `if-modified-since` headers, respectively, and a cached response is returned on HTTP [304].
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+[304]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304
+[cache-busting]: /configuration/build/#cache-busters
+[configure file caches]: /configuration/caches/
+[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
--- /dev/null
- hint = 'photo'
+---
+title: Configure imaging
+linkTitle: Imaging
+description: Configure imaging.
+categories: []
+keywords: []
+---
+
+## Processing options
+
+These are the default settings for processing images:
+
+{{< code-toggle file=hugo >}}
+[imaging]
+anchor = 'Smart'
+bgColor = '#ffffff'
- : (`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`.
++compression = 'lossy'
+quality = 75
+resampleFilter = 'box'
+{{< /code-toggle >}}
+
+anchor
- : (`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`.
-
- [hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
++: (`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
- 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).
++: (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`.
+
- : (`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`.
++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
- : (`string`) The resampling filter used when resizing an image. Default is `box`. See [details](/content-management/image-processing/#resampling-filter)
++: (`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
- ## EXIF data
++: (`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`.
++
++ 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.
++
++## 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
+
- These are the default settings for extracting EXIF data from images:
++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`.
+
- includeFields = ""
- excludeFields = ""
++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]
- : (`bool`) Whether to disable extraction of the image creation date/time. Default is `false`.
+disableDate = false
+disableLatLong = false
++excludeFields = ""
++includeFields = ""
+{{< /code-toggle >}}
+
+disableDate
- : (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`.
++: (`bool`) Whether to disable the [`Date`][] method by returning its zero value. Default is `false`.
+
+disableLatLong
- : (`string`) A [regular expression](g) matching the tags to exclude when extracting EXIF data.
++: (`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 include when extracting EXIF data. To include all available tags, set this value to `".*"`.
++: (`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
- > [!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.
++: (`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.
++
++## Meta method
++
++{{< 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`.
+
- [`Crop`]: /methods/resource/crop/
- [`Fill`]: /methods/resource/fill/
++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
--- /dev/null
- 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.
+---
+title: Introduction
+description: Configure your site using files, directories, and environment variables.
+categories: []
+keywords: []
+weight: 10
+---
+
+## Sensible defaults
+
+Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'My New Hugo Site'
+{{< /code-toggle >}}
+
+Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
+
+> [!note]
+> The best configuration file is a short configuration file.
+
+## Configuration file
+
+Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
+
+```text
+my-project/
+└── hugo.toml
+```
+
+> [!note]
+> For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
+
+A simple example:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'ABC Widgets, Inc.'
+[params]
+subtitle = 'The Best Widgets on Earth'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 202-555-1212'
+{{< /code-toggle >}}
+
+To use a different configuration file when building your site, use the `--config` flag:
+
+```sh
+hugo --config other.toml
+```
+
+Combine two or more configuration files, with left-to-right precedence:
+
+```sh
+hugo --config a.toml,b.yaml,c.json
+```
+
+> [!note]
+> See the specifications for each file format: [TOML], [YAML], and [JSON].
+
+## Configuration directory
+
+Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ └── production/
+ └── params.toml
+```
+
+The root configuration keys are {{< root-configuration-keys >}}.
+
+> [!note]
+> You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
+
+[#12899]: https://github.com/gohugoio/hugo/issues/12899
+
+### Omit the root key
+
+When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
+
+{{< code-toggle file=config/_default/hugo >}}
+[params]
+foo = 'bar'
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/params >}}
+foo = 'bar'
+{{< /code-toggle >}}
+
+### Recursive parsing
+
+Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
+
+```text
+my-project/
+└── config/
+ └── _default/
+ ├── navigation/
+ │ ├── menus.de.toml
+ │ └── menus.en.toml
+ └── hugo.toml
+```
+
+### Example
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ ├── production/
+ │ ├── hugo.toml
+ │ └── params.toml
+ └── staging/
+ ├── hugo.toml
+ └── params.toml
+```
+
+Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
+
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
+
+Now consider the following scenario:
+
+1. You don't want to load the analytics code when running `hugo server`.
+1. You want to use different Google tag IDs for your production and staging environments. For example:
+ - `G-PPPPPPPPP` for production
+ - `G-SSSSSSSSS` for staging
+
+To satisfy these requirements, configure your site as follows:
+
+1. `config/_default/hugo.toml`
+ - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
+ - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
+1. `config/production/hugo.toml`
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-PPPPPPPPP'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
+ - By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+
+1. `config/staging/hugo.toml`
+
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-SSSSSSSSS'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
+ - To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
+
+## Merge configuration settings
+
+Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
+
+```text
+project/
+├── themes/
+│ ├── theme-a/
+│ │ └── hugo.toml
+│ └── theme-b/
+│ └── hugo.toml
+└── hugo.toml
+```
+
+and this project-level configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'My New Hugo Site'
+theme = ['theme-a','theme-b']
+{{< /code-toggle >}}
+
+Hugo merges settings in this order:
+
+1. Project configuration (`hugo.toml` in the project root)
+1. `theme-a` configuration
+1. `theme-b` configuration
+
+The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged.
+
+The value for `_merge` can be one of:
+
+none
+: No merge.
+
+shallow
+: Only add values for new keys.
+
+deep
+: Add values for new keys, merge existing.
+
+Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
+
+{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
+
+## Environment variables
+
+You can also configure settings using operating system environment variables:
+
+```sh
+export HUGO_BASEURL=https://example.org/
+export HUGO_ENABLEGITINFO=true
+export HUGO_ENVIRONMENT=staging
+hugo
+```
+
+The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
+
+> [!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.
+
- : {{< new-in 0.123.0 />}}
++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_`.
+>
+> To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
+
+For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter].
+
+In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
+
+DART_SASS_BINARY
+: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
+
+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
+: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
+
+HUGO_NUMWORKERMULTIPLIER
+: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
+
+## Current configuration
+
+Display the complete site configuration with:
+
+```sh
+hugo config
+```
+
+Display a specific configuration setting with:
+
+```sh
+hugo config | grep [key]
+```
+
+Display the configured file mounts with:
+
+```sh
+hugo config mounts
+```
+
+[`baseURL`]: /configuration/all#baseurl
+[`enableGitInfo`]: /configuration/all#enablegitinfo
+[`environment`]: /configuration/all#environment
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
+[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
+[TOML]: https://toml.io/en/latest
+[YAML]: https://yaml.org/spec/
--- /dev/null
- : (`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`.
+---
+title: Configure languages
+linkTitle: Languages
+description: Configure the languages in your multilingual site.
+categories: []
+keywords: []
+---
+
+## Base settings
+
+Configure the following base settings within the site's root configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+disableDefaultLanguageRedirect = false
+disableLanguages = []
+{{< /code-toggle >}}
+
+defaultContentLanguage
- : (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
++: (`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 disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. 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 />}}
- : (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate:
++: (`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.
+
+## Language settings
+
+Configure each language under the `languages` key:
+
+{{< code-toggle config=languages />}}
+
+In the above, `en` is the [language key](#language-keys).
+
+disabled
+: (`bool`) Whether to disable this language when building the site. Default is `false`.
+
+languageCode
- - 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]
++: (`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.
+
- Access this value from a template using the [`Language.LanguageCode`] method on a `Site` or `Page` object.
++ Hugo also uses this value to populate:
+
- : (`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.
++ - 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 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 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 site title for this language. Access this value from a template using the [`Title`] method on a `Site` 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
- : (`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.
++: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
+
+weight
- Language keys must conform to the syntax described in [RFC 5646]. For example:
++: (`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
+
+Some configuration settings can be defined separately for each language. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+languageCode = 'en-US'
+languageName = 'English'
+weight = 1
+title = 'Project Documentation'
+timeZone = 'America/New_York'
+[languages.en.pagination]
+path = 'page'
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+The following configuration keys can be defined separately for each language:
+
+{{< per-lang-config-keys >}}
+
+Any key not defined in a `languages` object will fall back to the global value in the root of the site configuration.
+
+## Language keys
+
- 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:
++Language keys must conform to the syntax described in [RFC 5646][]. For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+[languages.de]
+ weight = 1
+[languages.en-US]
+ weight = 2
+[languages.pt-BR]
+ weight = 3
+{{< /code-toggle >}}
+
- > In the example above, omit `contentDir` if [translating by file name].
++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'
+[languages.en]
+weight = 1
+[languages.hugolang]
+weight = 2
+{{< /code-toggle >}}
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Example
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+disableDefaultLanguageRedirect = false
+
+[languages.de]
+contentDir = 'content/de'
+disabled = false
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.en]
+contentDir = 'content/en'
+disabled = false
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+> [!note]
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
++> In the example above, omit `contentDir` if [translating by file name][].
+
+## Multihost
+
+Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
+
+> [!note]
+> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
+
+For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'fr'
+[languages]
+ [languages.en]
+ baseURL = 'https://en.example.org/'
+ languageName = 'English'
+ title = 'In English'
+ weight = 2
+ [languages.fr]
+ baseURL = 'https://fr.example.org'
+ languageName = 'Français'
+ title = 'En Français'
+ weight = 1
+{{</ code-toggle >}}
+
+With the above, Hugo publishes two sites, each with their own root:
+
+```text
+public
+├── en
+└── 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 %}}>
++[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
--- /dev/null
- : {{< new-in 0.123.0 />}}
+---
+title: Configure markup
+linkTitle: Markup
+description: Configure markup.
+categories: []
+keywords: []
+aliases: [/getting-started/configuration-markup/]
+---
+
+## Default handler
+
+In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML.
+
+{{< code-toggle file=hugo >}}
+[markup]
+defaultMarkdownHandler = 'goldmark'
+{{< /code-toggle >}}
+
+Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter.
+
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
+
+`defaultMarkdownHandler`|Renderer
+:--|:--
+`asciidocext`|[AsciiDoc]
+`goldmark`|[Goldmark]
+`org`|[Emacs Org Mode]
+`pandoc`|[Pandoc]
+`rst`|[reStructuredText]
+
+To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+
+> [!note]
+> Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
+
+## Goldmark
+
+This is the default configuration for the Goldmark Markdown renderer:
+
+{{< code-toggle config=markup.goldmark />}}
+
+### Extensions
+
+The extensions below, excluding Extras and Passthrough, are enabled by default.
+
+Extension|Documentation|Enabled
+:--|:--|:-:
+`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark:
+`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
+`extras`|[Hugo Goldmark Extensions: Extras]|
+`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
+`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
+`passthrough`|[Hugo Goldmark Extensions: Passthrough]|
+`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
+`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
+`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
+`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark:
+
+#### Extras
+
+{{< new-in 0.126.0 />}}
+
+Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
+
+Element|Markdown|Rendered
+:--|:--|:--
+Deleted text|`~~foo~~`|`<del>foo</del>`
+Inserted text|`++bar++`|`<ins>bar</ins>`
+Mark text|`==baz==`|`<mark>baz</mark>`
+Subscript|`H~2~O`|`H<sub>2</sub>O`
+Superscript|`1^st^`|`1<sup>st</sup>`
+
+To avoid a conflict[^1], if you enable the "subscript" feature of the Extras extension, you must disable the Strikethrough extension:
+
+[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.subscript]
+enable = true
+{{< /code-toggle >}}
+
+If you still need to show deleted text after disabling the Strikethrough extension, enable the "deleted text" feature of the Extras extension:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.delete]
+enable = true
+{{< /code-toggle >}}
+
+With this configuration, to format text as deleted, wrap it with double-tildes.
+
+#### Footnote
+
+Enabled by default, the Footnote extension enables inclusion of footnotes in Markdown.
+
+enable
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to enable the Footnotes extension. Default is `true`.
+
+backlinkHTML
+: {{< new-in 0.151.0 />}}
+: (`string`) The HTML to be displayed at the end of a footnote that links the user back to the corresponding reference in the main text. The default is ↩︎ (a return arrow symbol).
+
+enableAutoIDPrefix
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to prepend a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. Default is `false`.
+
+#### Passthrough
+
+Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
+
+#### Typographer
+
+The Typographer extension replaces certain character combinations with HTML entities as specified below:
+
+Markdown|Replaced by|Description
+:--|:--|:--
+`...`|`…`|horizontal ellipsis
+`'`|`’`|apostrophe
+`--`|`–`|en dash
+`---`|`—`|em dash
+`«`|`«`|left angle quote
+`“`|`“`|left double quote
+`‘`|`‘`|left single quote
+`»`|`»`|right angle quote
+`”`|`”`|right double quote
+`’`|`’`|right single quote
+
+### Goldmark settings explained
+
+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]
+ > With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
+
+parser.wrapStandAloneImageWithinParagraph
+: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
+
+parser.autoDefinitionTermID
+: {{< new-in 0.144.0 />}}
+: (`bool`) Whether to automatically add `id` attributes to description list terms (i.e., `dt` elements). When `true`, the `id` attribute of each `dt` element is accessible through the [`Fragments.Identifiers`] method on a `Page` object.
+
+parser.autoHeadingID
+: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
+
+parser.autoIDType
+: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. Default is `github`.
+
+ - `github`: Generate GitHub-compatible `id` attributes
+ - `github-ascii`: Drop any non-ASCII characters after accent normalization
+ - `blackfriday`: Generate `id` attributes compatible with the Blackfriday Markdown renderer
+
+ This is also the strategy used by the [anchorize] template function.
+
+parser.attribute.block
+: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
+
+parser.attribute.title
+: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
+renderHooks.image.enableDefault
- - `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.
+: 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`.
+
- - `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.
++ - `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.
- : {{< new-in 0.123.0 />}}
++ - `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.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
+renderHooks.link.enableDefault
- : {{< new-in 0.148.0 />}}
+: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
+
+renderHooks.link.useEmbedded
- - `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.
+: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+
- - `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.
++ - `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.
- : (`string array`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
++ - `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
+: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
+
+renderer.unsafe
+: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`.
+
+## AsciiDoc
+
+This is the default configuration for the AsciiDoc renderer:
+
+{{< code-toggle config=markup.asciidocExt />}}
+
+### AsciiDoc settings explained
+
+attributes
+: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
+
+backend
+: (`string`) The backend output file format. Default is `html5`.
+
+extensions
++: (`[]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`.
+
+failureLevel
+: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
+
+noHeaderOrFooter
+: (`bool`) Whether to output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
+
+preserveTOC
+: (`bool`) Whether to preserve the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`.
+
+safeMode
+: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
+
+sectionNumbers
+: (`bool`) Whether to number each section title. Default is `false`.
+
+trace
+: (`bool`) Whether to include backtrace information on errors. Default is `false`.
+
+verbose
+: (`bool`) Whether to verbosely print processing information and configuration file checks to stderr. Default is `false`.
+
+workingFolderCurrent
+: (`bool`) Whether to set the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`.
+
+### Configuration example
+
+{{< code-toggle file=hugo >}}
+[markup.asciidocExt]
+ extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
+ workingFolderCurrent = true
+ [markup.asciidocExt.attributes]
+ my-base-url = "https://example.com/"
+ my-attribute-name = "my value"
+{{< /code-toggle >}}
+
+### Syntax highlighting
+
+Follow the steps below to enable syntax highlighting.
+
+Step 1
+: Set the `source-highlighter` attribute in your site configuration. For example:
+
+ {{< code-toggle file=hugo >}}
+ [markup.asciidocExt.attributes]
+ source-highlighter = 'rouge'
+ {{< /code-toggle >}}
+
+Step 2
+: Generate the highlighter CSS. For example:
+
+ ```text
+ rougify style monokai.sublime > assets/css/syntax.css
+ ```
+
+Step 3
+: In your base template add a link to the CSS file:
+
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ with resources.Get "css/syntax.css" }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ ...
+ </head>
+ ```
+
+Step 4
+: Add the code to be highlighted to your markup:
+
+ ```text
+ [#hello,ruby]
+ ----
+ require 'sinatra'
+
+ get '/hi' do
+ "Hello World!"
+ end
+ ----
+ ```
+
+### Troubleshooting
+
+Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
+
+```txt
+INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
+```
+
+## Highlight
+
+This is the default configuration.
+
+{{< code-toggle config=markup.highlight />}}
+
+{{% include "/_common/syntax-highlighting-options.md" %}}
+
+## Table of contents
+
+This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
+
+{{< code-toggle config=markup.tableOfContents />}}
+
+startLevel
+: (`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`.
+
+endLevel
+: (`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`.
+
+ordered
+: (`bool`) Whether to generates an ordered list instead of an unordered list. Default is `false`.
+
+[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
+[`TableOfContents`]: /methods/page/tableofcontents/
+[anchorize]: /functions/urls/anchorize
+[AsciiDoc]: https://asciidoc.org/
+[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
+[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
+[CommonMark]: https://spec.commonmark.org/current/
+[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[Emacs Org Mode]: https://orgmode.org/
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
+[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
+[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
+[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
+[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
+[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Goldmark]: https://github.com/yuin/goldmark/
+[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
+[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
+[image render hook]: /render-hooks/images/
+[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
+[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+[Markdown attributes]: /content-management/markdown-attributes/
+[mathematics in Markdown]: content-management/mathematics/
+[multilingual page resources]: /content-management/page-resources/#multilingual
+[Pandoc]: https://pandoc.org/
+[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
+[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[security policy]: /configuration/security/
+[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
--- /dev/null
- - `css.keepCSS2` has been deprecated. Use `css.version` instead.
+---
+title: Configure minify
+linkTitle: Minify
+description: Configure minify.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=minify />}}
+
+See the [tdewolff/minify] project page for details, but note the following:
+
+- `css.inline` is for internal use. Changing this setting has no effect.
- - `svg.inline` is for internal use. Changing this setting has no effect.
+- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead.
+
+[tdewolff/minify]: https://github.com/tdewolff/minify
--- /dev/null
- : (`string`) A comma-separated list of [glob](g) patterns matching paths that should not use the [configured proxy server](#proxy).
+---
+title: Configure modules
+linkTitle: Modules
+description: Configure modules.
+categories: []
+keywords: []
+aliases: [/hugo-modules/configuration/]
+---
+
+{{% include "/_common/gomodules-info.md" %}}
+
+## Top-level options
+
+This is the default configuration:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[module]
+noProxy = 'none'
+noVendor = ''
+private = '*.*'
+proxy = 'direct'
+vendorClosest = false
+workspace = 'off'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+auth
+: {{< new-in 0.144.0 />}}
+: (`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 [glob](g) pattern matching module paths to skip when vendoring.
++: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should not use the [configured proxy server](#proxy).
+
+noVendor
- : (`string`) A comma-separated list of [glob](g) patterns matching paths that should be treated as private.
++: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
+
+private
- : (`string`) The maximum Hugo version supported, for example `0.152.2`.
++: (`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.
+
+replacements
+: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`][].
+
+ {{< code-toggle file=hugo >}}
+ [module]
+ replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'
+ {{< /code-toggle >}}
+
+vendorClosest
+: (`bool`) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`.
+
+workspace
+: (`string`) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is `off`.
+
+You may also use environment variables to set any of the above. For example:
+
+```sh
+export HUGO_MODULE_PROXY="https://proxy.example.org"
+export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
+export HUGO_MODULE_WORKSPACE="/my/hugo.work"
+```
+
+## Hugo version
+
+You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible.
+
+This is the default configuration:
+
+{{< code-toggle config=module.hugoVersion />}}
+
+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
- [`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
-
++: (`string`) The maximum Hugo version supported, for example `0.153.0`.
+
+min
+: (`string`) The minimum Hugo version supported, for example `0.102.0`.
+
+## Imports
+
+{{< code-toggle file=hugo >}}
+[[module.imports]]
+disable = false
+ignoreConfig = false
+ignoreImports = false
+path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
+[[module.imports]]
+path = "my-shortcodes"
+{{< /code-toggle >}}
+
+disable
+: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`.
+
+ignoreConfig
+: (`bool`) Whether to ignore module configuration files, for example, `hugo.toml`. This will also prevent loading of any transitive module dependencies. Default is `false`.
+
+ignoreImports
+: (`bool`) Whether to ignore module imports. Default is `false`.
+
+noMounts
+: (`bool`) Whether to disable directory mounting for this import. Default is `false`.
+
+noVendor
+: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`.
+
+path
+: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`][].
+
+version
+: {{< new-in 0.150.0 />}}
+: If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information.
+
+## Mounts
+
+{{% glossary-term mount %}}
+
+> [!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`][].
+
- lang
- : (`string`) The language code, e.g. "en". Relevant for `content` mounts, and `static` mounts when in multihost mode.
+### 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.
+
+Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded.
+
+In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration.
+
+These are the default mounts:
+
+{{< code-toggle config=module.mounts />}}
+
+source
+: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
+
+target
+: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
+
+disableWatch
+: {{< new-in 0.128.0 />}}
+: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
+
- 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.
++files
++: {{< new-in 0.153.0 />}}
++: (`[]string`) A [glob slice](g) defining the files to include or exclude.
+
- excludeFiles="docs/*"
++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
+
+{{< code-toggle file=hugo >}}
+[module]
+[[module.mounts]]
+ source="content"
+ target="content"
++ files=["! docs/*"]
+[[module.mounts]]
+ source="node_modules"
+ target="assets"
+[[module.mounts]]
+ source="assets"
+ 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
--- /dev/null
- : (`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`.
+---
+title: Configure output formats
+linkTitle: Output formats
+description: Configure output formats.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "output format" %}}
+
+You can output a page in as many formats as you want. Define an infinite number of output formats, provided they each resolve to a unique file system path.
+
+This is the default output format configuration in tabular form:
+
+{{< datatable
+ "config"
+ "outputFormats"
+ "_key"
+ "mediaType"
+ "weight"
+ "baseName"
+ "isHTML"
+ "isPlainText"
+ "noUgly"
+ "notAlternative"
+ "path"
+ "permalinkable"
+ "protocol"
+ "rel"
+ "root"
+ "ugly"
+>}}
+
+## Default configuration
+
+The following is the default configuration that matches the table above:
+
+{{< code-toggle config=outputFormats />}}
+
+baseName
+: (`string`) The base name of the published file. Default is `index`.
+
+isHTML
- : (`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 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`.
+
+mediaType
+: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
+
+notAlternative
+: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
+
+noUgly
+: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`.
+
+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
- : (`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`.
++: (`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`) 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`.
+
+ugly
+: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
+
+weight
+: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`.
+
+## Modify an output format
+
+You can modify any of the default output formats. For example, to prioritize `json` rendering over `html` rendering, when both are generated, adjust the [`weight`](#weight):
+
+{{< code-toggle file=hugo >}}
+[outputFormats.json]
+weight = 1
+[outputFormats.html]
+weight = 2
+{{< /code-toggle >}}
+
+The example above shows that when you modify a default content format, you only need to define the properties that differ from their default values.
+
+## Create an output format
+
+You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
+
+Step 1
+: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first.
+
+ {{< code-toggle file=hugo >}}
+ [mediaTypes.'application/atom+xml']
+ suffixes = ['atom']
+ {{< /code-toggle >}}
+
+ See [configure media types][] for more information.
+
+Step 2
+: Create a new output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputFormats.atom]
+ mediaType = 'application/atom+xml'
+ noUgly = true
+ {{< /code-toggle >}}
+
+ Note that we use the default settings for all other output format properties.
+
+Step 3
+: Specify the page [kinds](g) for which to render this output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputs]
+ home = ['html', 'rss', 'atom']
+ section = ['html', 'rss', 'atom']
+ taxonomy = ['html', 'rss', 'atom']
+ term = ['html', 'rss', 'atom']
+ {{< /code-toggle >}}
+
+ See [configure outputs][] for more information.
+
+Step 4
+: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
+
+ ```text
+ layouts/list.atom.atom
+ ```
+
+ We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][].
+
+## List output formats
+
+To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
+
+```go-html-template
+{{ range .AlternativeOutputFormats }}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
+```
+
+## Link to output formats
+
+By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
+
+For example, in `page.json.json`, you'll see:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/
+{{ with .OutputFormats.Get "json" }}
+ {{ .RelPermalink }} → /that-page/index.json
+{{ end }}
+```
+
+To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format.
+
+With `permalinkable` set to true for `json` in the same `page.json.json` template:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/index.json
+{{ with .OutputFormats.Get "html" }}
+ {{ .RelPermalink }} → /that-page/
+{{ end }}
+```
+
+## Template lookup order
+
+Each output format requires a template conforming to the [template lookup order][].
+
+For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
+
+```text
+[page kind].[output format].[suffix]
+```
+
+For example, for section pages:
+
+Output format|Template path
+:--|:--
+`html`|`layouts/section.html.html`
+`json`|`layouts/section.json.json`
+`rss`|`layouts/section.rss.xml`
+
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
+[`baseURL`]: /configuration/all/#baseurl
+[`OutputFormats`]: /methods/page/outputformats/
+[`Permalink`]: /methods/page/permalink/
+[`permalinkable`]: #permalinkable
+[`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/
+[default media types]: /configuration/media-types/
+[embedded RSS template]: <{{% eturl rss %}}>
+[html/template]: https://pkg.go.dev/html/template
+[template lookup order]: /templates/lookup-order/
+[text/template]: https://pkg.go.dev/text/template
--- /dev/null
- : (`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`.
+---
+title: Configure related content
+linkTitle: Related content
+description: Configure related content.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To understand Hugo's related content identification, please refer to the [related content] page.
+
+Hugo provides a sensible default configuration for identifying related content, but you can customize it in your site configuration, either globally or per language.
+
+## Default configuration
+
+This is the default configuration:
+
+{{< code-toggle config=related />}}
+
+> [!note]
+> Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
+
+## Top-level options
+
+threshold
+: (`int`) A value between 0-100, inclusive. A lower value will return more, but maybe not so relevant, matches.
+
+includeNewer
+: (`bool`) Whether to include pages newer than the current page in the related content listing. This will mean that the output for older posts may change as new related content gets added. Default is `false`.
+
+toLower
+: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
+
+## Per-index options
+
+name
+: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
+
+type
+: (`string`) One of `basic` or `fragments`. Default is `basic`.
+
+applyFilter
+: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
+
+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`.
+
+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.
+
+toLower
+: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
+
+## Example
+
+Imagine we're building a book review site. Our main content will be book reviews, and we'll use genres and authors as taxonomies. When someone views a book review, we want to show a short list of related reviews based on shared authors and genres.
+
+Create the content:
+
+```text
+content/
+└── book-reviews/
+ ├── book-review-1.md
+ ├── book-review-2.md
+ ├── book-review-3.md
+ ├── book-review-4.md
+ └── book-review-5.md
+```
+
+Configure the taxonomies:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Configure the related content identification:
+
+{{< code-toggle file=hugo >}}
+[related]
+includeNewer = true
+threshold = 80
+toLower = true
+[[related.indices]]
+name = 'authors'
+weight = 2
+[[related.indices]]
+name = 'genres'
+weight = 1
+{{< /code-toggle >}}
+
+We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`.
+
+Then render a list of 5 related reviews with a _partial_ template like this:
+
+```go-html-template {file="layouts/_partials/related.html" copy=true}
+{{ with site.RegularPages.Related . | first 5 }}
+ <p>Related content:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+[related content]: /content-management/related-content/
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
- {{< new-in 0.124.0 />}}
-
+---
+title: Configure segments
+linkTitle: Segments
+description: Configure your site for segmented rendering.
+categories: []
+keywords: []
+---
+
- - Matchers: Each filter contains one or more field [glob](g) matchers.
+> [!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.
+
+Segmented rendering offers several advantages:
+
+- Faster builds: Process large sites more efficiently.
+- Rapid development: Render only a subset of your site for quicker iteration.
+- Scheduled rebuilds: Rebuild specific sections at different frequencies (e.g., home page and news hourly, full site weekly).
+- Targeted output: Generate specific output formats (like JSON for search indexes).
+
+## Segment definition
+
+Each segment is defined by include and exclude filters:
+
+- Filters: Each segment has zero or more exclude filters and zero or more include filters.
- : (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
++- 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
+
+Available fields for filtering:
+
+kind
- lang
- : (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
++: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
- : (`string`) A [glob](g) pattern matching the [output format](g) of the page. For example: `{html,json}`.
++sites
++: {{< new-in 0.153.0 />}}
++: (`map`) A map to define [sites matrix](g).
+
+output
- : (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
++: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
+
+path
- [page language]: /methods/page/language/
++: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+## Example
+
+Place broad filters, such as those for language or output format, in the excludes section. For example:
+
+{{< code-toggle file=hugo >}}
+[segments.segment1]
+ [[segments.segment1.excludes]]
+ lang = "n*"
+ [[segments.segment1.excludes]]
+ lang = "en"
+ output = "rss"
+ [[segments.segment1.includes]]
+ kind = "{home,term,taxonomy}"
+ [[segments.segment1.includes]]
+ path = "{/docs,/docs/**}"
+{{< /code-toggle >}}
+
+## Rendering segments
+
+Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
+
+```bash
+hugo --renderSegments segment1
+```
+
+You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
+
+```bash
+hugo --renderSegments segment1,segment2
+```
+
+[`renderSegments`]: /configuration/all/#rendersegments
--- /dev/null
- : (`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.
+---
+title: Configure server
+linkTitle: Server
+description: Configure the development server.
+categories: []
+keywords: []
+---
+
+These settings are exclusive to Hugo's development server, so a dedicated [configuration directory] for development, where the server is configured accordingly, is the recommended approach.
+
+[configuration directory]: /configuration/introduction/#configuration-directory
+
+```text
+project/
+└── config/
+ ├── _default/
+ │ └── hugo.toml
+ └── development/
+ └── server.toml
+```
+
+## Default settings
+
+The development server defaults to redirecting to `/404.html` for any requests to URLs that don't exist. See the [404 errors](#404-errors) section below for details.
+
+{{< code-toggle config=server />}}
+
+force
+: (`bool`) Whether to force a redirect even if there is existing content in the path.
+
+from
- : (`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.
++: (`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 pattern](g) with values to match. If the map is empty, the redirect will always be triggered.
+
+fromRe
+: {{< new-in 0.144.0 />}}
+: (`string`) A [regular expression](g) used to match the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the `to` field as `$1`, `$2`, and so on.
+
+status
+: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
+
+to
+: (`string`) The URL to forward the request to.
+
+## Headers
+
+Include headers in every server response to facilitate testing, particularly for features like [Content Security Policies].
+
+[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+
+{{< code-toggle file=config/development/server >}}
+[[headers]]
+for = "/**"
+
+[headers.values]
+X-Frame-Options = "DENY"
+X-XSS-Protection = "1; mode=block"
+X-Content-Type-Options = "nosniff"
+Referrer-Policy = "strict-origin-when-cross-origin"
+Content-Security-Policy = "script-src localhost:1313"
+{{< /code-toggle >}}
+
+## Redirects
+
+You can define simple redirect rules.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+from = "/myspa/**"
+to = "/myspa/"
+status = 200
+force = false
+{{< /code-toggle >}}
+
+The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications].
+
+[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application
+
+## 404 errors
+
+The development server defaults to redirecting to /404.html for any requests to URLs that don't exist.
+
+{{< code-toggle config=server />}}
+
+If you've already defined other redirects, you must explicitly add the 404 redirect.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+force = false
+from = "/**"
+to = "/404.html"
+status = 404
+{{< /code-toggle >}}
+
+For multilingual sites, ensure the default language 404 redirect is defined last:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
+When the default language is served from a subdirectory:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/en/404.html'
+status = 404
+{{< /code-toggle >}}
--- /dev/null
- instagram.accessToken <!-- TODO: Remove when no longer in docs.yaml -->
- : (`string`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting.
-
- instagram.disableInlineCSS <!-- TODO: Remove when no longer in docs.yaml -->
- : (`bool`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting.
-
+---
+title: Configure services
+linkTitle: Services
+description: Configure embedded templates.
+categories: []
+keywords: []
+---
+
+Hugo provides [embedded templates](g) to simplify site and content creation. Some of these templates are configurable. For example, the embedded Google Analytics template requires a Google tag ID.
+
+This is the default configuration:
+
+{{< code-toggle config=services />}}
+
+disqus.shortname
+: (`string`) The `shortname` used with the Disqus commenting system. See [details](/templates/embedded/#disqus). To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.Disqus.Shortname }}
+ ```
+
+googleAnalytics.id
+: (`string`) The Google tag ID for Google Analytics 4 properties. See [details](/templates/embedded/#google-analytics). To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.GoogleAnalytics.ID }}
+ ```
+
- twitter.disableInlineCSS <!-- TODO: Remove when no longer in docs.yaml -->
- : (`bool`) Do not use. Deprecated in [v0.141.0]. Use the `x` shortcode instead.
-
+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:
+
+ ```go-html-template
+ {{ .Site.Config.Services.RSS.Limit }}
+ ```
+
+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:
+
+ ```go-html-template
+ {{ .Site.Config.Services.X.DisableInlineCSS }}
+
+[v0.141.0]: https://github.com/gohugoio/hugo/releases/tag/v0.141.0
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: Configure sitemap
+linkTitle: Sitemap
+description: Configure the sitemap.
+categories: []
+keywords: []
+---
+
+These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
+
+{{< code-toggle config=sitemap />}}
+
+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
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+filename
+: (`string`) The name of the generated file. Default is `sitemap.xml`.
+
+priority
+: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
+---
+title: Comments
+description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
+categories: []
+keywords: []
+aliases: [/extras/comments/]
+---
+
+Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
+
+Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
+
+## Add Disqus
+
+Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
+
+### Configure Disqus
+
+Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+### Render Hugo's built-in Disqus partial template
+
+Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
+
+```go-html-template
+{{ partial "disqus.html" . }}
+```
+
+## Alternatives
+
+Commercial commenting systems:
+
++- [Commentix](https://www.commentix.com/)
+- [Emote](https://emote.com/)
+- [Graph Comment](https://graphcomment.com/)
+- [Hyvor Talk](https://talk.hyvor.com/)
+- [IntenseDebate](https://intensedebate.com/)
+- [ReplyBox](https://getreplybox.com/)
+
+Open-source commenting systems:
+
+- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
+- [Comentario](https://gitlab.com/comentario/comentario/)
+- [Comma](https://github.com/Dieterbe/comma/)
+- [Commento](https://commento.io/)
+- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
+- [Giscus](https://giscus.app/)
+- [Isso](https://isso-comments.de/)
+- [Remark42](https://remark42.com/)
+- [Staticman](https://staticman.net/)
+- [Talkyard](https://blog-comments.talkyard.io/)
+- [Utterances](https://utteranc.es/)
++- [Zoomment](https://zoomment.com/)
+
+[configuration]: /configuration/
+[disquspartial]: /templates/embedded/#disqus
+[disqussetup]: https://disqus.com/profile/signup/
+[front matter]: /content-management/front-matter/
--- /dev/null
- 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.
+---
+title: Content adapters
+description: Create content adapters to dynamically add content when building your site.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.126.0 />}}
+
+## Overview
+
+A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter.
+
+```text
+content/
+├── articles/
+│ ├── _index.md
+│ ├── article-1.md
+│ └── article-2.md
+├── books/
+│ ├── _content.gotmpl <-- content adapter
+│ └── _index.md
+└── films/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Each content adapter is named `_content.gotmpl` and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+
+## Methods
+
+Use these methods within a content adapter.
+
+### AddPage
+
+Adds a page to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+```
+
+### AddResource
+
+Adds a page resource to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ with resources.Get "images/a.jpg" }}
+ {{ $content := dict
+ "mediaType" .MediaType.Type
+ "value" .
+ }}
+ {{ $resource := dict
+ "content" $content
+ "path" "the-hunchback-of-notre-dame/cover.jpg"
+ }}
+ {{ $.AddResource $resource }}
+{{ end }}
+```
+
+Then retrieve the new page resource with something like:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Resources.Get "cover.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+### Site
+
+Returns the `Site` to which the pages will be added.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .Site.Title }}
+```
+
+> [!note]
+> Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
+
+### Store
+
+Returns a persistent "scratch pad" to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+```
+
+### EnableAllLanguages
+
++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 }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .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.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
+`content.value`|The content value as a string.|
+`dates.date`|The page creation date as a `time.Time` value.|
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|
+`dates.lastmod`|The page last modification date as a `time.Time` value.|
+`dates.publishDate`|The page publication date as a `time.Time` value.|
+`params`|A map of page parameters.|
+`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`title`|The page title.|
+
+> [!note]
+> While `path` is the only required field, we recommend setting `title` as well.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|
+`params`|A map of resource parameters.|
+`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`title`|The resource title.|
+
+> [!note]
+> When `content.value` is a string, Hugo generates a new resource with a publication path relative to the page. However, if `content.value` is already a resource, Hugo directly uses its value and publishes it relative to the site root. This latter method is more efficient.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
+
+## Example
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+ ```text
+ content/
+ └── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+ ```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.\
+ <https://gohugo.io/shared/examples/data/books.json>
+
+Step 3
+: Create the content adapter.
+
+ ```go-html-template {file="content/books/_content.gotmpl" copy=true}
+ {{/* Get remote data. */}}
+ {{ $data := dict }}
+ {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+
+ {{/* Add pages and page resources. */}}
+ {{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+
+ {{ end }}
+ ```
+
+Step 4
+: Create a _page_ template to render each book review.
+
+ ```go-html-template {file="layouts/books/page.html" copy=true}
+ {{ define "main" }}
+ <h1>{{ .Title }}</h1>
+
+ {{ with .Resources.GetMatch "cover.*" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
+ {{ end }}
+
+ <p>Author: {{ .Params.author }}</p>
+
+ <p>
+ ISBN: {{ .Params.isbn }}<br>
+ Rating: {{ .Params.rating }}<br>
+ Review date: {{ .Date | time.Format ":date_long" }}
+ </p>
+
+ {{ with .GetTerms "tags" }}
+ <p>Tags:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+
+ {{ .Content }}
+ {{ end }}
+ ```
+
+## Multilingual sites
+
+With multilingual sites you can:
+
+1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
+1. Create content adapters unique to each language. See the examples below.
+
+### Translations by file name
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+weight = 1
+
+[languages.de]
+weight = 2
+{{< /code-toggle >}}
+
+Include a language designator in the content adapter's file name.
+
+```text
+content/
+└── books/
+ ├── _content.de.gotmpl
+ ├── _content.en.gotmpl
+ ├── _index.de.md
+ └── _index.en.md
+```
+
+### Translations by content directory
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+weight = 2
+{{< /code-toggle >}}
+
+Create a single content adapter in each directory:
+
+```text
+content/
+├── de/
+│ └── books/
+│ ├── _content.gotmpl
+│ └── _index.md
+└── en/
+ └── books/
+ ├── _content.gotmpl
+ └── _index.md
+```
+
+## Page collisions
+
+Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ ├── _index.md
+ └── the-hunchback-of-notre-dame.md
+```
+
+If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order.
+
+To detect page collisions, use the `--printPathWarnings` flag when building your site.
+
+[content formats]: /content-management/formats/#classification
+[front matter field]: /content-management/front-matter/#fields
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[syntax]: /templates/introduction/
+[template functions]: /functions/
--- /dev/null
- : (`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.
+---
+title: Front matter
+description: Use front matter to add metadata to your content.
+categories: []
+keywords: []
+aliases: [/content/front-matter/]
+---
+
+## Overview
+
+The front matter at the top of each content file is metadata that:
+
+- Describes the content
+- Augments the content
+- Establishes relationships with other content
+- Controls the published structure of your site
+- Determines template selection
+
+Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
+
+See examples of front matter delimiters by toggling between the serialization formats below.
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), [arrays](g), or [maps](g). Note that the TOML format also supports unquoted date/time values.
+
+## Fields
+
+The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
+
+> [!note]
+> The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details.
+
+[parameters]: #parameters
+
+aliases
- : (`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 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].
+
+cascade
+: (`map`) A map (or a slice of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade] section for details.
+
+date
+: (`string`) The date associated with the page, typically the creation date. 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 [`Date`] method on a `Page` object.
+
+description
+: (`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`] method on a `Page` object.
+
+draft
+: (`bool`) Whether to disable rendering unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`] method on a `Page` object.
+
+expiryDate
+: (`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. 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 [`ExpiryDate`] method on a `Page` object.
+
+headless
+: (`bool`) Applicable to [leaf bundles], whether to set the `render` and `list` [build options] to `never`, creating a headless bundle of [page resources].
+
+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`, `string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
++: (`[]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.
+
+layout
+: (`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
+
+linkTitle
+: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
+
+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 array`) The [output formats] to render. See [configure outputs] for more information.
++: (`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
- : {{< new-in 0.123.0 />}}
++: (`[]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
+: Alias to [publishDate](#publishdate).
+
+publishDate
+: (`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. 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 [`PublishDate`] method on a `Page` object.
+
+published
+: Alias to [publishDate](#publishdate).
+
+resources
+: (`map array`) An array of maps to provide metadata for [page 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.
++
++ <!-- markdownlint-disable MD049 -->
++
++ {{< 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 >}}
++
++ <!-- markdownlint-enable MD049 -->
++
+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.
+
+summary
+: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
+
+title
+: (`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
+
+translationKey
+: (`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
+
+type
+: (`string`) The [content type](g), overriding the value derived from the top-level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+
+unpublishdate
+: Alias to [expirydate](#expirydate).
+
+url
+: (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
+
+weight
+: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object.
+
+## Parameters
+
- We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2026-03-10 (15 months after deprecation).
+Specify custom page parameters under the `params` key in front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
+
+Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
+
+Parameter|Data type|Used by these embedded templates
+:--|:--|:--
+`audio`|`[]string`|[`opengraph.html`]
+`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
+`videos`|`[]string`|[`opengraph.html`]
+
+The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
+
+## Taxonomies
+
+Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Add taxonomy terms as shown below:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+tags = ['red','blue']
+genres = ['mystery','romance']
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+You can add taxonomy terms to the front matter of any these [page kinds](g):
+
+- `home`
+- `page`
+- `section`
+- `taxonomy`
+- `term`
+
+Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .GetTerms "tags" }}
+ <p>Tags</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+[`GetTerms`]: /methods/page/getterms/
+
+## Cascade
+
+A [node](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for that same field.
+
+For example, to cascade a "color" parameter from the home page to all its descendants:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+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
+
+<!-- TODO
+Update the <version> and <date> below when we actually get around to deprecating _target.
+
- : (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
++We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (15 months after deprecation).
+-->
+
+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:
+
+[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+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 [page kind](g). For example: `{taxonomy,term}`.
++: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
+
+kind
- : (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
++: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+path
++: (`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
+
+Define an array of cascade parameters to apply different values to different targets. For example:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/books/**}'
+kind = 'page'
+[[cascade]]
+[cascade.params]
+color = 'blue'
+[cascade.target]
+path = '{/films/**}'
+kind = 'page'
+{{< /code-toggle >}}
+
+> [!note]
+> For multilingual sites, defining cascade values in your site configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
+>
+> If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language.
+
+## Emacs Org Mode
+
+If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example:
+
+```text {file="content/example.org"}
+#+TITLE: Example
+#+DATE: 2024-02-02T04:14:54-08:00
+#+DRAFT: false
+#+AUTHOR: John Smith
+#+GENRES: mystery
+#+GENRES: romance
+#+TAGS: red
+#+TAGS: blue
+#+WEIGHT: 10
+```
+
+Note that you can also specify array elements on a single line:
+
+```text {file="content/example.org"}
+#+TAGS[]: red blue
+```
+
+[content format]: /content-management/formats/
+[emacs org mode]: https://orgmode.org/
+
+## Dates
+
+When populating a date field, whether a [custom page parameter](#parameters) or one of the four predefined fields ([`date`](#date), [`expiryDate`](#expirydate), [`lastmod`](#lastmod), [`publishDate`](#publishdate)), use one of these parsable formats:
+
+{{% include "/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your site configuration. The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+1. The time zone specified in your site configuration
+1. The `Etc/UTC` time zone
+
+[`aliases`]: /methods/page/aliases/
+[`date`]: /methods/page/date/
+[`description`]: /methods/page/description/
+[`draft`]: /methods/page/draft/
+[`expirydate`]: /methods/page/expirydate/
+[`fuzzywordcount`]: /methods/page/wordcount/
+[`keywords`]: /methods/page/keywords/
+[`lastmod`]: /methods/page/date/
+[`layout`]: /methods/page/layout/
+[`linktitle`]: /methods/page/linktitle/
+[`opengraph.html`]: <{{% eturl opengraph %}}>
+[`Param`]: /methods/page/param/
+[`Params`]: /methods/page/params/
+[`publishdate`]: /methods/page/publishdate/
+[`readingtime`]: /methods/page/readingtime/
+[`schema.html`]: <{{% eturl schema %}}>
+[`sitemap`]: /methods/page/sitemap/
+[`slug`]: /methods/page/slug/
+[`Summary`]: /methods/page/summary/
+[`title`]: /methods/page/title/
+[`translationkey`]: /methods/page/translationkey/
+[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
+[`type`]: /methods/page/type/
+[`weight`]: /methods/page/weight/
+[`wordcount`]: /methods/page/wordcount/
+[aliases]: /content-management/urls/#aliases
+[build options]: /content-management/build-options/
+[cascade]: #cascade-1
+[configure outputs]: /configuration/outputs/#outputs-per-page
+[content formats]: /content-management/formats/#classification
+[embedded templates]: /templates/embedded/
+[json]: https://www.json.org/
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[menus]: /content-management/menus/#define-in-front-matter
+[output formats]: /configuration/output-formats/
+[page parameters]: #parameters
+[page resources]: /content-management/page-resources/#metadata
+[sitemap templates]: /templates/sitemap/
+[target a specific template]: /templates/lookup-order/#target-a-template
+[template lookup order]: /templates/lookup-order/
+[toml]: https://toml.io/
+[URL management]: /content-management/urls/#slug
+[yaml]: https://yaml.org/
--- /dev/null
- description: Resize, crop, rotate, filter, and convert images.
+---
+title: Image processing
- ## Image resources
++description: Process, transform, and analyze images.
+categories: []
+keywords: []
+---
+
- To process an image you must access the file as a page resource, global resource, or remote resource.
++Hugo provides methods to transform and analyze images during the build process. The results are cached to ensure subsequent builds remain fast.
+
- ### Page resource
++## Resources
+
- To access an image as a 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" %}}
+
+```text
+content/
+└── posts/
+ └── post-1/ <-- page bundle
+ ├── index.md
+ └── sunset.jpg <-- page resource
+```
+
- ### Global resource
++To capture an image as a page resource:
+
+```go-html-template
+{{ $image := .Resources.Get "sunset.jpg" }}
+```
+
- To access an image as a global resource:
++### Global
+
+{{% glossary-term "global resource" %}}
+
+```text
+assets/
+└── images/
+ └── sunset.jpg <-- global resource
+```
+
- ### Remote resource
++To capture an image as a global resource:
+
+```go-html-template
+{{ $image := resources.Get "images/sunset.jpg" }}
+```
+
- To access an image as a remote resource:
++### Remote
+
+{{% glossary-term "remote resource" %}}
+
- ## Image rendering
++To capture an image as a remote resource:
+
+```go-html-template
+{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
+```
+
- Once you have accessed an image as a resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties.
++## Rendering
+
- Example 1: Throws an error if the resource is not found.
++Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods.
+
- Example 2: Skips image rendering 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" }}
+<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
+```
+
- Example 4: Skips rendering if there's problem accessing a remote resource.
++Example 2: Skip image rendering if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+{{ with $image }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 3: A more concise way to skip image rendering if the resource is not found.
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
- ## Image processing methods
-
- 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:
-
- ```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.
++Example 4: Skip rendering if there's problem accessing a remote resource.
+
+```go-html-template
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
- ```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.
++## Processing
+
- {{ $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 }}
- <ul>
- {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
- {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
- {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
- {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
- {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
- {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
- </ul>
- {{ 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) }}
++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
- In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation.
-
- ### Anchor
-
- 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) }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .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
++{{ with .Resources.Get "sunset.jpg" }}
++ {{ with .Resize "400x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
+```
+
- 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.
++> [!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.
+
- Value|Example
++Each method serves a specific transformation or metadata requirement:
+
- `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|Description
+:--|:--
- The default value is `photo`. You may override the default value in the [site configuration].
++[`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"}
+
- ```go-html-template
- {{ $image.Resize "600x webp picture" }}
- ```
-
- ### Background color
++Select a method from the table above for syntax and usage examples.
+
- 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.
++## Performance
+
- Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
++### Caching
+
- The default value is `#ffffff` (white). You may override the default value in the [site configuration].
++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.
+
- ```go-html-template
- {{ $image.Resize "600x jpg #b31280" }}
++If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds:
+
- ### Resampling filter
++```toml
++[caches]
++ [caches.images]
++ dir = ':cacheDir/images'
+```
+
- You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
++### Garbage collection
+
- 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" }}
++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:
+
- 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" />}}
++```text
++hugo --gc
+```
+
- {{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}}
++### Resource usage
+
- {{< 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" />}}
++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.
+
- ## 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
++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).
+
++[`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/
--- /dev/null
- With `class` and `id` you can use shorthand notation:
+---
+title: Markdown attributes
+description: Use Markdown attributes to add HTML attributes when rendering Markdown to HTML.
+categories: []
+keywords: []
+---
+
+## Overview
+
+Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+For example:
+
+```text
+This is a paragraph.
+{class="foo bar" id="baz"}
+```
+
- Hugo renders both of these to:
++With `class` and `id` attributes you can also use short-form notation:
+
+```text
+This is a paragraph.
+{.foo .bar #baz}
+```
+
- blockquote | bottom
- fenced code block | right
- heading | right
- horizontal rule | bottom
- image | bottom
- list | bottom
- paragraph | bottom
- table | bottom
++Hugo renders both of the examples above to:
+
+```html
+<p class="foo bar" id="baz">This is a paragraph.</p>
+```
+
++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.
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true # default is true
+block = true # default is false
+{{< /code-toggle >}}
+
+## Standalone images
+
+By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+[Goldmark]: https://github.com/yuin/goldmark
+
+If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
+
+To apply attributes to a standalone image element, you must disable the default wrapping behavior:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false # default is true
+{{< /code-toggle >}}
+
+## Usage
+
+You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
+
+[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+
+The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
+
+For example:
+
+```text
+> This is a blockquote.
+{class="foo bar" hidden=hidden}
+```
+
+Hugo renders this to:
+
+```html
+<blockquote class="foo bar" hidden="hidden">
+ <p>This is a blockquote.</p>
+</blockquote>
+```
+
+In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
+
+Element|Position of attribute list
+:--|:--
++blockquote|bottom
++fenced code block|right
++heading|right
++horizontal rule|bottom
++image|bottom
++list|bottom
++paragraph|bottom
++table|bottom
+
+For example:
+
+````text
+## Section 1 {class=foo}
+
+```bash {class=foo linenos=inline}
+declare a=1
+echo "${a}"
+```
+
+This is a paragraph.
+{class=foo}
+````
+
+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/
--- /dev/null
- | other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
- | photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
+---
+title: Page resources
+description: Use page resources to logically associate assets with a page.
+categories: []
+keywords: []
+---
+
+Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
+`_index.md` files at their root. Page resources are only available to the
+page with which they are bundled.
+
+In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
+
+```text
+content
+└── post
+ ├── first-post
+ │ ├── images
+ │ │ ├── a.jpg
+ │ │ ├── b.jpg
+ │ │ └── c.jpg
+ │ ├── index.md (root of page bundle)
+ │ ├── latest.html
+ │ ├── manual.json
+ │ ├── notice.md
+ │ ├── office.mp3
+ │ ├── pocket.mp4
+ │ ├── rating.pdf
+ │ └── safety.txt
+ └── second-post
+ └── index.md (root of page bundle)
+```
+
+## Examples
+
+Use any of these methods on a `Page` object to capture page resources:
+
+- [`Resources.ByType`]
+- [`Resources.Get`]
+- [`Resources.GetMatch`]
+- [`Resources.Match`]
+
+ Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
+
+The following examples assume this content structure:
+
+```text
+content/
+└── example/
+ ├── data/
+ │ └── books.json <-- page resource
+ ├── images/
+ │ ├── a.jpg <-- page resource
+ │ └── b.jpg <-- page resource
+ ├── snippets/
+ │ └── text.md <-- page resource
+ └── index.md
+```
+
+Render a single image, and throw an error if the file does not exist:
+
+```go-html-template
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+Render all images, resized to 300 px wide:
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+Render the markdown snippet:
+
+```go-html-template
+{{ with .Resources.Get "snippets/text.md" }}
+ {{ .Content }}
+{{ end }}
+```
+
+List the titles in the data file, and throw an error if the file does not exist.
+
+```go-html-template
+{{ $path := "data/books.json" }}
+{{ with .Resources.Get $path }}
+ {{ with . | transform.Unmarshal }}
+ <p>Books:</p>
+ <ul>
+ {{ range . }}
+ <li>{{ .title }}</li>
+ {{ end }}
+ </ul>
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+## Metadata
+
+The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
+
+> [!note]
+> Resources of type `page` get `Title` etc. from their own front matter.
+
+name
+: (`string`) Sets the value returned in `Name`.
+
+> [!note]
+> The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
+
+title
+: (`string`) Sets the value returned in `Title`
+
+params
+: (`map`) A map of custom key-value pairs.
+
+### Resources metadata example
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=content/example.md fm=true >}}
+title: Application
+date: 2018-01-25
+resources:
+ - src: images/sunset.jpg
+ name: header
+ - src: documents/photo_specs.pdf
+ title: Photo Specifications
+ params:
+ icon: photo
+ - src: documents/guide.pdf
+ title: Instruction Guide
+ - src: documents/checklist.pdf
+ title: Document Checklist
+ - src: documents/payment.docx
+ title: Proof of Payment
+ - src: "**.pdf"
+ name: pdf-file-:counter
+ params:
+ icon: pdf
+ - src: "**.docx"
+ params:
+ icon: word
+{{</ code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+From the example above:
+
+- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
+- `documents/photo_specs.pdf` will get the `photo` icon.
+- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
+- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
+- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
+- Every docx in the bundle will receive the `word` icon.
+
+> [!note]
+> The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
+
+### The `:counter` placeholder in `name` and `title`
+
+The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
+
+The counter starts at 1 the first time they are used in either `name` or `title`.
+
+For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
+
+{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
+title = 'Engine inspections'
+[[resources]]
+ src = "*specs.pdf"
+ title = "Specification #:counter"
+[[resources]]
+ src = "**.pdf"
+ name = "pdf-file-:counter"
+{{</ code-toggle >}}
+
+the `Name` and `Title` will be assigned to the resource files as follows:
+
+| Resource file | `Name` | `Title` |
+|-------------------|-------------------|-----------------------|
+| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
+| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
- {{< new-in 0.123.0 />}}
-
++| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
++| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
+
+## Multilingual
+
+By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
+
+> [!note]
+> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
+
+Consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageName = 'English'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+└── my-bundle/
+ ├── a.jpg <-- shared page resource
+ ├── b.jpg <-- shared page resource
+ ├── c.de.jpg
+ ├── c.en.jpg
+ ├── index.de.md
+ └── index.en.md
+```
+
+With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource (duplicate)
+│ │ ├── b.jpg <-- shared page resource (duplicate)
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+
+```
+
+With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
+
+> [!important]
+> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
+>
+> In its default configuration, Hugo automatically uses the [embedded link render hook] and 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 link or image render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark]
+duplicateResourceFiles = true
+{{< /code-toggle >}}
+
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Resource`]: /methods/resource
+[`Resources.ByType`]: /methods/page/resources#bytype
+[`Resources.Get`]: /methods/page/resources/#get
+[`Resources.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Match`]: /methods/page/resources#match
+[content formats]: /content-management/formats/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
--- /dev/null
- The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
+---
+title: Shortcodes
+description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.
+categories: []
+keywords: []
+aliases: [/extras/shortcodes/]
+---
+
+## Introduction
+
+{{% glossary-term shortcode %}}
+
+There are three types of shortcodes: embedded, custom, and inline.
+
+## Embedded
+
+Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+{{% list-pages-in-section path=/shortcodes %}}
+
+## Custom
+
+Create custom shortcodes to simplify and standardize content creation. For example, the following _shortcode_ template generates an audio player using a [global resource](g):
+
+```go-html-template {file="layouts/_shortcodes/audio.html"}
+{{ with resources.Get (.Get "src") }}
+ <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+```
+
+Then call the shortcode from within markup:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+Learn more about creating shortcodes in the [shortcode templates] section.
+
+## Inline
+
+An inline shortcode is a _shortcode_ template defined within content.
+
+Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
+
+To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site's configuration:
+
+{{< code-toggle file=hugo >}}
+[security]
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+For more information see [configure security](/configuration/security).
+
+The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
+
+```text {file="content/example.md"}
+Today is
+{{</* date.inline ":date_medium" */>}}
+ {{- now | time.Format (.Get 0) -}}
+{{</* /date.inline */>}}.
+
+Today is {{</* date.inline ":date_full" /*/>}}.
+```
+
+In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:
+
+```html
+<p>Today is Jan 30, 2025.</p>
+<p>Today is Thursday, January 30, 2025</p>
+```
+
+Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method].
+
+> [!note]
+> You cannot [nest](#nesting) inline shortcodes.
+
+Learn more about creating shortcodes in the [shortcode templates] section.
+
+## Calling
+
+Shortcode calls involve three syntactical elements: tags, arguments, and notation.
+
+### Tags
+
+Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`] shortcode requires an opening and closing tag:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Some shortcodes do not accept content. For example, the embedded [`instagram`] shortcode requires a single _positional_ argument:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Some shortcodes optionally accept content. For example, you can call the embedded [`qr`] shortcode with content:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Or use the self-closing syntax with a trailing slash to pass the text as an argument:
+
+```text
+{{</* qr text=https://gohugo.io /*/>}}
+```
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Arguments
+
+Shortcode arguments can be either _named_ or _positional_.
+
+Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required.
+
+```text
+{{</* figure src=/images/kitten.jpg */>}}
+```
+
+Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.
+
+```text
+{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
+```
+
+Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
+
+```text
+{{</* my-shortcode name="John Smith" age=24 married=false */>}}
+```
+
+You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
+
+```text
+{{</* figure
+ src=/images/kitten.jpg
+ alt="A white kitten"
+ caption="This is a white kitten"
+ loading=lazy
+*/>}}
+```
+
+Use a [raw string literal](g) if you need to pass a multiline string:
+
+```text
+{{</* myshortcode `This is some <b>HTML</b>,
+and a new line with a "quoted string".` */>}}
+```
+
+Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Notation
+
+Shortcodes can be called using two different notations, distinguished by their tag delimiters.
+
+Notation|Example
+:--|:--
+Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}`
+Standard|`{{</* foo */>}} ## Section 2 {{</* /foo */>}}`
+
+#### Markdown notation
+
+Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object.
+
+#### Standard notation
+
+With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
+
+By way of example, with this _shortcode_ template:
+
+```go-html-template {file="layouts/_shortcodes/foo.html"}
+{{ .Inner }}
+```
+
+And this markdown:
+
+```text {file="content/example.md"}
+{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
+
+{{</* foo */>}} ## Section 2 {{</* /foo */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<h2 id="heading">Section 1</h2>
+
+## Section 2
+```
+
+In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
+
++> [!note]
++> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
+
+## Nesting
+
+Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
+
+```text {file="content/example.md"}
+{{</* gallery class="content-gallery" */>}}
+ {{</* image src="/images/a.jpg" */>}}
+ {{</* image src="/images/b.jpg" */>}}
+ {{</* image src="/images/c.jpg" */>}}
+{{</* /gallery */>}}
+```
+
+The [shortcode templates][nesting] section provides a detailed explanation and examples.
+
+[`details`]: /shortcodes/details
+[`figure`]: /shortcodes/figure
+[`instagram`]: /shortcodes/instagram
+[`qr`]: /shortcodes/qr
+[`TableOfContents`]: /methods/page/tableofcontents/
+[layout string]: /functions/time/format/#layout-string
+[nesting]: /templates/shortcode/#nesting
+[shortcode method]: /templates/shortcode/#methods
+[shortcode templates]: /templates/shortcode/
--- /dev/null
- > - 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.
+---
+title: URL management
+description: Control the structure and appearance of URLs through front matter entries and settings in your site configuration.
+categories: []
+keywords: []
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+---
+
+## Overview
+
+By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
+
+```text
+content/posts/post-1.md → https://example.org/posts/post-1/
+```
+
+You can change the structure and appearance of URLs with front matter values and site configuration options.
+
+## Front matter
+
+### `slug`
+
+Set the `slug` in front matter to override the last segment of the path. This front matter field is not applicable to `home`, `section`, `taxonomy`, or `term` pages.
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Post'
+slug = 'my-first-post'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/posts/my-first-post/
+```
+
+### `url`
+
+Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
+
+> [!note]
+> Hugo does not sanitize the `url` front matter field, allowing you to generate:
+>
- 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.
++> - 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.
+
+#### Include a colon
+
+{{< new-in 0.136.0 />}}
+
+If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
+
+For example, with this front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+url: "my\\:example"
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/my:example/
+```
+
+As described above, this will fail on Windows because the colon (`:`) is a reserved character.
+
+#### File extensions
+
+With this front matter:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article/
+```
+
+If you include a file extension:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article.html'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article.html
+```
+
+#### Leading slashes
+
- > This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
++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
+:--|:--|:--
+monolingual|`/about`|`https://example.org/about/`
+monolingual|`about`|`https://example.org/about/`
+multilingual|`/about`|`https://example.org/about/`
+multilingual|`about`|`https://example.org/de/about/`
+
+#### Permalinks tokens in front matter
+
+{{< new-in 0.131.0 />}}
+
+You can also use tokens when setting the `url` value. This is typically used in `cascade` sections:
+
+{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
+title ="Bar"
+[[cascade]]
+ url = "/:sections[last]/:slug"
+{{< /code-toggle >}}
+
+Use any of these tokens:
+
+{{% include "/_common/permalink-tokens.md" %}}
+
+## Site configuration
+
+### Permalinks
+
+See [configure permalinks](/configuration/permalinks).
+
+### Appearance
+
+See [configure ugly URLs](/configuration/ugly-urls/).
+
+### Post-processing
+
+Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
+
+#### Canonical URLs
+
+> [!caution]
- Create redirects from old URLs to new URLs with aliases:
++> 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.
+
+```html
+<a href="/about"> → <a href="https://example.org/about/">
+<img src="/a.gif"> → <img src="https://example.org/a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+canonifyURLs = true
+{{< /code-toggle >}}
+
+#### Relative URLs
+
+> [!caution]
+> Do not enable this option unless you are creating a serverless site, navigable via the file system.
+{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 transforms the URL to be relative to the current page.
+
+For example, when rendering `content/posts/post-1`:
+
+```html
+<a href="/about"> → <a href="../../about">
+<img src="/a.gif"> → <img src="../../a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+relativeURLs = true
+{{< /code-toggle >}}
+
+## Aliases
+
- - An alias with a leading slash is relative to the `baseURL`
- - An alias without a leading slash is relative to the current directory
++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.
+
- ### Examples {#alias-examples}
++### Defining aliases
+
- 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']
++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.
+
- Each of these directory-relative aliases is equivalent to the site-relative alias above:
++{{< 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 >}}
+
- - `previous-file-name`
- - `./previous-file-name`
- - `../posts/previous-file-name`
++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:
+
- You can create more than one alias to the current page:
++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/`
+
- {{< code-toggle file=content/posts/new-file-name.md fm=true >}}
- aliases = ['previous-file-name','original-file-name']
- {{< /code-toggle >}}
++### Redirection methods
+
- In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
-
- {{< code-toggle file=content/posts/new-file-name.de.md fm=true >}}
- aliases = ['/de/posts/previous-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.
+
- ### How aliases work
++> [!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.
+
- Using the first example above, Hugo generates the following site structure:
++#### Client-side redirection
+
- ```text
- public/
- ├── posts/
- │ ├── new-file-name/
- │ │ └── index.html
- │ ├── previous-file-name/
- │ │ └── index.html
- │ └── index.html
- └── index.html
- ```
++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.
+
- The alias from the previous URL to the new URL is a client-side redirect:
++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`.
+
- ```html {file="posts/previous-file-name/index.html"}
++Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files:
+
- <html lang="en-us">
++```go-html-template
+<!DOCTYPE html>
- <title>https://example.org/posts/new-file-name/</title>
- <link rel="canonical" href="https://example.org/posts/new-file-name/">
++<html lang="{{ site.Language.LanguageCode }}">
+ <head>
- <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
++ <title>{{ .Permalink }}</title>
++ {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
+ <meta charset="utf-8">
- 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.
++ <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
+ </head>
+</html>
+```
+
- 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.
++To override this, create a file named `alias.html` in your `layouts` directory. This custom template has access to the following context:
++
++`Permalink`
++: (`string`) The absolute URL of the destination page.
++
++`Page`
++: (`page.Page`) The full `Page` object of the destination.
+
- Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
++#### Server-side redirection
+
- ### Customize
++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.
+
- 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:
++To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:
+
- Permalink
- : The link to 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.
+
- Page
- : The Page data for the page being aliased.
++See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
+
- [source code]: <{{% eturl alias %}}>
++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
--- /dev/null
- CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.152.2
+---
+title: Development
+description: Contribute to the development of Hugo.
+categories: []
+keywords: []
+---
+
+## Introduction
+
+You can contribute to the Hugo project by:
+
+- Answering questions on the [forum]
+- Improving the [documentation]
+- Monitoring the [issue queue]
+- Creating or improving [themes]
+- Squashing [bugs]
+
+Please submit documentation issues and pull requests to the [documentation repository].
+
+If you have an idea for an enhancement or new feature, create a new topic on the [forum] in the "Feature" category. This will help you to:
+
+- Determine if the capability already exists
+- Measure interest
+- Refine the concept
+
+If there is sufficient interest, [create a proposal]. Do not submit a pull request until the project lead accepts the proposal.
+
+For a complete guide to contributing to Hugo, see the [Contribution Guide].
+
+## Prerequisites
+
+To build the extended or extended/deploy edition from source you must:
+
+1. Install [Git]
+1. Install [Go] version 1.24.0 or later
+1. Install a C compiler, either [GCC] or [Clang]
+1. Update your `PATH` environment variable as described in the [Go documentation]
+
+> [!note]
+> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+
+## GitHub workflow
+
+> [!note]
+> This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [project repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number.
+
+ For a new feature:
+
+ ```sh
+ git checkout -b feat/implement-some-feature-99999
+ ```
+
+ For a bug fix:
+
+ ```sh
+ git checkout -b fix/fix-some-bug-99999
+ ```
+
+Step 4
+: Make changes.
+
+Step 5
+: Compile and install.
+
+ To compile and install the standard edition:
+
+ ```text
+ go install
+ ```
+
+ To compile and install the extended edition:
+
+ ```text
+ CGO_ENABLED=1 go install -tags extended
+ ```
+
+ To compile and install the extended/deploy edition:
+
+ ```text
+ CGO_ENABLED=1 go install -tags extended,withdeploy
+ ```
+
+Step 6
+: Test your changes:
+
+ ```text
+ go test ./...
+ ```
+
+Step 7
+: Commit your changes with a descriptive commit message:
+
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with the name of the package, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - See the [commit message guidelines] for requirements
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+ For example:
+
+ ```sh
+ git commit -m "tpl/strings: Create wrap function
+
+ The strings.Wrap function wraps a string into one or more lines,
+ splitting the string after the given number of characters, but not
+ splitting in the middle of a word.
+
+ Fixes #99998
+ Closes #99999"
+ ```
+
+Step 8
+: Push the new branch to your fork of the documentation repository.
+
+Step 9
+: Visit the [project repository] and create a pull request (PR).
+
+Step 10
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+## Building from source
+
+You can build, install, and test Hugo at any point in its development history. The examples below build and install the extended edition of Hugo.
+
+To build and install the latest release:
+
+```sh
+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.155.3
+```
+
+To build and install at the latest commit on the master branch:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master
+```
+
+To build and install at a specific commit:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@c0d9beb
+```
+
+[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
+[Clang]: https://clang.llvm.org/
+[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
+[Contribution Guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
+[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
+[documentation]: /documentation
+[documentation repository]: https://github.com/gohugoio/hugoDocs
+[forum]: https://discourse.gohugo.io
+[GCC]: https://gcc.gnu.org/
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[Go documentation]: https://go.dev/doc/code#Command
+[issue queue]: https://github.com/gohugoio/hugo/issues
+[issues]: https://github.com/gohugoio/hugo/issues
+[project repository]: https://github.com/gohugoio/hugo/
+[themes]: https://themes.gohugo.io/
--- /dev/null
- description: Slices an array to the items after the Nth item.
+---
+title: collections.After
- returnType: any
- signatures: [collections.After INDEX COLLECTION]
++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 N SLICE]
+aliases: [/functions/after]
+---
+
+The following shows `after` being used in conjunction with the [`slice`]function:
+
+```go-html-template
+{{ $data := slice "one" "two" "three" "four" }}
+<ul>
+ {{ range after 2 $data }}
+ <li>{{ . }}</li>
+ {{ end }}
+</ul>
+```
+
+The template above is rendered to:
+
+```html
+<ul>
+ <li>three</li>
+ <li>four</li>
+</ul>
+```
+
+## Example of `after` with `first`: 2nd–4th most recent articles
+
+You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods](/quick-reference/page-collections/#sort). Let's assume you have a `section` page at `example.com/articles`. You have 10 articles, but you want your template to show only two rows:
+
+1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
+1. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+
+```go-html-template {file="layouts/section/articles.html"}
+{{ define "main" }}
+ <section class="row featured-article">
+ <h2>Featured Article</h2>
+ {{ range first 1 .Pages.ByPublishDate.Reverse }}
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ {{ end }}
+ </section>
+ <div class="row recent-articles">
+ <h2>Recent Articles</h2>
+ {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
+ <section class="recent-article">
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ </section>
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+[`first`]: /functions/collections/first/
+[`slice`]: /functions/collections/slice/
--- /dev/null
- description: Appends one or more elements to a slice and returns the resulting slice.
+---
+title: collections.Append
- returnType: any
- signatures:
- - collections.Append ELEMENT [ELEMENT...] COLLECTION
- - collections.Append COLLECTION1 COLLECTION2
++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...] SLICE
++ - collections.Append SLICE1 SLICE2
+aliases: [/functions/append]
+---
+
+This function appends all elements, excluding the last, to the last element. This allows [pipe](g) constructs as shown below.
+
+Append a single element to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" }}
+{{ $s }} → [a b c]
+```
+
+Append two elements to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" "d" }}
+{{ $s }} → [a b c d]
+```
+
+Append two elements, as a slice, to a slice. This produces the same result as the previous example:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [a b c d]
+```
+
+Start with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append "a" }}
+{{ $s }} → [a]
+
+{{ $s = $s | append "b" "c" }}
+{{ $s }} → [a b c]
+
+{{ $s = $s | append (slice "d" "e") }}
+{{ $s }} → [a b c d e]
+```
+
+If you start with a slice of a slice:
+
+```go-html-template
+{{ $s := slice (slice "a" "b") }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+To create a slice of slices, starting with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append (slice (slice "a" "b")) }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+Although the elements in the examples above are strings, you can use the `append` function with any data type, including Pages. For example, on the home page of a corporate site, to display links to the two most recent press releases followed by links to the four most recent articles:
+
+```go-html-template
+{{ $p := where site.RegularPages "Type" "press-releases" | first 2 }}
+{{ $p = $p | append (where site.RegularPages "Type" "articles" | first 4) }}
+
+{{ with $p }}
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
--- /dev/null
- description: Returns a new collection with each element transformed by the given function.
+---
+title: collections.Apply
- signatures: [collections.Apply COLLECTION FUNCTION PARAM...]
++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'
- The `apply` function takes three or more arguments, depending on the function being applied to the collection elements.
++ signatures: [collections.Apply SLICE FUNCTION PARAM...]
+aliases: [/functions/apply]
+---
+
- 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 `apply` function takes three or more arguments, depending on the function being applied to the slice elements.
+
++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" }}
+
+{{ $s = apply $s "strings.FirstUpper" "." }}
+{{ $s }} → [Hello World]
+
+{{ $s = apply $s "strings.Replace" "." "l" "_" }}
+{{ $s }} → [He__o Wor_d]
+```
--- /dev/null
- description: Returns the elements of the last collection that are not in any of the others.
+---
+title: collections.Complement
- returnType: any
- signatures: ['collections.Complement COLLECTION [COLLECTION...]']
++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 SLICE [SLICE...]']
+aliases: [/functions/complement]
+---
+
+To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
+
+```go-html-template
+{{ $c1 := slice 3 }}
+{{ $c2 := slice 4 5 }}
+{{ $c3 := slice 1 2 3 4 5 }}
+
+{{ complement $c1 $c2 $c3 }} → [1 2]
+```
+
+> [!note]
+> Make your code simpler to understand by using a [chained pipeline]:
+
+```go-html-template
+{{ $c3 | complement $c1 $c2 }} → [1 2]
+```
+
+You can also use the `complement` function with page collections. Let's say your site has five content types:
+
+```text
+content/
+├── blog/
+├── books/
+├── faqs/
+├── films/
+└── songs/
+```
+
+To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
+
+```go-html-template
+{{ $blog := where site.RegularPages "Type" "blog" }}
+{{ $faqs := where site.RegularPages "Type" "faqs" }}
+{{ range site.RegularPages | complement $blog $faqs }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+> [!note]
+> Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
+
+```go-html-template
+{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+In this example we use the `complement` function to remove [stop words] from a sentence:
+
+```go-html-template
+{{ $text := "The quick brown fox jumps over the lazy dog" }}
+{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
+{{ $filtered := split $text " " | complement $stopWords }}
+
+{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
+```
+
+[`where`]: /functions/collections/where/
+[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
+[stop words]: https://en.wikipedia.org/wiki/Stop_word
--- /dev/null
- description: Returns a slice of sequentially ordered random integers.
+---
+title: collections.D
- 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.
++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 />}}
+
- See [this article][] for a detailed explanation.
++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.
+
- > [!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.
-
++- `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
+
+```go-html-template
+{{ collections.D 6 7 42 }} → [4, 9, 10, 20, 22, 24, 41]
+```
+
+The example above generates the _same_ random numbers each time it is called. To generate a _different_ set of 7 random numbers in the same range, change the seed value.
+
+```go-html-template
+{{ 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
+<ul>
+ {{ $p := site.RegularPages }}
+ {{ range collections.D time.Now.YearDay 5 ($p | len) }}
+ {{ with (index $p .) }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+The construct above is significantly faster than using the [`collections.Shuffle`][] function.
+
+## Seed value
+
+Choosing an appropriate seed value depends on your objective.
+
+Objective|Seed example
+:--|:--
+Consistent result|`42`
+Different result on each call|`int time.Now.UnixNano`
+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)`
+
- [this article]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
+[`collections.Shuffle`]: /functions/collections/shuffle/
+[day of the year]: /methods/time/yearday/
++[Method D]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
--- /dev/null
- description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
+---
+title: collections.Delimit
- signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]']
++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 SLICE|MAP DELIMITER [LAST]']
+aliases: [/functions/delimit]
+---
+
+Delimit a slice:
+
+```go-html-template
+{{ $s := slice "b" "a" "c" }}
+{{ delimit $s ", " }} → b, a, c
+{{ delimit $s ", " " and "}} → b, a and c
+```
+
+Delimit a map:
+
+> [!note]
+> The `delimit` function sorts maps by key, returning the values.
+
+```go-html-template
+{{ $m := dict "b" 2 "a" 1 "c" 3 }}
+{{ delimit $m ", " }} → 1, 2, 3
+{{ delimit $m ", " " and "}} → 1, 2 and 3
+```
--- /dev/null
- description: Returns a map composed of the given key-value pairs.
+---
+title: collections.Dictionary
++description: Returns a map created from the given key-value pairs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [dict]
+ returnType: map[string]any
+ signatures: ['collections.Dictionary [VALUE...]']
+aliases: [/functions/dict]
+---
+
+Specify the key-value pairs as individual arguments:
+
+```go-html-template
+{{ $m := dict "a" 1 "b" 2 }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": 1,
+ "b": 2
+}
+```
+
+To create an empty map:
+
+```go-html-template
+{{ $m := dict }}
+```
+
+Note that the `key` can be either a `string` or a `[]string`. The latter is useful to create a deeply nested structure, e.g.:
+
+```go-html-template
+{{ $m := dict (slice "a" "b" "c") "value" }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": {
+ "b": {
+ "c": "value"
+ }
+ }
+}
+```
--- /dev/null
- description: Returns the given collection, limited to the first N elements.
+---
+title: collections.First
- returnType: any
- signatures: [collections.First N COLLECTION]
++description: Returns the first N elements of the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [first]
- Set `N` to zero to return an empty collection:
++ returnType: 'any'
++ signatures: [collections.First N SLICE|STRING]
+aliases: [/functions/first]
+---
+
+```go-html-template
+{{ slice "a" "b" "c" | first 1 }} → [a]
+{{ slice "a" "b" "c" | first 2 }} → [a b]
+```
+
+Given that a string is in effect a read-only slice of bytes, this function can be used to return the specified number of bytes from the beginning of the string:
+
+```go-html-template
+{{ "abc" | first 1 }} → a
+{{ "abc" | first 2 }} → ab
+```
+
+Note that a _character_ may consist of multiple _bytes_:
+
+```go-html-template
+{{ "Schön" | first 3 }} → Sch
+{{ "Schön" | first 4 }} → Sch\xc3
+{{ "Schön" | first 5 }} → Schö
+```
+
+To use the `collections.First` function with a page collection:
+
+```go-html-template
+{{ range first 5 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
++Set `N` to zero to return an empty slice:
+
+```go-html-template
+{{ $emptyPageCollection := first 0 .Pages }}
+```
+
+Use `first` and [`where`][] together:
+
+```go-html-template
+{{ range where .Pages "Section" "articles" | first 5 }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+[`where`]: /functions/collections/where/
--- /dev/null
- description: Groups the given page collection by the given key.
+---
+title: collections.Group
- returnType: any
++description: Returns a map by grouping the given page collection (slice) by a specific key.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [group]
++ returnType: page.PageGroup
+ signatures: [collections.Group KEY PAGES]
+aliases: [/functions/group]
+---
+
+```go-html-template
+{{ $new := .Site.RegularPages | first 10 | group "New" }}
+{{ $old := .Site.RegularPages | last 10 | group "Old" }}
+{{ $groups := slice $new $old }}
+{{ range $groups }}
+ <h3>{{ .Key }}{{/* Prints "New", "Old" */}}</h3>
+ <ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The page group you get from `group` is of the same type you get from the built-in [group methods](/quick-reference/page-collections/#group) in Hugo. The example above can be [paginated](/templates/pagination/).
--- /dev/null
- description: Reports whether the given value is a member of the given set.
+---
+title: collections.In
- signatures: [collections.In SET VALUE]
++description: Reports whether a value exists within the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [in]
+ returnType: bool
- The `SET` can be an [array](g), [slice](g), or [string](g).
-
++ signatures: [collections.In SLICE|STRING VALUE]
+aliases: [/functions/in]
+---
+
- ```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 := slice "a" "b" "c" }}
+{{ in $s "b" }} → true
+```
+
+```go-html-template
+{{ $s := "abc" }}
+{{ in $s "b" }} → true
+```
--- /dev/null
- description: Returns the object, element, or value associated with the given key or keys.
+---
+title: collections.Index
- signatures: [collections.Index COLLECTION KEY...]
++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 SLICE|MAP KEY...]
+aliases: [/functions/index,/functions/index-function]
+---
+
+Each indexed item must be a map or a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ index $s 0 }} → a
+{{ index $s 1 }} → b
+
+{{ $m := dict "a" 100 "b" 200 }}
+{{ index $m "b" }} → 200
+```
+
+Use two or more keys to access a nested value:
+
+```go-html-template
+{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
+{{ index $m "c" 1 }} → 20
+
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ index $m "c" "e" }} → 20
+```
+
+You may also use a slice of keys to access a nested value:
+
+```go-html-template
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ $s := slice "c" "e" }}
+{{ index $m $s }} → 20
+```
+
+Use the `collections.Index` function to access a nested value when the key is variable. For example, these are equivalent:
+
+```go-html-template
+{{ .Site.Params.foo }}
+
+{{ $k := "foo" }}
+{{ index .Site.Params $k }}
+```
--- /dev/null
- description: Returns the common elements of two arrays or slices, in the same order as the first array.
+---
+title: collections.Intersect
- returnType: any
- signatures: [collections.Intersect SET1 SET2]
++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 SLICE1 SLICE2]
+aliases: [/functions/intersect]
+---
+
+A useful example is to use it as `AND` filters when combined with where:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [union](/functions/collections/union) for `OR`.
--- /dev/null
- description: Reports whether the key exists within the collection.
+---
+title: collections.IsSet
- signatures: [collections.IsSet COLLECTION KEY]
++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 MAP|SLICE KEY|INDEX]
+aliases: [/functions/isset]
+---
+
+For example, consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+showHeroImage = false
+{{< /code-toggle >}}
+
+If the value of `showHeroImage` is `true`, we can detect that it exists using either `if` or `with`:
+
+```go-html-template
+{{ if site.Params.showHeroImage }}
+ {{ site.Params.showHeroImage }} → true
+{{ end }}
+
+{{ with site.Params.showHeroImage }}
+ {{ . }} → true
+{{ end }}
+```
+
+But if the value of `showHeroImage` is `false`, we can't use either `if` or `with` to detect its existence. In this case, you must use the `isset` function:
+
+```go-html-template
+{{ if isset site.Params "showheroimage" }}
+ <p>The showHeroImage parameter is set to {{ site.Params.showHeroImage }}.<p>
+{{ end }}
+```
+
+> [!note]
+> When using the `isset` function you must reference the key using lower case. See the previous example.
--- /dev/null
- description: Returns a KeyVals struct.
+---
+title: collections.KeyVals
++description: Returns a KeyVals struct by pairing a given key and values.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [keyVals]
+ returnType: types.KeyValues
+ signatures: [collections.KeyVals KEY VALUE...]
+aliases: [/functions/keyvals]
+---
+
+The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
+
+[`Related`]: /methods/pages/related/
+
+See [related content](/content-management/related-content/).
+
+```go-html-template
+{{ $kv := keyVals "foo" "a" "b" "c" }}
+```
+
+The resulting data structure is:
+
+```json
+{
+ "Key": "foo",
+ "Values": [
+ "a",
+ "b",
+ "c"
+ ]
+}
+```
+
+To extract the key and values:
+
+```go-html-template
+{{ $kv.Key }} → foo
+{{ $kv.Values }} → [a b c]
+```
--- /dev/null
- description: Returns the given collection, limited to the last N elements.
+---
+title: collections.Last
- returnType: any
- signatures: [collections.Last N COLLECTION]
++description: Returns the last N elements of the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [last]
- Set `N` to zero to return an empty collection:
++ returnType: 'any'
++ signatures: [collections.Last N SLICE|STRING]
+aliases: [/functions/last]
+---
+
+```go-html-template
+{{ slice "a" "b" "c" | last 1 }} → [c]
+{{ slice "a" "b" "c" | last 2 }} → [b c]
+```
+
+Given that a string is in effect a read-only slice of bytes, this function can be used to return the specified number of bytes from the end of the string:
+
+```go-html-template
+{{ "abc" | last 1 }} → c
+{{ "abc" | last 2 }} → bc
+```
+
+Note that a _character_ may consist of multiple _bytes_:
+
+```go-html-template
+{{ "Schön" | last 1 }} → n
+{{ "Schön" | last 2 }} → \xb6n
+{{ "Schön" | last 3 }} → ön
+```
+
+To use the `collections.Last` function with a page collection:
+
+```go-html-template
+{{ range last 5 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
++Set `N` to zero to return an empty slice:
+
+```go-html-template
+{{ $emptyPageCollection := last 0 .Pages }}
+```
+
+Use `last` and [`where`][] together:
+
+[`where`]: /functions/collections/where/
+
+```go-html-template
+{{ range where .Pages "Section" "articles" | last 5 }}
+ {{ .Render "summary" }}
+{{ end }}
+```
--- /dev/null
- description: Returns the result of merging two or more maps.
+---
+title: collections.Merge
- returnType: any
++description: Returns a map by combining two or more given maps.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [merge]
++ returnType: map[string]any
+ signatures: [collections.Merge MAP MAP...]
+aliases: [/functions/merge]
+---
+
+Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
+
+Key handling is case-insensitive.
+
+The following examples use these map definitions:
+
+```go-html-template
+{{ $m1 := dict "x" "foo" }}
+{{ $m2 := dict "x" "bar" "y" "wibble" }}
+{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
+```
+
+Example 1
+
+```go-html-template
+{{ $merged := merge $m1 $m2 $m3 }}
+
+{{ $merged.x }} → baz
+{{ $merged.y }} → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 2
+
+```go-html-template
+{{ $merged := merge $m3 $m2 $m1 }}
+
+{{ $merged.x }} → foo
+{{ $merged.y }} → wibble
+{{ $merged.z.a }} → huey
+```
+
+Example 3
+
+```go-html-template
+{{ $merged := merge $m2 $m3 $m1 }}
+
+{{ $merged.x }} → foo
+{{ $merged.y }} → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 4
+
+```go-html-template
+{{ $merged := merge $m1 $m3 $m2 }}
+
+{{ $merged.x }} → bar
+{{ $merged.y }} → wibble
+{{ $merged.z.a }} → huey
+```
+
+> [!note]
+> Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
--- /dev/null
- signatures: [collections.NewScratch ]
+---
+title: collections.NewScratch
+description: Returns a locally scoped "scratch pad" to store and manipulate data.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [newScratch]
+ returnType: maps.Scratch
++ 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.
+
+## Methods
+
+### Set
+
+Sets the value of the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+```
+
+### Get
+
+Gets the value of the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Get "greeting" }} → Hello
+```
+
+### Add
+
+Adds the given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Add "greeting" "Welcome" }}
+{{ $s.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "total" 3 }}
+{{ $s.Add "total" 7 }}
+{{ $s.Get "total" }} → 10
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greetings" (slice "Hello") }}
+{{ $s.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ $s.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.DeleteInMap "greetings" "english" }}
+{{ $s.Get "greetings" }} → map[french:Bonjour]
+```
+
+### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Delete "greeting" }}
+```
+
+### Values
+
+Returns the raw backing map. Do not use with `Store` methods on a `Page` object due to concurrency issues.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+
+{{ $map := $s.Values }}
+```
+
+{{% include "_common/scratch-pad-scope.md" %}}
--- /dev/null
- description: Returns a URL query string composed of the given key-value pairs, encoded and sorted by key.
+---
+title: collections.Querify
- signatures: ['collections.Querify [VALUE...]']
++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 MAP|SLICE|KEY VALUE...]
+aliases: [/functions/querify]
+---
+
+Specify the key-value pairs as a map, a slice, or a sequence of scalar values. For example, the following are equivalent:
+
+```go-html-template
+{{ collections.Querify (dict "a" 1 "b" 2) }}
+{{ collections.Querify (slice "a" 1 "b" 2) }}
+{{ collections.Querify "a" 1 "b" 2 }}
+```
+
+To append a query string to a URL:
+
+```go-html-template
+{{ $qs := collections.Querify (dict "a" 1 "b" 2) }}
+{{ $href := printf "https://example.org?%s" $qs }}
+
+<a href="{{ $href }}">Link</a>
+```
+
+Hugo renders this to:
+
+```html
+<a href="https://example.org?a=1&b=2">Link</a>
+```
+
+You can also pass in a map from your site configuration or front matter. For example:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+[params.query]
+a = 1
+b = 2
+{{< /code-toggle >}}
+
+```go-html-template
+{{ collections.Querify .Params.query }}
+```
--- /dev/null
- description: Reverses the order of a collection.
+---
+title: collections.Reverse
- returnType: any
- signatures: [collections.Reverse 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 SLICE]
+aliases: [/functions/collections.reverse]
+---
+
+```go-html-template
+{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]
+```
--- /dev/null
- description: Returns a slice of integers.
+---
+title: collections.Seq
++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:
+ functions_and_methods:
+ aliases: [seq]
+ returnType: '[]int'
+ signatures:
+ - collections.Seq LAST
+ - collections.Seq FIRST LAST
+ - collections.Seq FIRST INCREMENT LAST
+aliases: [/functions/seq]
+---
+
+```go-html-template
+{{ seq 2 }} → [1 2]
+{{ seq 0 2 }} → [0 1 2]
+{{ seq -2 2 }} → [-2 -1 0 1 2]
+{{ seq -2 2 2 }} → [-2 0 2]
+```
+
+A contrived example of iterating over a sequence of integers:
+
+```go-html-template
+{{ $product := 1 }}
+{{ range seq 4 }}
+ {{ $product = mul $product . }}
+{{ end }}
+{{ $product }} → 24
+```
+
+> [!note]
+> The slice created by this function is limited to 1 million elements.
--- /dev/null
- description: Returns a random permutation of a given array or slice.
+---
+title: collections.Shuffle
- returnType: any
- signatures: [collections.Shuffle COLLECTION]
++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 SLICE]
+aliases: [/functions/shuffle]
+---
+
+```go-html-template
+{{ collections.Shuffle (slice "a" "b" "c") }} → [b a c]
+```
+
+The result will vary from one build to the next.
+
+To render an unordered list of 5 random pages from a page collection:
+
+```go-html-template
+<ul>
+ {{ $p := site.RegularPages }}
+ {{ range $p | collections.Shuffle | first 5 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+{{< new-in 0.149.0 />}}
+
+Using the [`collections.D`][] function for the same task is significantly faster.
+
+[`collections.D`]: /functions/collections/D/
--- /dev/null
- description: Returns a slice composed of the given values.
+---
+title: collections.Slice
- returnType: any
++description: Returns a slice created from the given values.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [slice]
++ returnType: '[]any'
+ signatures: ['collections.Slice [VALUE...]']
+aliases: [/functions/slice]
+---
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ $s }} → [a b c]
+```
+
+To create an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+```
--- /dev/null
- description: Sorts slices, maps, and page collections.
+---
+title: collections.Sort
- signatures: ['collections.Sort COLLECTION [KEY] [ORDER]']
++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 MAP|SLICE [KEY] [ORDER]']
+aliases: [/functions/sort]
+---
+
+The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
+
+The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
+
+## Sort a slice
+
+The examples below assume this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+grades = ['b','a','c']
+{{< /code-toggle >}}
+
+### Ascending order {#slice-ascending-order}
+
+Sort slice elements in ascending order using either of these constructs:
+
+```go-html-template
+{{ sort site.Params.grades }} → [a b c]
+{{ sort site.Params.grades "value" "asc" }} → [a b c]
+```
+
+In the examples above, `value` is the `KEY` representing the value of the slice element.
+
+### Descending order {#slice-descending-order}
+
+Sort slice elements in descending order:
+
+```go-html-template
+{{ sort site.Params.grades "value" "desc" }} → [c b a]
+```
+
+In the example above, `value` is the `KEY` representing the value of the slice element.
+
+## Sort a map
+
+The examples below assume this site configuration:
+
+{{< code-toggle file=hugo >}}
+[params.authors.a]
+firstName = "Marius"
+lastName = "Pontmercy"
+[params.authors.b]
+firstName = "Victor"
+lastName = "Hugo"
+[params.authors.c]
+firstName = "Jean"
+lastName = "Valjean"
+{{< /code-toggle >}}
+
+> [!note]
+> When sorting maps, the `KEY` argument must be lowercase.
+
+### Ascending order {#map-ascending-order}
+
+Sort map objects in ascending order using either of these constructs:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" }}
+ {{ .firstName }}
+{{ end }}
+
+{{ range sort site.Params.authors "firstname" "asc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+These produce:
+
+```text
+Jean Marius Victor
+```
+
+### Descending order {#map-descending-order}
+
+Sort map objects in descending order:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" "desc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+This produces:
+
+```text
+Victor Marius Jean
+```
+
+### First level key removal
+
+Hugo removes the first level keys when sorting a map.
+
+Original map:
+
+```json
+{
+ "felix": {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ "spot": {
+ "breed": "boxer",
+ "type": "dog"
+ }
+}
+```
+
+After sorting:
+
+```json
+[
+ {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ {
+ "breed": "boxer",
+ "type": "dog"
+ }
+]
+```
+
+## Sort a page collection
+
+> [!note]
+> Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
+
+In this contrived example, sort the site's regular pages by `.Type` in descending order:
+
+```go-html-template
+{{ range sort site.RegularPages "Type" "desc" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+[sorting and grouping methods]: /methods/pages/
--- /dev/null
- description: Returns the symmetric difference of two collections.
+---
+title: collections.SymDiff
- returnType: any
- signatures: [COLLECTION | collections.SymDiff COLLECTION]
++description: Returns a slice containing the symmetric difference of two given slices.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [symdiff]
++ returnType: '[]any'
++ signatures: [SLICE1 | collections.SymDiff SLICE2]
+aliases: [/functions/symdiff]
+---
+
+Example:
+
+```go-html-template
+{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]
+```
+
+Also see <https://en.wikipedia.org/wiki/Symmetric_difference>.
--- /dev/null
- description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices.
+---
+title: collections.Union
- returnType: any
- signatures: [collections.Union SET1 SET2]
++description: Returns a slice containing the unique elements from two given slices.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [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.
++ returnType: '[]any'
++ signatures: [collections.Union SLICE1 SLICE2]
+aliases: [/functions/union]
+---
+
-
- {{ union (slice 1 2 3) nil }} → [1 2 3]
-
- {{ union nil (slice 1 2 3) }} → [1 2 3]
-
- {{ union nil nil }} → []
++
+
+```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 }} → []
+```
+
+## OR filter in where query
+
+This is also very useful to use as `OR` filters when combined with where:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [intersect](/functions/collections/intersect) for `AND`.
--- /dev/null
- description: Returns the given collection, removing duplicate elements.
+---
+title: collections.Uniq
- returnType: any
- signatures: [collections.Uniq COLLECTION]
++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 SLICE]
+aliases: [/functions/uniq]
+---
+
+```go-html-template
+{{ slice 1 3 2 1 | uniq }} → [1 3 2]
+```
--- /dev/null
- description: Returns the given collection, removing elements that do not satisfy the comparison condition.
+---
+title: collections.Where
- returnType: any
- signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE']
++description: Returns a slice by filtering the given slice based on a key, operator, and value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [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:
++ returnType: '[]any'
++ signatures: ['collections.Where SLICE KEY [OPERATOR] VALUE']
+aliases: [/functions/where]
+---
+
- collections.Where COLLECTION KEY [OPERATOR] VALUE
- --------------------
- comparison condition
++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
- COLLECTION
- : (`any`) A [page collection](g) or a [slice](g) of [maps](g).
++collections.Where SLICE KEY [OPERATOR] VALUE
++ --------------------
++ comparison condition
+```
+
+Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "books" }}
+{{ $books := where .Site.Data.books "genres" "suspense" }}
+```
+
+## Arguments
+
+The where function takes three or four arguments. The `OPERATOR` argument is optional.
+
- ```go-html-template
- {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
- ```
++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:
+
- For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
++ ```go-html-template
++ {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
++ ```
+
+OPERATOR
+: (`string`) The logical comparison [operator](#operators).
+
+VALUE
+: (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
+
+Comparison|Result
+:--|:--
+`"123" "eq" "123"`|`true`
+`"123" "eq" 123`|`false`
+`false "eq" "false"`|`false`
+`false "eq" false`|`true`
+
+When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
+
+## Operators
+
+Use any of the following logical operators:
+
+`=`, `==`, `eq`
+: (`bool`) Reports whether the given field value is equal to `VALUE`.
+
+`!=`, `<>`, `ne`
+: (`bool`) Reports whether the given field value is not equal to `VALUE`.
+
+`>=`, `ge`
+: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
+
+`>`, `gt`
+: `true` Reports whether the given field value is greater than `VALUE`.
+
+`<=`, `le`
+: (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
+
+`<`, `lt`
+: (`bool`) Reports whether the given field value is less than `VALUE`.
+
+`in`
+: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`not in`
+: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`intersect`
+: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
+
+`like`
+: (`bool`) Reports whether the given field value matches the [regular expression](g) specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
+
+> [!note]
+> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
+
+## String comparison
+
+Compare the value of the given field to a [`string`](g):
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
+{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
+```
+
+## Numeric comparison
+
+Compare the value of the given field to an [`int`](g) or [`float`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.price" "eq" 42 }}
+{{ $pages := where $books "Params.price" "ne" 42.67 }}
+{{ $pages := where $books "Params.price" "ge" 42 }}
+{{ $pages := where $books "Params.price" "gt" 42.67 }}
+{{ $pages := where $books "Params.price" "le" 42 }}
+{{ $pages := where $books "Params.price" "lt" 42.67 }}
+```
+
+## Boolean comparison
+
+Compare the value of the given field to a [`bool`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.fiction" "eq" true }}
+{{ $pages := where $books "Params.fiction" "eq" false }}
+{{ $pages := where $books "Params.fiction" "ne" true }}
+{{ $pages := where $books "Params.fiction" "ne" false }}
+```
+
+## Member comparison
+
+Compare a [`scalar`](g) to a [`slice`](g).
+
- To return a collection of pages where the "color" page parameter is neither "red" nor "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" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "in" $colors }}
+```
+
- Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
++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" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "not in" $colors }}
+```
+
+## Intersection comparison
+
- For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
++Compare a `slice` to a `slice`, returning elements with common values. This is frequently used when comparing taxonomy terms.
+
- To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor":
++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" }}
+
+{{ $genres := slice "suspense" "romance" }}
+{{ $pages := where $books "Params.genres" "intersect" $genres }}
+```
+
+## Regular expression comparison
+
- > Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
++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` }}
+```
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+> [!note]
- For example, to return a collection of pages that were created before the current year:
++> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice.
+
+## Date comparison
+
+### Predefined dates
+
+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.
+
- To return a collection of future events:
++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) }}
+{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
+```
+
+### Custom dates
+
+With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
+
+> [!note]
+> Using TOML for pages with custom front matter dates enables precise date comparisons.
+
+With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons.
+
+In the TOML example below, note that the event date is not quoted.
+
+```text {file="content/events/2024-user-conference.md"}
++++
+title = '2024 User Conference"
+eventDate = 2024-04-01
++++
+```
+
- 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:
++To return a slice of future events:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
+```
+
- To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`:
++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" }}
+{{ $futureEvents := slice }}
+{{ range $events }}
+ {{ if gt (time.AsTime .Params.eventDate) now }}
+ {{ $futureEvents = $futureEvents | append . }}
+ {{ end }}
+{{ end }}
+```
+
+## Nil comparison
+
- 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 present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
- 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.
++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 }}
+```
+
+In both examples above, note that `nil` is not quoted.
+
+## Nested comparison
+
+These are equivalent:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
+{{ $pages = where $pages "Params.level" "eq" "beginner" }}
+```
+
+```go-html-template
+{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
+```
+
+## Portable section comparison
+
+Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
+```
+
+With this construct, a theme author can instruct users to specify their main sections in the site configuration:
+
+{{< code-toggle file=hugo >}}
+mainSections = ['blog','galleries']
+{{< /code-toggle >}}
+
+If `mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
+
+## Boolean/undefined comparison
+
+Consider this site content:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md <-- front matter: exclude = false
+│ ├── post-2.md <-- front matter: exclude = true
+│ └── post-3.md <-- front matter: exclude not defined
+└── _index.md
+```
+
+The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result.
+
+### Equality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+</ul>
+```
+
+### Inequality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+To exclude a page with an undefined field from a boolean _inequality_ test:
+
++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:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 2</a></li>
+</ul>
+```
+
+[`collections.Complement`]: /functions/collections/complement/
+[`date`]: /methods/page/date/
+[`lastmod`]: /methods/page/lastmod/
+[`MainSections`]: /methods/site/mainsections/
+[`time.Time`]: https://pkg.go.dev/time#Time
--- /dev/null
- description: Use these functions to work with arrays, slices, maps, and page collections.
+---
+title: Collections functions
+linkTitle: collections
++description: Use these functions to manipulate and query maps, slices, and strings.
+categories: []
+keywords: []
+---
--- /dev/null
- 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.
+---
+title: css.Quoted
+description: Returns the given string, setting its data type to indicate that it must be quoted when used in CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: css.QuotedString
+ signatures: [css.Quoted STRING]
+---
+
+<!-- Added in v0.111.0 -->
+
+> [!note]
+> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
+
++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:
+
+```scss {file="assets/sass/main.scss"}
+@use "hugo:vars" as h;
+
+ol li::after {
+ content: h.$ol-li-after;
+}
+
+ul li::after {
+ content: h.$ul-li-after;
+}
+```
+
+```go-html-template {file="layouts/_partials/css.html"}
+{{ $vars := dict
+ "ol_li_after" ("6" | css.Quoted )
+ "ul_li_after" ("7" | css.Quoted )
+}}
+
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" $vars
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+The Sass code is transpiled to:
+
+```css {file="public/css/main.css"}
+ol li::after {
+ content: "6";
+}
+
+ul li::after {
+ content: "7";
+}
+```
+
+[`css.Sass`]: /functions/css/sass/
+[`vars`]: /functions/css/sass/#vars
--- /dev/null
- {{< new-in 0.128.0 />}}
-
+---
+title: css.Sass
+description: Transpiles Sass to CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [toCSS]
+ returnType: resource.Resource
+ signatures: ['css.Sass [OPTIONS] RESOURCE']
+---
+
- 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.
+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
+
+enableSourceMap
+: (`bool`) Whether to generate a source map. Default is `false`.
+
+includePaths
+: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
+
+outputStyle
+: (`string`) The output style of the resulting CSS. With LibSass, one of `nested` (default), `expanded`, `compact`, or `compressed`. With Dart Sass, either `expanded` (default) or `compressed`.
+
+precision
+: (`int`) The precision of floating point math. Applicable to LibSass. Default is `8`.
+
+silenceDeprecations
+: {{< new-in 0.139.0 />}}
+: (`slice`) A slice of deprecation IDs to silence. IDs are enclosed in brackets within Dart Sass warning messages (e.g., `import` in `WARN Dart Sass: DEPRECATED [import]`). Applicable to Dart Sass. Default is `false`.
+
+silenceDependencyDeprecations
+: {{< new-in 0.146.0 />}}
+: (`bool`) Whether to silence deprecation warnings from dependencies, where a dependency is considered any file transitively imported through a load path. This does not apply to `@warn` or `@debug` rules.Default is `false`.
+
+sourceMapIncludeSources
+: (`bool`) Whether to embed sources in the generated source map. Applicable to Dart Sass. Default is `false`.
+
+targetPath
+: (`string`) The publish path for the transformed resource, relative to the[`publishDir`][]. If unset, the target path defaults to the asset's original path with a `.css` extension.
+
+transpiler
+: (`string`) The transpiler to use, either `libsass` or `dartsass`. Hugo's extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass). Default is `libsass`.
+
++ > [!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/).
+
+ ```scss
+ // LibSass
+ @import "hugo:vars";
+
+ // Dart Sass
+ @use "hugo:vars" as v;
+ ```
+
- 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].
++ 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
+
+```go-html-template {copy=true}
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" site.Params.styles
+ "includePaths" (slice "node_modules/bootstrap/scss")
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## 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.
++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.
+
+### Installation overview
+
+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.
+
- 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.
++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.
+
+### Installing in a development environment
+
+When you install Dart Sass somewhere in your PATH, Hugo will find it.
+
+OS|Package manager|Site|Installation
+:--|:--|:--|:--
+Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
+macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Windows|Chocolatey|[chocolatey.org]|`choco install sass`
+Windows|Scoop|[scoop.sh]|`scoop install sass`
+
+You may also install [prebuilt binaries][] for Linux, macOS, and Windows. You must install the prebuilt binary outside of your project directory and ensure its path is included in your system's PATH environment variable.
+
+Run `hugo env` to list the active transpilers.
+
+> [!note]
+> If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
+
+### Installing in a production environment
+
- 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.
++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.
+
- - [Cloudflare]
- - [GitHub Pages]
- - [GitLab Pages]
- - [Netlify]
- - [Render]
- - [Vercel]
++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][]
++- [SourceHut][]
++- [Vercel][]
+
+[`css.Quoted`]: /functions/css/quoted/
+[`css.Unquoted`]: /functions/css/unquoted/
+[`publishDir`]: /configuration/all/#publishdir
+[`useResourceCacheWhen`]: /configuration/build/#useresourcecachewhen
+[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
+[LibSass]: https://sass-lang.com/libsass
+[Netlify]: /host-and-deploy/host-on-netlify/
+[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
+[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/
--- /dev/null
- 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.
+---
+title: css.Unquoted
+description: Returns the given string, setting its data type to indicate that it must not be quoted when used in CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: css.UnquotedString
+ signatures: [css.Unquoted STRING]
+---
+
+<!-- Added in v0.111.0 -->
+
+> [!note]
+> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
+
++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:
+
+```scss {file="assets/sass/main.scss"}
+@use "hugo:vars" as h;
+
+h1 {
+ font-size: h.$font-size-h1;
+}
+
+h2 {
+ font-size: h.$font-size-h2;
+}
+```
+
+```go-html-template {file="layouts/_partials/css.html"}
+{{ $vars := dict
+ "font_size_h1" ("72px * 0.500" | css.Unquoted)
+ "font_size_h2" ("72px * 0.375" | css.Unquoted)
+}}
+
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" $vars
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+The Sass rules are transpiled to:
+
+```css {file="public/css/main.css"}
+h1 {
+ font-size: 36px;
+}
+
+h2 {
+ font-size: 27px;
+}
+```
+
+[`css.Sass`]: /functions/css/sass/
+[`vars`]: /functions/css/sass/#vars
--- /dev/null
- {{< new-in 0.123.0 />}}
-
+---
+title: fmt.Warnidf
+description: Log a suppressible WARNING from a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [warnidf]
+ returnType: string
+ signatures: ['fmt.Warnidf ID FORMAT [INPUT]']
+aliases: [/functions/warnidf]
+---
+
+{{% 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.
+
+This template code:
+
+```go-html-template
+{{ warnidf "warning-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+WARN You should consider fixing this.
+You can suppress this warning by adding the following to your site configuration:
+ignoreLogs = ['warning-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["warning-42"]
+{{< /code-toggle >}}
+
+[`warnf`]: /functions/fmt/warnf/
--- /dev/null
+---
+title: and
+description: Returns the first falsy argument. If all arguments are truthy, returns the last argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: [and VALUE...]
+---
+
+{{% 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)
+
+{{ 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" %}}
--- /dev/null
- {{ or 0 1 2 }} → 1
- {{ or false "a" 1 }} → a
- {{ or 0 true "a" }} → true
+---
+title: or
+description: Returns the first truthy argument. If all arguments are falsy, returns the last argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: [or VALUE...]
+---
+
+{{% include "/_common/functions/truthy-falsy.md" %}}
+
++The `or` function evaluates the arguments from left to right, and returns when the result is determined.
++
+```go-html-template
- {{ or false "" 0 }} → 0
- {{ or 0 "" false }} → false
++{{ 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" %}}
--- /dev/null
- {{< new-in 0.123.0 />}}
-
+---
+title: range
+description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [range COLLECTION]
+aliases: [/functions/range]
+---
+
+The collection may be a slice, a map, or an integer.
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ . }} → foo bar baz
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+Within a range block:
+
+- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration
+- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations
+
+## Understanding context
+
+See the [context] section in the introduction to templating.
+
+For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+
+With this contrived example:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ .Title }}
+{{ end }}
+```
+
+Hugo will throw an error:
+
+```text
+can't evaluate field Title in type int
+```
+
+The error occurs because we are trying to use the `.Title` method on a string instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+This template will render the page title three times:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ $.Title }}
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+## Examples
+
+### Slice of scalars
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $v := $s }}
+ <p>{{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $k, $v := $s }}
+ <p>{{ $k }}: {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>0: foo</p>
+<p>1: bar</p>
+<p>2: baz</p>
+```
+
+### Slice of maps
+
+This template code:
+
+```go-html-template
+{{ $m := slice
+ (dict "name" "John" "age" 30)
+ (dict "name" "Will" "age" 28)
+ (dict "name" "Joey" "age" 24)
+}}
+{{ range $m }}
+ <p>{{ .name }} is {{ .age }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>John is 30</p>
+<p>Will is 28</p>
+<p>Joey is 24</p>
+```
+
+### Slice of pages
+
+This template code:
+
+```go-html-template
+{{ range where site.RegularPages "Type" "articles" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<h2><a href="/articles/article-3/">Article 3</a></h2>
+<h2><a href="/articles/article-2/">Article 2</a></h2>
+<h2><a href="/articles/article-1/">Article 1</a></h2>
+```
+
+### Maps
+
+This template code:
+
+```go-html-template
+{{ $m := dict "name" "John" "age" 30 }}
+{{ range $k, $v := $m }}
+ <p>key = {{ $k }} value = {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```go-html-template
+<p>key = age value = 30</p>
+<p>key = name value = John</p>
+```
+
+Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map.
+
+### Integers
+
+Ranging over a positive integer `n` executes the block `n` times, with the context starting at zero and incrementing by one in each iteration.
+
+```go-html-template
+{{ $s := slice }}
+{{ range 1 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0]
+```
+
+```go-html-template
+{{ $s := slice }}
+{{ range 3 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0 1 2]
+```
+
+Ranging over a non-positive integer executes the block zero times.
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`break`]: /functions/go-template/break/
+[`continue`]: /functions/go-template/continue/
+[`else`]: /functions/go-template/else/
+[context]: /templates/introduction/#context
--- /dev/null
- {{ hugo.Generator }} → <meta name="generator" content="Hugo 0.152.2">
+---
+title: hugo.Generator
+description: Renders an HTML meta element identifying the software that generated the site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: template.HTML
+ signatures: [hugo.Generator]
+---
+
+```go-html-template
++{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.155.3">
+```
--- /dev/null
- {{< new-in 0.124.0 />}}
-
+---
+title: hugo.IsMultihost
+description: Reports whether each configured language has a unique base URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultihost]
+---
+
+Site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ baseURL = 'https://de.example.org/'
+ languageCode = 'de-DE'
+ languageName = 'Deutsch'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ baseURL = 'https://en.example.org/'
+ languageCode = 'en-US'
+ languageName = 'English'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultihost }} → true
+```
--- /dev/null
- {{< new-in 0.124.0 />}}
-
+---
+title: hugo.IsMultilingual
+description: Reports whether there are two or more configured languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultilingual]
+---
+
+Site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ languageCode = 'de-DE'
+ languageName = 'Deutsch'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ languageCode = 'en-US'
+ languageName = 'English'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultilingual }} → true
+```
--- /dev/null
- {{ hugo.Version }} → 0.152.2
+---
+title: hugo.Version
+description: Returns the current version of the Hugo binary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: hugo.VersionString
+ signatures: [hugo.Version]
+---
+
+```go-html-template
++{{ hugo.Version }} → 0.155.3
+```
--- /dev/null
- description: Returns an image filter that rotates and flips an image as needed per its EXIF orientation tag.
+---
+title: images.AutoOrient
++description: Returns an image filter that rotates and flips an image as needed per its Exif orientation tag.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.AutoOrient]
+---
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.AutoOrient }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+> [!note]
+> When using with other filters, specify `images.AutoOrient` first.
+
+```go-html-template
+{{ $filters := slice
+ images.AutoOrient
+ (images.Process "resize 200x")
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+{{< img
+ src="images/examples/landscape-exif-orientation-5.jpg"
+ alt="Zion National Park"
+ filter="AutoOrient"
+ filterArgs=""
+ example=true
+>}}
--- /dev/null
- {{< new-in 0.123.0 />}}
-
+---
+title: images.Dither
+description: Returns an image filter that dithers an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: ['images.Dither [OPTIONS]']
+---
+
- : (`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`).
+## Options
+
+colors
++: (`[]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
+
+method
+: (`string`) The dithering method. See the [dithering methods](#dithering-methods) section below for a list of the available methods. Default is `FloydSteinberg`.
+
+serpentine
+: (`bool`) Applicable to error diffusion dithering methods, whether to apply the error diffusion matrix in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`.
+
+strength
+: (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`.
+
+## Usage
+
+Create the options map:
+
+```go-html-template
+{{ $opts := dict
+ "colors" (slice "222222" "808080" "dddddd")
+ "method" "ClusteredDot4x4"
+ "strength" 0.85
+}}
+```
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Dither $opts }}
+```
+
+Or create the filter using the default settings:
+
+```go-html-template
+{{ $filter := images.Dither }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Dithering methods
+
+See the [Go documentation] for descriptions of each of the dithering methods below.
+
+[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables
+
+Error diffusion dithering methods:
+
+- Atkinson
+- Burkes
+- FalseFloydSteinberg
+- FloydSteinberg
+- JarvisJudiceNinke
+- Sierra
+- Sierra2
+- Sierra2_4A
+- Sierra3
+- SierraLite
+- Simple2D
+- StevenPigeon
+- Stucki
+- TwoRowSierra
+
+Ordered dithering methods:
+
+- ClusteredDot4x4
+- ClusteredDot6x6
+- ClusteredDot6x6_2
+- ClusteredDot6x6_3
+- ClusteredDot8x8
+- ClusteredDotDiagonal16x16
+- ClusteredDotDiagonal6x6
+- ClusteredDotDiagonal8x8
+- ClusteredDotDiagonal8x8_2
+- ClusteredDotDiagonal8x8_3
+- ClusteredDotHorizontalLine
+- ClusteredDotSpiral5x5
+- ClusteredDotVerticalLine
+- Horizontal3x5
+- Vertical5x3
+
+## Example
+
+This example uses the default dithering options.
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Dither"
+ filterArgs=""
+ example=true
+>}}
+
+## Recommendations
+
+Regardless of dithering method, do both of the following to obtain the best results:
+
+1. Scale the image _before_ dithering
+1. Output the image to a lossless format such as GIF or PNG
+
+The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.
+
+```go-html-template
+{{ with resources.Get "original.jpg" }}
+ {{ $opts := dict
+ "method" "ClusteredDotSpiral5x5"
+ "colors" (first 3 .Colors)
+ }}
+ {{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Dither $opts)
+ (images.Process "png")
+ }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+For best results, if the dithering palette is grayscale, convert the image to grayscale before dithering.
+
+```go-html-template
+{{ $opts := dict "colors" (slice "222" "808080" "ddd") }}
+{{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Grayscale)
+ (images.Dither $opts)
+ (images.Process "png")
+}}
+{{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+The example above:
+
+1. Resizes the image to be 800 px wide
+1. Converts the image to grayscale
+1. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+1. Converts the image to the PNG format
--- /dev/null
- keywords: []
+---
+title: images.Filter
+description: Applies one or more image filters to the given image resource.
+categories: []
++keywords: [filter]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.ImageResource
+ signatures: [images.Filter FILTERS... IMAGE]
+---
+
+Apply one or more [image filters](#image-filters) to the given image.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`Filter`] method on a `Resource` object.
+
+[`Filter`]: /methods/resource/filter/
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
+
+{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
--- /dev/null
- description: Returns an image filter that processes the given image using the given specification.
+---
+title: images.Process
- keywords: []
++description: Returns an image filter that processes an image according to the given processing specification.
+categories: []
- signatures: [images.Process SPEC]
++keywords: [process]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
- 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).
-
- ```go-html-template
- {{ $filter := images.Process "resize 300x" }}
- ```
-
- 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).
-
- ```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).
++ signatures: [images.Process SPECIFICATION]
+---
+
- {{ $filter := images.Process "crop 200x200 center" }}
++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
- 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" }}
- ```
++{{ with resources.Get "images/original.jpg" }}
++ {{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
++ {{ with .Filter $filter }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ end }}
++{{ end }}
+```
+
- 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" }}
- ```
++In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
+
- {{ $filter := images.Process "resize 256x q40 webp" }}
++{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Usage
+
+Create a filter:
+
+```go-html-template
- filterArgs="resize 256x q40 webp"
++{{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
++
++[`Filter`]: /methods/resource/filter/
++[`images.Filter`]: /functions/images/filter
++[processing specification]: #processing-specification
--- /dev/null
- > To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
+---
+title: lang.Translate
+description: Translates a string using the translation tables in the i18n directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [T, i18n]
+ returnType: string
+ signatures: ['lang.Translate KEY [CONTEXT]']
+aliases: [/functions/i18n]
+---
+
+The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
+
+If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`][].
+
+If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
+
+> [!note]
- i18n/en-US.toml
++> 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.
+
+## Translation tables
+
+Create translation tables in the `i18n` directory, naming each file according to [RFC 5646][]. Translation tables may be JSON, TOML, or YAML. For example:
+
+```text
+i18n/en.toml
- The base name must match the [language key][] as defined in your site configuration.
++i18n/pt-BR.toml
+```
+
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
++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:
+
+```text
+i18n/art-x-hugolang.toml
+i18n/hugolang.toml
+```
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Simple translations
+
+Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+privacy = 'privacy'
+security = 'security'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+privacy = 'prywatność'
+security = 'bezpieczeństwo'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "privacy" }} → privacy
+{{ T "security" }} → security
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "privacy" }} → prywatność
+{{ T "security" }} → bezpieczeństwo
+```
+
+## Translations with pluralization
+
+Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The Unicode [CLDR Plural Rules chart][CLDR] describes the pluralization categories for each language.
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+[day]
+one = 'day'
+other = 'days'
+
+[day_with_count]
+one = '{{ . }} day'
+other = '{{ . }} days'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+[day]
+one = 'miesiąc'
+few = 'miesiące'
+many = 'miesięcy'
+other = 'miesiąca'
+
+[day_with_count]
+one = '{{ . }} miesiąc'
+few = '{{ . }} miesiące'
+many = '{{ . }} miesięcy'
+other = '{{ . }} miesiąca'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "day" 0 }} → days
+{{ T "day" 1 }} → day
+{{ T "day" 2 }} → days
+{{ T "day" 5 }} → days
+
+{{ T "day_with_count" 0 }} → 0 days
+{{ T "day_with_count" 1 }} → 1 day
+{{ T "day_with_count" 2 }} → 2 days
+{{ T "day_with_count" 5 }} → 5 days
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "day" 0 }} → miesięcy
+{{ T "day" 1 }} → miesiąc
+{{ T "day" 2 }} → miesiące
+{{ T "day" 5 }} → miesięcy
+
+{{ T "day_with_count" 0 }} → 0 miesięcy
+{{ T "day_with_count" 1 }} → 1 miesiąc
+{{ T "day_with_count" 2 }} → 2 miesiące
+{{ T "day_with_count" 5 }} → 5 miesięcy
+```
+
+In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization.
+
+Translation table:
+
+{{< code-toggle file=i18n/en >}}
+[age]
+one = '{{ .name }} is {{ .count }} year old.'
+other = '{{ .name }} is {{ .count }} years old.'
+{{< /code-toggle >}}
+
+Template code:
+
+```go-html-template
+{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
+{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
+```
+
+> [!note]
+> Translation tables may contain both simple translations and translations with pluralization.
+
+## Reserved keys
+
+Hugo uses the [go-i18n][] package to look up values in translation tables. This package reserves the following keys for internal use:
+
+id
+: (`string`) Uniquely identifies the message.
+
+description
+: (`string`) Describes the message to give additional context to translators that may be relevant for translation.
+
+hash
+: (`string`) Uniquely identifies the content of the message that this message was translated from.
+
+leftdelim
+: (`string`) The left Go template delimiter.
+
+rightdelim
+: (`string`) The right Go template delimiter.
+
+zero
+: (`string`) The content of the message for the [CLDR][] plural form "zero".
+
+one
+: (`string`) The content of the message for the [CLDR][] plural form "one".
+
+two
+: (`string`) The content of the message for the [CLDR][] plural form "two".
+
+few
+: (`string`) The content of the message for the [CLDR][] plural form "few".
+
+many
+: (`string`) The content of the message for the [CLDR][] plural form "many".
+
+other
+: (`string`) The content of the message for the [CLDR][] plural form "other".
+
+If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
+
+{{< code-toggle file=i18n/es >}}
+_description = 'descripción'
+_few = 'pocos'
+_many = 'muchos'
+_one = 'uno'
+_other = 'otro'
+_two = 'dos'
+_zero = 'cero'
+{{< /code-toggle >}}
+
+Then in your templates:
+
+```go-html-template
+{{ T "_description" }} → descripción
+{{ T "_few" }} → pocos
+{{ T "_many" }} → muchos
+{{ T "_one" }} → uno
+{{ T "_two" }} → dos
+{{ T "_zero" }} → cero
+{{ T "_other" }} → otro
+```
+
+[`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 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- description: Unmarshals the given resource into an OpenAPI 3 document.
+---
+title: openapi3.Unmarshal
- signatures: ['openapi3.Unmarshal RESOURCE']
++description: Unmarshals the given resource into an OpenAPI 3 Description.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: openapi3.OpenAPIDocument
- Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g).
++ signatures: ['openapi3.Unmarshal RESOURCE [OPTIONS]']
+---
+
- [OpenAPI]: https://www.openapis.org/
++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).
+
- For example, to work with a remote [OpenAPI] definition:
++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.
+
- ```go-html-template
- {{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }}
++## Options
+
- {{ with try (resources.GetRemote $url) }}
++{{< 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 := "" }}
- {{ $api = . | openapi3.Unmarshal }}
++{{ $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 }}
- To inspect the data structure:
++ {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
- ```go-html-template
++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.
++
++### 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`.
+
- ```go-html-template
++## 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}
+<pre>{{ debug.Dump $api }}</pre>
+```
+
+To list the GET and POST operations for each of the API paths:
+
- > [!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.
-
++```go-html-template {copy=true}
+{{ range $path, $details := $api.Paths.Map }}
+ <p>{{ $path }}</p>
+ <dl>
+ {{ with $details.Get }}
+ <dt>GET</dt>
+ <dd>{{ .Summary }}</dd>
+ {{ end }}
+ {{ with $details.Post }}
+ <dt>POST</dt>
+ <dd>{{ .Summary }}</dd>
+ {{ end }}
+ </dl>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>/pets</p>
+<dl>
+ <dt>GET</dt>
+ <dd>List all pets</dd>
+ <dt>POST</dt>
+ <dd>Create a pet</dd>
+</dl>
+<p>/pets/{petId}</p>
+<dl>
+ <dt>GET</dt>
+ <dd>Info for a specific pet</dd>
+</dl>
+```
++
++[`resources.GetRemote`]: /functions/resources/getremote/#options
++[OpenAPI Document]: https://swagger.io/specification/#openapi-document
++[OpenAPI Description]: https://swagger.io/specification/#openapi-description
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
- "build_date": "2025-07-08T13:12:19-07:00",
- "hugo_version": "0.152.2",
- "last_modified": "2025-07-07T22:09:13-07:00"
+---
+title: resources.FromString
+description: Returns a resource created from a string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.FromString TARGETPATH STRING]
+---
+
+The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
+
+Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
+
+```json
+{
++ "build_date": "2026-01-11T11:27:49-08:00",
++ "hugo_version": "0.155.3",
++ "last_modified": "2026-01-11T11:27:59-08:00"
+}
+```
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ {{ $r := resources.FromString "site.json" $json }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+The example above:
+
+1. Creates a map with the relevant key-value pairs using the [`dict`] function
+1. Encodes the map as a JSON string using the [`jsonify`] function
+1. Creates a resource from the JSON string using the `resources.FromString` function
+1. Publishes the file to the root of the `public` directory using the resource's `.Publish` method
+
+Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $string := `
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ `
+ }}
+ {{ $r := resources.FromString "" $string }}
+ {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+[`dict`]: /functions/collections/dictionary/
+[`jsonify`]: /functions/encoding/jsonify/
+[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
--- /dev/null
- Hugo determines a match using a case-insensitive [glob](g) pattern.
+---
+title: resources.GetMatch
+description: Returns the first global resource from paths matching the given glob pattern, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.GetMatch PATTERN]
+---
+
+```go-html-template
+{{ with resources.GetMatch "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+> [!note]
+> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+>
+> For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
+
++Hugo determines a match using a case-insensitive [glob pattern](g).
+
+{{% include "/_common/glob-patterns.md" %}}
+
+[`Resources.GetMatch`]: /methods/page/resources/
--- /dev/null
- {{< new-in 0.125.0 />}}
-
+---
+title: strings.Diff
+description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [strings.Diff OLDNAME OLD NEWNAME NEW]
+---
+
+Use `strings.Diff` to compare two strings and render a highlighted diff:
+
+```go-html-template
+{{ $want := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 42.</p>
+`}}
+
+{{ $got := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 13.</p>
+`}}
+
+{{ $diff := strings.Diff "want" $want "got" $got }}
+{{ transform.Highlight $diff "diff" }}
+```
+
+Rendered:
+
+
--- /dev/null
--- /dev/null
++---
++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" . }}
++ <p>This content is passed to the partial.</p>
++{{ end }}
++```
++
++Inside the partial, call `templates.Inner` to render the captured block.
++
++```go-html-template {file="layouts/_partials/components/card.html"}
++<div class="card-frame">
++ {{ templates.Inner . }}
++</div>
++```
++
++## 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"}
++<ul class="styled-list">
++ {{ range .items }}
++ <li>
++ {{ templates.Inner . }}
++ </li>
++ {{ end }}
++</ul>
++```
++
++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/
--- /dev/null
+---
+title: transform.ToMath
+description: Renders mathematical equations and expressions written in the LaTeX markup language.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: template.HTML
+ signatures: ['transform.ToMath INPUT [OPTIONS]']
+aliases: [/functions/tomath]
+---
+
+{{< new-in 0.132.0 />}}
+
+Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
+
+```go-html-template
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
+```
+
+> [!note]
+> By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
+>
+> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
+
+```go-html-template
+{{ $opts := dict "output" "htmlAndMathml" }}
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
+```
+
+## Options
+
+Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
+
+displayMode
+: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`.
+
+errorColor
+: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
+
+fleqn
+: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`.
+
+macros
+: (`map`) A map of macros to be used in the math expression. Default is `{}`.
+
+ ```go-html-template
+ {{ $macros := dict
+ "\\addBar" "\\bar{#1}"
+ "\\bold" "\\mathbf{#1}"
+ }}
+ {{ $opts := dict "macros" $macros }}
+ {{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
+ ```
+
+minRuleThickness
+: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
+
+output
+: (`string`) Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
+
+ With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
+
+ ```html
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ ```
+
+strict
+: {{< new-in 0.147.6 />}}
+: (`string`) Controls how KaTeX handles LaTeX features that offer convenience but aren't officially supported, one of `error`, `ignore`, or `warn`. Default is `error`.
+
+ - `error`: Throws an error when convenient, unsupported LaTeX features are encountered.
+ - `ignore`: Allows convenient, unsupported LaTeX features without any feedback.
+ - `warn`: {{< new-in 0.147.7 />}} Emits a warning when convenient, unsupported LaTeX features are encountered.
+
+ The `newLineInDisplayMode` error code, which flags the use of `\\` or `\newline` in display mode outside an array or tabular environment, is intentionally designed not to throw an error, despite this behavior being questionable.
+
+throwOnError
+: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
+
+## Error handling
+
+There are three ways to handle errors:
+
+1. Let KaTeX throw an error and fail the build. This is the default behavior.
+1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
+1. Handle the error in your template.
+
+The example below demonstrates error handing within a template.
+
+## Example
+
+Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
+
+Step 1
+: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+
+[passthrough extension]: /configuration/markup/#passthrough
+
+ {{< code-toggle file=hugo copy=true >}}
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+ {{< /code-toggle >}}
+
+ > [!note]
+ > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+
+Step 2
+: Create a [passthrough render hook][] to capture and render the LaTeX markup.4
+
+[passthrough render hook]: /render-hooks/passthrough/
+
+ ```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
+ {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+ {{- with try (transform.ToMath .Inner $opts) }}
+ {{- with .Err }}
+ {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+ {{- else }}
+ {{- .Value }}
+ {{- $.Page.Store.Set "hasMath" true }}
+ {{- end }}
+ {{- end -}}
+ ```
+
+Step 3
+: In your base template, conditionally include the KaTeX CSS within the head element.
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ {{ end }}
+ </head>
+ ```
+
+ 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 }}
++ > <link rel="stylesheet" href="...">
++ > {{ end }}
++ > ```
++
+Step 4
+: Add some mathematical markup to your content, then test.
+
+ ```text {file="content/example.md"}
+ This is an inline \(a^*=x-b^*\) equation.
+
+ These are block equations:
+
+ \[a^*=x-b^*\]
+
+ $$a^*=x-b^*$$
+ ```
+
+## Chemistry
+
+{{< new-in 0.144.0 />}}
+
+You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package.
+
+```text
+$$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
+[mhchem]: https://mhchem.github.io/MathJax-mhchem/
+[rendering options]: https://katex.org/docs/options.html
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
- minVersion: v0.128.0
+---
+title: Quick start
+description: Create a Hugo site in minutes.
+categories: []
+keywords: []
+params:
++ minVersion: v0.146.0
+weight: 10
+aliases: [/quickstart/,/overview/quickstart/]
+---
+
+In this tutorial you will:
+
+1. Create a site
+1. Add content
+1. Configure the site
+1. Publish the site
+
+## Prerequisites
+
+Before you begin this tutorial you must:
+
+1. [Install Hugo] (extended or extended/deploy edition, {{% param "minVersion" %}} or later)
+1. [Install Git]
+
+You must also be comfortable working from the command line.
+
+## Create a site
+
+### Commands
+
+> [!note]
+> **If you are a Windows user:**
+>
+> - Do not use the Command Prompt
+> - Do not use Windows PowerShell
+> - Run these commands from [PowerShell] or a Linux terminal such as WSL or Git > Bash
+>
+> PowerShell and Windows PowerShell [are different applications].
+
+Verify that you have installed Hugo {{% param "minVersion" %}} or later.
+
+```text
+hugo version
+```
+
+Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command.
+
+```text
+hugo new site quickstart
+cd quickstart
+git init
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+echo "theme = 'ananke'" >> hugo.toml
+hugo server
+```
+
+View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
+
+### Explanation of commands
+
+Create the [site skeleton] for your project in the `quickstart` directory.
+
+```text
+hugo new site quickstart
+```
+
+Change the current directory to the root of your project.
+
+```text
+cd quickstart
+```
+
+Initialize an empty Git repository in the current directory.
+
+```text
+git init
+```
+
+Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule].
+
+```text
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+```
+
+Append a line to the site configuration file, indicating the current theme.
+
+```text
+echo "theme = 'ananke'" >> hugo.toml
+```
+
+Start Hugo's development server to view the site.
+
+```text
+hugo server
+```
+
+Press `Ctrl + C` to stop Hugo's development server.
+
+## Add content
+
+Add a new page to your site.
+
+```text
+hugo new content content/posts/my-first-post.md
+```
+
+Hugo created the file in the `content/posts` directory. Open the file with your editor.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+```
+
+Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content].
+
+Add some [Markdown] to the body of the post, but do not change the `draft` value.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+## Introduction
+
+This is **bold** text, and this is *emphasized* text.
+
+Visit the [Hugo](https://gohugo.io) website!
+```
+
+Save the file, then start Hugo's development server to view the site. You can run either of the following commands to include draft content.
+
+```text
+hugo server --buildDrafts
+hugo server -D
+```
+
+View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+
+When satisfied with your new content, set the front matter `draft` parameter to `false`.
+
+> [!note]
+> Hugo's rendering engine conforms to the CommonMark [specification] for Markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation.
+
+## Configure the site
+
+With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project.
+
+```text
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'My New Hugo Site'
+theme = 'ananke'
+```
+
+Make the following changes:
+
+1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above.
+1. Set the `languageCode` to your language and region.
+1. Set the `title` for your production site.
+
+Start Hugo's development server to see your changes, remembering to include draft content.
+
+```text
+hugo server -D
+```
+
+> [!note]
+> Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
+>
+> [The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
+
+## Publish the site
+
+In this step you will _publish_ your site, but you will not _deploy_ it.
+
+When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files.
+
+When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple.
+
+```text
+hugo
+```
+
+To learn how to _deploy_ your site, see the [host and deploy] section.
+
+## Ask for help
+
+Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+## Other resources
+
+For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page.
+
+[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
+[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
+[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
+[site skeleton]: /getting-started/directory-structure/#site-skeleton
+[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
+[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content
+[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content
+[forum]: https://discourse.gohugo.io/
+[front matter]: /content-management/front-matter/
+[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[host and deploy]: /host-and-deploy/
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Install Hugo]: /installation/
+[live testing tool]: https://spec.commonmark.org/dingus/
+[Markdown]: https://daringfireball.net/projects/markdown
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
+[site configuration]: /configuration/
+[specification]: https://spec.commonmark.org/
+[The New Dynamic]: https://www.thenewdynamic.com/
--- /dev/null
- hugo v0.152.2-6abdacad3f3fe944ea42177844469139e81feda6+extended linux/amd64 BuildDate=2025-10-24T15:31:49Z VendorInfo=gohugoio
+---
+title: Basic usage
+description: Use the command-line interface (CLI) to perform basic tasks.
+categories: []
+keywords: []
+weight: 20
+aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
+---
+
+## Test your installation
+
+After [installing] Hugo, test your installation by running:
+
+```sh
+hugo version
+```
+
+You should see something like:
+
+```text
- {{< new-in 0.123.0 />}}
-
++hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
+```
+
+## Display available commands
+
+To see a list of the available commands and flags:
+
+```sh
+hugo help
+```
+
+To get help with a subcommand, use the `--help` flag. For example:
+
+```sh
+hugo server --help
+```
+
+## Build your site
+
+To build your site, `cd` into your project directory and run:
+
+```sh
+hugo
+```
+
+The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
+
+> [!note]
+> Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
+>
+> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
+
+## Draft, future, and expired content
+
+Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
+
+- The `draft` value is `true`
+- The `date` is in the future
+- The `publishDate` is in the future
+- The `expiryDate` is in the past
+
- 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.
+> [!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.
+
+You can override the default behavior when running `hugo` or `hugo server` with command line flags:
+
+```sh
+hugo --buildDrafts # or -D
+hugo --buildExpired # or -E
+hugo --buildFuture # or -F
+```
+
+Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your site. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
+>
+> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+## Develop and test your site
+
+To view your site while developing layouts or creating content, `cd` into your project directory and run:
+
+```sh
+hugo server
+```
+
+The [`hugo server`] command builds your site and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
+
+```text
+Web Server is available at http://localhost:1313/
+```
+
+While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
+
+Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
+
+### LiveReload
+
+While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.
+
+### Automatic redirection
+
+When editing content, if you want your browser to automatically redirect to the page you last modified, run:
+
+```sh
+hugo server --navigateToChanged
+```
+
+## Deploy your site
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+When you are ready to deploy your site, run:
+
+```sh
+hugo
+```
+
+This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
+
+```text
+public/
+├── categories/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── posts/
+│ ├── my-first-post/
+│ │ └── index.html
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── tags/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── index.html
+├── index.xml <-- RSS feed for the site
+└── sitemap.xml
+```
+
+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.
+
- [AWS Amplify]: https://aws.amazon.com/amplify/
++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.
+
+[`--destination`]: /commands/hugo/#options
+[`cascade`]: /content-management/front-matter/#cascade
+[`hugo server`]: /commands/hugo_server/
+[`hugo`]: /commands/hugo/
+[`publishDir`]: /configuration/all/#publishdir
- [CloudCannon]: https://cloudcannon.com/
- [Cloudflare Pages]: https://pages.cloudflare.com/
+[build options]: /content-management/build-options/
- [GitHub Pages]: https://pages.github.com/
- [GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
+[front matter]: /content-management/front-matter/
- [Netlify]: https://www.netlify.com/
+[host and deploy]: /host-and-deploy/
+[installing]: /installation/
+[LiveReload]: https://github.com/livereload/livereload-js
--- /dev/null
- DART_SASS_VERSION: 1.96.0
- GO_VERSION: 1.25.5
- HUGO_VERSION: 0.152.2
+---
+title: Host on AWS Amplify
+description: Host your site on AWS Amplify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-aws-amplify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://aws.amazon.com/resources/create-account/) an AWS account
+1. [Log in](https://console.aws.amazon.com/) to your AWS account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
+
+Step 1
+: Create a file named `amplify.yml` in the root of your project.
+
+ ```sh
+ touch amplify.yml
+ ```
+
+Step 2
+: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed.
+
+ ```yaml {file="amplify.yml" copy=true}
+ version: 1
+ env:
+ variables:
+ # Application versions
++ DART_SASS_VERSION: 1.97.3
++ GO_VERSION: 1.25.6
++ HUGO_VERSION: 0.155.3
+ # Time zone
+ TZ: Europe/Oslo
+ # Cache
+ HUGO_CACHEDIR: ${PWD}/.hugo
+ NPM_CONFIG_CACHE: ${PWD}/.npm
+ frontend:
+ phases:
+ preBuild:
+ commands:
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ - echo "Installing Go ${GO_VERSION}..."
+ - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ - rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+
+ # Install Node.js dependencies
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
+ # Configure Git
+ - echo "Configuring Git..."
+ - git config core.quotepath false
+ build:
+ commands:
+ - echo "Building site..."
+ - hugo --gc --minify
+ artifacts:
+ baseDirectory: public
+ files:
+ - '**/*'
+ cache:
+ paths:
+ - ${HUGO_CACHEDIR}/**/*
+ - ${NPM_CONFIG_CACHE}/**/*
+ ```
+
+Step 3
+: Commit and push the change to your GitHub repository.
+
+ ```sh
+ git add -A
+ git commit -m "Create amplify.yml"
+ git push
+ ```
+
+Step 4
+: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
+
+Step 5
+: Choose a source code provider, then press the **Next** button.
+
+ 
+
+Step 6
+: Authorize AWS Amplify to access your GitHub account.
+
+ 
+
+Step 7
+: Select your personal account or relevant organization.
+
+ 
+
+Step 8
+: Authorize access to one or more repositories.
+
+ 
+
+Step 9
+: Select a repository and branch, then press the **Next** button.
+
+ 
+
+Step 10
+: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page.
+
+Step 11
+: On the "Review" page, scroll to the bottom then press the **Save and deploy** button.
+
+Step 12
+: When your site has finished deploying, press the **Visit deployed URL** button to view your published site.
+
+ 
+
+[Amplify Console]: https://console.aws.amazon.com/amplify/apps
--- /dev/null
- DART_SASS_VERSION=1.96.0
- GO_VERSION=1.25.5
- HUGO_VERSION=0.152.2
- NODE_VERSION=24.12.0
+---
+title: Host on Cloudflare
+description: Host your site on Cloudflare.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account
+1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `wrangler.toml` file in the root of your project.
+
+ ```toml {file="wrangler.toml" copy=true}
+ name = "hosting-cloudflare-worker"
+ compatibility_date = "2025-07-31"
+
+ [build]
+ command = "chmod a+x build.sh && ./build.sh"
+
+ [assets]
+ directory = "./public"
+ not_found_handling = "404-page"
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Cloudflare Worker.
+ #
+ # The Cloudflare Worker automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
++ 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
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo --gc --minify
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu.
+
+ 
+
+Step 5
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 6
+: Connect to GitHub.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Cloudflare Workers and Pages application.
+
+ 
+
+Step 8
+: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 9
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 10
+: Select the repository to import.
+
+ 
+
+Step 11
+: On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button.
+
+ 
+
+Step 12
+: Wait for the site to build and deploy, then visit your site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site.
--- /dev/null
- DART_SASS_VERSION: 1.96.0
- GO_VERSION: 1.25.5
- HUGO_VERSION: 0.152.2
- NODE_VERSION: 24.12.0
+---
+title: Host on GitHub Pages
+description: Host your site on GitHub Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-github/]
+---
+
+## Types of sites
+
+There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
+
+> [!note]
+> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
+
+## Procedure
+
+Step 1
+: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
+
+ 
+
+ Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
+
+ 
+
+Step 2
+: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [caches.images]
+ dir = ":cacheDir/images"
+ {{< /code-toggle >}}
+
+ See [configure file caches] for more information.
+
+Step 3
+: Create a file named `hugo.yaml` in a directory named `.github/workflows`.
+
+ ```text
+ mkdir -p .github/workflows
+ touch .github/workflows/hugo.yaml
+ ```
+
+Step 4
+: Copy and paste the YAML below into the file you created.
+
+ ```yaml {file=".github/workflows/hugo.yaml" copy=true}
+ name: Build and deploy
+ on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+ defaults:
+ run:
+ shell: bash
+ jobs:
+ build:
+ runs-on: ubuntu-latest
+ env:
- uses: actions/checkout@v5
++ 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/setup-go@v5
++ uses: actions/checkout@v6
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Setup Go
- uses: actions/setup-node@v4
++ uses: actions/setup-go@v6
+ with:
+ go-version: ${{ env.GO_VERSION }}
+ cache: false
+ - name: Setup Node.js
- uses: actions/cache/restore@v4
++ uses: actions/setup-node@v6
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Create directory for user-specific executable files
+ run: |
+ mkdir -p "${HOME}/.local"
+ - name: Install Dart Sass
+ run: |
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
+ - name: Install Hugo
+ run: |
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
+ - name: Verify installations
+ run: |
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ - name: Install Node.js dependencies
+ run: |
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
+ - name: Configure Git
+ run: |
+ git config core.quotepath false
+ - name: Cache restore
+ id: cache-restore
- uses: actions/cache/save@v4
++ uses: actions/cache/restore@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: hugo-${{ github.run_id }}
+ restore-keys:
+ hugo-
+ - name: Build the site
+ run: |
+ hugo \
+ --gc \
+ --minify \
+ --baseURL "${{ steps.pages.outputs.base_url }}/" \
+ --cacheDir "${{ runner.temp }}/hugo_cache"
+ - name: Cache save
+ id: cache-save
++ uses: actions/cache/save@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./public
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+Step 5
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 6
+: From GitHub's main menu, choose **Actions**. You will see something like this:
+
+ 
+
+Step 7
+: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
+
+ 
+
+Step 8
+: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site.
+
+## Customize the workflow
+
+The example workflow above includes this step, which typically takes 10‑15 seconds:
+
+```yaml
+- name: Install Dart Sass
+ run: sudo snap install dart-sass
+```
+
+You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
+
+## Other resources
+
+- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
+- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
+- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
+
+[`cacheDir`]: /configuration/all/#cachedir
+[configure file caches]: /configuration/caches/
+[Dart Sass]: /functions/css/sass/#dart-sass
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
--- /dev/null
- DART_SASS_VERSION: 1.96.0
- HUGO_VERSION: 0.152.2
- NODE_VERSION: 24.12.0
+---
+title: Host on GitLab Pages
+description: Host your site on GitLab Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-gitlab/]
+---
+
+## Assumptions
+
+- Working familiarity with Git for version control
+- Completion of the Hugo [Quick Start]
+- A [GitLab account](https://gitlab.com/users/sign_in)
+- A Hugo website on your local machine that you are ready to publish
+
+## BaseURL
+
+The `baseURL` in your [site configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
+
+## Configure GitLab CI/CD
+
+Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+
+```yaml {file=".gitlab-ci.yml" copy=true}
+variables:
+ # Application versions
- name: golang:1.25.5-bookworm
++ DART_SASS_VERSION: 1.97.3
++ HUGO_VERSION: 0.155.3
++ NODE_VERSION: 24.13.0
+ # Git
+ GIT_DEPTH: 0
+ GIT_STRATEGY: clone
+ GIT_SUBMODULE_STRATEGY: recursive
+ # Time zone
+ TZ: Europe/Oslo
+
+image:
++ name: golang:1.25.6-bookworm
+
+pages:
+ stage: deploy
+ script:
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install utilities
+ - echo "Installing utilities..."
+ - apt-get update
+ - apt-get install -y brotli xz-utils zstd
+
+ # Install Dart Sass
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Hugo
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ - echo "Installing Node.js ${NODE_VERSION}..."
+ - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+ - "echo brotli: $(brotli --version)"
+ - "echo xz: $(xz --version)"
+ - "echo zstd: $(zstd --version)"
+
+ # Install Node.js dependencies
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
+ # Configure Git
+ - echo "Configuring Git..."
+ - git config core.quotepath false
+
+ # Build site
+ - echo "Building site..."
+ - hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+
+ # Compress published files
+ - echo "Compressing published files..."
+ - find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
+ - time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
+ - time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## Push your Hugo website to GitLab
+
+Next, create a new repository on GitLab. It is not necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to master branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
+git push -u origin master
+```
+
+## Wait for your page to build
+
+That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
+
+After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
+
+## Next steps
+
+GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
+
+[Quick Start]: /getting-started/quick-start/
--- /dev/null
- DART_SASS_VERSION = "1.96.0"
- GO_VERSION = "1.25.5"
- HUGO_VERSION = "0.152.2"
- NODE_VERSION = "24.12.0"
+---
+title: Host on Netlify
+description: Host your site on Netlify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-netlify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://app.netlify.com/signup) a Netlify account
+1. [Log in](https://app.netlify.com/login) to your Netlify account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+<!-- Using "text" as the code block language because "toml" looks terrible. -->
+
+Step 1
+: Create a `netlify.toml` file in the root of your project.
+
+ ```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]
+ publish = "public"
+ command = """\
+ git config core.quotepath false && \
+ hugo --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+ If your site requires Dart Sass to transpile Sass to CSS, set the `DART_SASS_VERSION` and include the Dart Sass installation in the build step.
+
+ ```text {file="netlify.toml" copy=true}
+ [build.environment]
++ 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]
+ publish = "public"
+ command = """\
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ export PATH="${HOME}/.local/dart-sass:${PATH}" && \
+ git config core.quotepath false && \
+ hugo --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+Step 2
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 3
+: In the upper right corner of the Netlify dashboard, press the **Add new project** button and select “Import an existing project".
+
+ 
+
+Step 4
+: Connect to GitHub.
+
+ 
+
+Step 5
+: Press the "Authorize Netlify" button to allow the Netlify application to access your GitHub account.
+
+ 
+
+Step 6
+: Press the **Configure Netlify on GitHub** button.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Netlify application.
+
+ 
+
+Step 8
+: Authorize the Netlify application to access all repositories or only select repositories, then press the Install button.
+
+ 
+
+Your browser will be redirected to the Netlify dashboard.
+
+Step 9
+: Click on the name of the repository you wish to import.
+
+ 
+
+Step 10
+: On the "Review configuration" page, enter a project name, leave the settings at their default values, then press the **Deploy** button.
+
+ 
+
+ 
+
+Step 11
+: When the deployment completes, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Netlify will rebuild and deploy your site.
--- /dev/null
- value: 1.96.0
+---
+title: Host on Render
+description: Host your site on Render.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-render/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dashboard.render.com/register) a Render account
+1. [Log in](https://dashboard.render.com/login) to your Render account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a [Render Blueprint][] in the root of your project.
+
+ ``` {file="render.yaml" copy=true}
+ services:
+ - type: web
+ name: hosting-render
+ repo: https://github.com/jmooring/hosting-render
+ runtime: static
+ buildCommand: chmod a+x build.sh && ./build.sh
+ staticPublishPath: public
+ envVars:
+ - key: DART_SASS_VERSION
- value: 1.25.5
++ value: 1.97.3
+ - key: GO_VERSION
- value: 0.152.2
++ value: 1.25.6
+ - key: HUGO_VERSION
- value: 24.12.0
++ value: 0.155.3
+ - key: NODE_VERSION
++ value: 24.13.0
+ - key: TZ
+ value: Europe/Oslo
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Render.
+ #
+ # Render automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu.
+
+ 
+
+Step 5
+: Press the **GitHub** button to connect to your GitHub account.
+
+ 
+
+Step 6
+: Press the **Authorize Render** button to allow the Render application to access your GitHub account.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Render application.
+
+ 
+
+Step 8
+: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button.
+
+
+
+Step 9
+: On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 10
+: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page.
+
+ 
+
+Step 11
+: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page.
+
+ 
+
+Step 12
+: Click on the link to the static site resource.
+
+ 
+
+Step 13
+: Click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Render will rebuild and deploy your site.
+
+[Render Blueprint]: https://render.com/docs/blueprint-spec
+[dashboard]: https://dashboard.render.com/
--- /dev/null
- - Working familiarity with [Git] or [Mercurial] for version control
- - Completion of the Hugo [Quick Start]
- - A [SourceHut account]
+---
+title: Host on SourceHut Pages
+description: Host your site on SourceHut Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-sourcehut/]
+---
+
+## Assumptions
+
- 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://<YourUsername>.srht.site/`). If you want to use another domain, check the [custom domain section] of the official documentation.
++- 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/
+[Mercurial]: https://www.mercurial-scm.org/
+[SourceHut account]: https://meta.sr.ht/login
+[Quick Start]: /getting-started/quick-start/
+
+Any and all mentions of `<YourUsername>` refer to your actual SourceHut username and must be substituted accordingly.
+
+## BaseURL
+
- 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:
++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://<YourUsername>.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
+
- First, define your [build manifest] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template:
++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/
+
+```sh
+hugo
+tar -C public -cvz . > site.tar.gz
+hut init
+hut pages publish -d <YourUsername>.srht.site site.tar.gz
+```
+
+A TLS certificate will be automatically obtained for you, and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Automated deployment
+
+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:
+
+[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests
+
+```yaml {file=".build.yml" copy=true}
+image: alpine/edge
+packages:
+ - hugo
+ - hut
+oauth: pages.sr.ht/PAGES:RW
+environment:
+ site: <YourUsername>.srht.site
+tasks:
+- package: |
+ cd $site
+ hugo
+ tar -C public -cvz . > ../site.tar.gz
+- upload: |
+ 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: <YourUsername>.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 `<YourUsername>.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git:
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to main branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://git.sr.ht/~<YourUsername>/<YourUsername>.srht.site
+git push -u origin main
+```
+
+You can now follow the build progress of your page at `https://builds.sr.ht/`.
+
+After the build has passed, a TLS certificate will be automatically obtained for you and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Other resources
+
+- [SourceHut Pages](https://srht.site/)
+- [SourceHut Builds user manual](https://man.sr.ht/builds.sr.ht/)
--- /dev/null
- DART_SASS_VERSION=1.96.0
- GO_VERSION=1.25.5
- HUGO_VERSION=0.152.2
- NODE_VERSION=24.12.0
+---
+title: Host on Vercel
+description: Host your site on Vercel.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://vercel.com/signup) a Vercel account
+1. [Log in](https://vercel.com/login) to your Vercel account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `vercel.json` file in the root of your project.
+
+ ```json {file="vercel.json" copy=true}
+ {
+ "$schema": "https://openapi.vercel.sh/vercel.json",
+ "buildCommand": "chmod a+x build.sh && ./build.sh",
+ "outputDirectory": "public"
+ }
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on Vercel.
+ #
+ # The Vercel build image automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
++ 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
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site"
+ hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu.
+
+ 
+
+Step 5
+: Press the "Continue with GitHub" button.
+
+ 
+
+Step 6
+: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account.
+
+ 
+
+Step 7
+: Press the **Install** button to install the Vercel application.
+
+ 
+
+Step 8
+: Select the GitHub account where you want to install the Vercel application.
+
+ 
+
+Step 9
+: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 10
+: Press the **Import** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 11
+: On the "New Project" page, leave the settings at their default values and press the **Deploy** button.
+
+ 
+
+Step 12
+: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page.
+
+ 
+
+Step 13
+: On the "Production Deployment" page, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.
--- /dev/null
- - 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.
+---
+title: Use Hugo Modules
+description: How to use Hugo Modules.
+categories: []
+keywords: []
+weight: 20
+aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
+---
+
+## Prerequisite
+
+{{% include "/_common/gomodules-info.md" %}}
+
+## Initialize a new module
+
+Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
+
+```sh
+hugo mod init github.com/<your_user>/<your_project>
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_init/).
+
+## Use a module for a theme
+
+The easiest way to use a Module for a theme is to import it in the configuration.
+
+1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
+1. Import the theme:
+
+ {{< code-toggle file=hugo >}}
+ [module]
+ [[module.imports]]
+ path = "github.com/spf13/hyde"
+ {{< /code-toggle >}}
+
+## Update modules
+
+Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports).
+
+To update or manage versions, you can use `hugo mod get`.
+
+Some examples:
+
+### Update all modules
+
+```sh
+hugo mod get -u
+```
+
+### Update all modules recursively
+
+```sh
+hugo mod get -u ./...
+```
+
+### Update one module
+
+```sh
+hugo mod get -u github.com/gohugoio/myShortcodes
+```
+
+### Get a specific version
+
+```sh
+hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_get/).
+
+## Make and test changes in a module
+
+One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
+
+```sh
+replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
+```
+
+If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
+
+Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option.
+
+## Print dependency graph
+
+Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
+
+E.g.:
+
+```txt
+hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+Also see the [CLI Doc](/commands/hugo_mod_graph/).
+
+## Vendor your modules
+
+`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds.
+
+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 pattern](g).
+
+Also see the [CLI Doc](/commands/hugo_mod_vendor/).
+
+## Tidy go.mod, go.sum
+
+Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
+
+Also see the [CLI Doc](/commands/hugo_mod_clean/).
+
+## Clean module cache
+
+Run `hugo mod clean` to delete the entire modules cache.
+
+Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/).
+
+Also see the [CLI Doc](/commands/hugo_mod_clean/).
+
+## Module workspaces
+
+Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version.
+
+A common use case for a workspace is to simplify local development of a site with its theme modules.
+
+A workspace can be configured in a `*.work` file and activated with the [module.workspace](/configuration/module/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable.
+
+See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example:
+
+```text
+go 1.20
+
+use .
+use ../gohugoioTheme
+```
+
+Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the `.`) in the list.
+
+With that you can start the Hugo server with that workspace enabled:
+
+```sh
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded.
--- /dev/null
- ## Editions
-
+---
+title: BSD
+description: Install Hugo on BSD derivatives.
+categories: []
+keywords: []
+weight: 40
+---
+
- Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Repository packages
+
+Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release].
+
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
+
+### DragonFly BSD
+
+[DragonFly BSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkg install gohugo
+```
+
+[DragonFly BSD]: https://www.dragonflybsd.org/
+
+### FreeBSD
+
+[FreeBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkg install gohugo
+```
+
+[FreeBSD]: https://www.freebsd.org/
+
+### NetBSD
+
+[NetBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkgin install go-hugo
+```
+
+[NetBSD]: https://www.netbsd.org/
+
+### OpenBSD
+
+[OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
+
+```sh
+doas pkg_add hugo
+```
+
+[OpenBSD]: https://www.openbsd.org/
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Repository packages|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
+Automatic updates?|:x:|varies|:x:
+Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
--- /dev/null
- ## Editions
-
+---
+title: Linux
+description: Install Hugo on Linux.
+categories: []
+keywords: []
+weight: 20
+---
+
- Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
+{{% include "/_common/installation/01-editions.md" %}}
+
- [most distributions]: https://snapcraft.io/docs/installing-snapd
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
++<!--
+### Snap
+
+[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
+
+The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. The sites you create and build must be located within your home directory, or on removable media.
+
+To install the extended edition of Hugo:
+
+```sh
+sudo snap install hugo
+```
+
+To control automatic updates:
+
+```sh
+# disable automatic updates
+sudo snap refresh --hold hugo
+
+# enable automatic updates
+sudo snap refresh --unhold hugo
+```
+
+To control access to removable media:
+
+```sh
+# allow access
+sudo snap connect hugo:removable-media
+
+# revoke access
+sudo snap disconnect hugo:removable-media
+```
+
+To control access to SSH keys:
+
+```sh
+# allow access
+sudo snap connect hugo:ssh-keys
+
+# revoke access
+sudo snap disconnect hugo:ssh-keys
+```
+
++[strictly confined]: https://snapcraft.io/docs/snap-confinement
++[most distributions]: https://snapcraft.io/docs/installing-snapd
++[Snap]: https://snapcraft.io/
++-->
++
+{{% include "/_common/installation/homebrew.md" %}}
+
+## Repository packages
+
+Most Linux distributions maintain a repository for commonly installed applications.
+
+> [!note]
+> The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version].
+>
+> Use one of the other installation methods if your package repository does not provide the desired version.
+
+### Alpine Linux
+
+To install the extended edition of Hugo on [Alpine Linux]:
+
+```sh
+doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
+```
+
+### Arch Linux
+
+Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo:
+
+```sh
+sudo pacman -S hugo
+```
+
+### Debian
+
+Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. To install the extended edition of Hugo:
+
+```sh
+sudo apt install hugo
+```
+
+You can also download Debian packages from the [latest release][] page.
+
+### Exherbo
+
+To install the extended edition of Hugo on [Exherbo]:
+
+1. Add this line to /etc/paludis/options.conf:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+1. Install using the Paludis package manager:
+
+ ```sh
+ cave resolve -x repository/heirecka
+ cave resolve -x hugo
+ ```
+
+### Fedora
+
+Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. To install the extended edition of Hugo:
+
+```sh
+sudo dnf install hugo
+```
+
+### Gentoo
+
+Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
+
+1. Specify the `extended` [USE] flag in /etc/portage/package.use/hugo:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+1. Build using the Portage package manager:
+
+ ```sh
+ sudo emerge www-apps/hugo
+ ```
+
+### NixOS
+
+The NixOS distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+nix-env -iA nixos.hugo
+```
+
+### openSUSE
+
+Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. To install the extended edition of Hugo:
+
+```sh
+sudo zypper install hugo
+```
+
+### Solus
+
+The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo eopkg install hugo
+```
+
+### Void Linux
+
+To install the extended edition of Hugo on [Void Linux]:
+
+```sh
+sudo xbps-install -S hugo
+```
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Repository packages|Build from source
+:--|:--:|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
+Automatic updates?|:x:|varies [^2]|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+
+[^1]: Easy if a previous version is still installed.
+[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
+
+[Alpine Linux]: https://alpinelinux.org/
+[Arch Linux]: https://archlinux.org/
+[Calculate Linux]: https://www.calculate-linux.org/
+[CentOS]: https://www.centos.org/
+[Debian]: https://www.debian.org/
+[elementary OS]: https://elementary.io/
+[EndeavourOS]: https://endeavouros.com/
+[Exherbo]: https://www.exherbolinux.org/
+[Fedora]: https://getfedora.org/
+[Funtoo]: https://www.funtoo.org/
+[Garuda Linux]: https://garudalinux.org/
+[GeckoLinux]: https://geckolinux.github.io/
+[Gentoo]: https://www.gentoo.org/
+[KDE neon]: https://neon.kde.org/
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
+[latest version]: https://github.com/gohugoio/hugo/releases/latest
+[Linux Karmada]: https://linuxkamarada.com/
+[Linux Lite]: https://www.linuxliteos.com/
+[Linux Mint]: https://linuxmint.com/
+[Manjaro]: https://manjaro.org/
- [Snap]: https://snapcraft.io/
+[MX Linux]: https://mxlinux.org/
+[openSUSE]: https://www.opensuse.org/
+[Pop!_OS]: https://pop.system76.com/
+[Red Hat Enterprise Linux]: https://www.redhat.com/
- [strictly confined]: https://snapcraft.io/docs/snap-confinement
+[Solus]: https://getsol.us/
+[Ubuntu]: https://ubuntu.com/
+[USE]: https://packages.gentoo.org/packages/www-apps/hugo
+[Void Linux]: https://voidlinux.org/
+[Zorin OS]: https://zorin.com/os/
--- /dev/null
- ## Editions
-
+---
+title: macOS
+description: Install Hugo on macOS.
+categories: []
+keywords: []
+weight: 10
+---
+
- Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+{{% include "/_common/installation/homebrew.md" %}}
+
+### MacPorts
+
+[MacPorts] is a free and open-source package manager for macOS. To install the extended edition of Hugo:
+
+```sh
+sudo port install hugo
+```
+
+[MacPorts]: https://www.macports.org/
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^2]|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+
+[^1]: Easy if a previous version is still installed.
+[^2]: Possible but requires advanced configuration.
--- /dev/null
- ## Editions
-
+---
+title: Windows
+description: Install Hugo on Windows.
+categories: []
+keywords: []
+weight: 30
+---
+
+> [!note]
+> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
+
- Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+### Chocolatey
+
+[Chocolatey] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+choco install hugo-extended
+```
+
+### Scoop
+
+[Scoop] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+scoop install hugo-extended
+```
+
+### Winget
+
+[Winget] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+winget install Hugo.Hugo.Extended
+```
+
+To uninstall the extended edition of Hugo:
+
+```sh
+winget uninstall --name "Hugo (Extended)"
+```
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+> [!note]
+> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^1]|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+
+[^1]: Possible but requires advanced configuration.
+[^2]: Easy if a previous version is still installed.
+
+[Chocolatey]: https://chocolatey.org/
+[Scoop]: https://scoop.sh/
+[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++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 }}
++```
--- /dev/null
--- /dev/null
++---
++title: Output format methods
++linkTitle: Output format
++description: Use these methods with an OutputFormat object.
++categories: []
++keywords: []
++---
--- /dev/null
- description: Returns the URL aliases as defined in front matter.
+---
+title: Aliases
- The `Aliases` method on a `Page` object 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:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.Aliases]
+---
+
- For example:
++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).
+
- {{< code-toggle file=content/about.md fm=true >}}
- title = 'About'
- aliases = ['/old-url','/really-old-url']
++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.
+
- To list the aliases:
++## Redirects
++
++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.
++
++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
++```
++
++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 >}}
+
- ```go-html-template
- {{ range .Aliases }}
- {{ . }}
- {{ end }}
++### 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:
+
- [aliases]: /content-management/urls/#aliases
++```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/
--- /dev/null
- ## Methods
-
- {{% include "/_common/methods/page/output-format-methods.md" %}}
-
- ## Example
-
- Generate a `link` element in the `<head>` of each page for each of the alternative output formats:
+---
+title: AlternativeOutputFormats
+description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.OutputFormats
+ signatures: [PAGE.AlternativeOutputFormats]
+---
+
+{{% glossary-term "output format" %}}
+
+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/).
+
- <head>
- ...
- {{ $title := printf "%s | %s" .Title site.Title }}
- {{ if .IsHome }}
- {{ $title = site.Title }}
- {{ end }}
- {{ range .AlternativeOutputFormats }}
- {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink $title | safeHTML }}
- {{ end }}
- ...
- </head>
++For example, to generate a `link` element for each of the alternative output formats:
+
+```go-html-template
- On the site's home page, Hugo renders this to:
++{{ range .AlternativeOutputFormats }}
++ {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
++{{ end }}
+```
+
- <link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets, Inc.">
++Hugo renders this to something like:
+
+```html
++<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml">
++<link rel="alternate" type="application/json" href="https://example.org/index.json">
+```
--- /dev/null
- 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.
+---
+title: GitInfo
+description: Returns Git information related to the last commit of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '*gitmap.GitInfo'
+ signatures: [PAGE.GitInfo]
+---
+
+The `GitInfo` method on a `Page` object returns an object with additional methods.
+
+> [!note]
+> Hugo's Git integration is performant, but may increase build times on large sites.
+
+## Prerequisites
+
+Install Git, create a repository, and commit your project files.
+
+You must also allow Hugo to access your repository. In your site configuration:
+
+{{< code-toggle file=hugo >}}
+enableGitInfo = true
+{{< /code-toggle >}}
+
+Alternatively, use the command line flag when building your site:
+
+```sh
+hugo --enableGitInfo
+```
+
+> [!note]
+> When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file.
+>
+> This is configurable. See [details].
+
+## Methods
+
+### AbbreviatedHash
+
+(`string`) The abbreviated commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AbbreviatedHash }} → aab9ec0b3
+{{ end }}
+```
+
+### AuthorDate
+
+(`time.Time`) The author date.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### AuthorEmail
+
+(`string`) The author's email address, respecting [gitmailmap].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorEmail }} → jsmith@example.org
+{{ end }}
+```
+
+### AuthorName
+
+(`string`) The author's name, respecting [gitmailmap].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorName }} → John Smith
+{{ end }}
+```
+
+### CommitDate
+
+(`time.Time`) The commit date.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### Hash
+
+(`string`) The commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
+{{ end }}
+```
+
+### Subject
+
+(`string`) The commit message subject.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Subject }} → Add tutorials
+{{ end }}
+```
+
+### Body
+
+(`string`) The commit message body.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Body }} → - Two new pages added.
+{{ end }}
+```
+
+### Ancestors
+
+(`gitmap.GitInfos`) A slice of file-filtered ancestor commits, if any, ordered from most recent to least recent.
+
+For example, to list the last 5 commits:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+To reverse the order:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors.Reverse | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+### Parent
+
+(`*gitmap.GitInfo`) The first file-filtered ancestor commit, if any.
+
+## Last modified date
+
+By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
+
+You can change this behavior in your [site configuration].
+
+## Hosting considerations
+
++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.
+
+Hosting service|Default clone depth|Configurable
+:--|:--|:--
+AWS Amplify|Deep|N/A
+Cloudflare|Shallow|Yes [^1]
+DigitalOcean App Platform|Deep|N/A
+GitHub Pages|Shallow|Yes [^2]
+GitLab Pages|Shallow|Yes [^3]
+Netlify|Deep|N/A
+Render|Shallow|Yes [^1]
+Vercel|Shallow|Yes [^1]
+
+[^1]: To perform a deep clone when hosting on Cloudflare, Render, or Vercel, include this code in the build script after the repository has been cloned:
+
+ ```text
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+ ```
+
+[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action. See [example](/host-and-deploy/host-on-github-pages/#step-7).
+
+[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+
+[details]: /configuration/front-matter/#dates
+[gitmailmap]: https://git-scm.com/docs/gitmailmap
+[site configuration]: /configuration/front-matter/
--- /dev/null
- 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.
+---
+title: Language
+description: Returns the language object for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [PAGE.Language]
+---
+
- The examples below assume the following in your 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
+
- (`string`) The language tag as defined by [RFC 5646].
++The examples below assume the following in the site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+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]. This is the lower cased key from the site configuration.
+
+```go-html-template
+{{ .Language.Lang }} → de
+```
+
+### LanguageCode
+
+(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+
+```go-html-template
+{{ .Language.LanguageCode }} → de-DE
+```
+
+### LanguageDirection
+
+(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+
+```go-html-template
+{{ .Language.LanguageDirection }} → ltr
+```
+
+### LanguageName
+
+(`string`) The language name from the site configuration.
+
+```go-html-template
+{{ .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.
+
+```go-html-template
+{{ .Language.Weight }} → 2
+```
+
++[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[details]: /methods/site/language/
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- {{% include "/_common/methods/page/output-format-methods.md" %}}
+---
+title: OutputFormats
+description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]OutputFormat'
+ signatures: [PAGE.OutputFormats]
+---
+
+{{% glossary-term "output format" %}}
+
+The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/).
+
+## Methods
+
- ## Example
++### Canonical
+
- To link to the RSS feed for the current page:
++{{< new-in "0.154.4" />}}
+
- {{ with .OutputFormats.Get "rss" }}
- <a href="{{ .RelPermalink }}">RSS Feed</a>
++(`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
- On the site's home page, Hugo renders this to:
++{{ 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 "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
+{{ end }}
+```
+
- ```html
- <a href="/index.xml">RSS Feed</a>
++To render an anchor element pointing to the `rss` output format for the current page:
+
++```go-html-template
++{{ with .OutputFormats.Get "rss" }}
++ <a href="{{ .RelPermalink }}">RSS Feed</a>
++{{ end }}
+```
+
+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
--- /dev/null
- {{< new-in 0.123.0 />}}
-
+---
+title: Path
+description: Returns the logical path of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Path]
+---
+
+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" %}}
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+> [!note]
+> Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
+>
+> The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
+
+The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
+
+## Examples
+
+### Monolingual site
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
+[`Page.Ref`]| |
+[`Page.RelRef`]| |
+[`Shortcode.Ref`]| |
+[`Shortcode.RelRef`]| |
+
+> [!note]
+> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+## Logical tree
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+A key difference between these trees is the relative path from p1 to p2:
+
+- In the file tree, the relative path from p1 to p2 is `../p2.md`
+- In the logical tree, the relative path is `p2`
+
+> [!note]
+> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+[`Page.GetPage`]: /methods/page/getpage/
+[`Page.Ref`]: /methods/page/ref/
+[`Page.RelRef`]: /methods/page/relref/
+[`ref`]: /shortcodes/ref/
+[`relref`]: /shortcodes/relref/
+[`Shortcode.Ref`]: /methods/shortcode/ref
+[`Shortcode.RelRef`]: /methods/shortcode/relref
+[`Site.GetPage`]: /methods/site/getpage/
+[`urls.Ref`]: /functions/urls/ref/
+[`urls.RelRef`]: /functions/urls/relref/
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
--- /dev/null
- (`resource.Resource`) Returns the first page resource from paths matching the given [glob](g) pattern, or nil if none found.
+---
+title: Resources
+description: Returns a collection of page resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: resource.Resources
+ signatures: [PAGE.Resources]
+---
+
+The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g).
+
+To work with global or remote resources, see the [`resources`] functions.
+
+## Methods
+
+### ByType
+
+(`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`.
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.ByType`] function.
+
+### Get
+
+(`resource.Resource`) Returns a page resource from the given path, or nil if none found.
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Get`] function.
+
+### GetMatch
+
- (`resource.Resources`) Returns a collection of page resources 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" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.GetMatch`] function.
+
+### Match
+
- With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob](g) pattern.
++(`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" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Match`] function.
+
+### Mount
+
+{{< new-in 0.140.0 />}}
+
+(`ResourceGetter`) Mounts the given resources from the two arguments base (`string`) to the given target path (`string`) and returns an object that implements [Get](#get). Note that leading slashes in target marks an absolute path. Relative target paths allows you to mount resources relative to another set, e.g. a [Page bundle](/content-management/page-bundles/):
+
+```go-html-template
+{{ $common := resources.Match "/js/headlessui/*.*" }}
+{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
+```
+
+This method is currently only useful in [js.Batch](/functions/js/batch/#import-context).
+
+## Pattern matching
+
++With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern](g).
+
+{{% include "/_common/glob-patterns.md" %}}
+
+[`resources.ByType`]: /functions/resources/ByType/
+[`resources.GetMatch`]: /functions/resources/ByType/
+[`resources.Get`]: /functions/resources/ByType/
+[`resources.Match`]: /functions/resources/ByType/
+[`resources`]: /functions/resources/
+[media type]: https://en.wikipedia.org/wiki/Media_type
--- /dev/null
--- /dev/null
++---
++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 . }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++ {{ 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 . }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++ {{ end }}
++{{ end }}
++```
++
++To render a list of all versions of the current page, including the current page:
++
++```go-html-template
++{{ with .Rotate "version" }}
++ {{ range . }}
++ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
++ {{ end }}
++{{ end }}
++```
--- /dev/null
- {{< new-in 0.125.0 />}}
-
+---
+title: Sitemap
+description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: config.SitemapConfig
+ signatures: [PAGE.Sitemap]
+---
+
+Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates].
+
+## Methods
+
+### 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).
+
+```go-html-template
+{{ .Sitemap.ChangeFreq }}
+```
+
+### Disable
+
+(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+```go-html-template
+{{ .Sitemap.Disable }}
+```
+
+### Priority
+
+(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
+
+```go-html-template
+{{ .Sitemap.Priority }}
+```
+
+## Example
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+[sitemap]
+changeFreq = 'monthly'
+{{< /code-toggle >}}
+
+And this content:
+
+{{< code-toggle file=content/news.md fm=true >}}
+title = 'News'
+[sitemap]
+changeFreq = 'hourly'
+{{< /code-toggle >}}
+
+And this simplistic sitemap template:
+
+```xml {file="layouts/sitemap.xml"}
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
+ {{ range .Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>
+ {{ if not .Lastmod.IsZero }}
+ <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
+ {{ end }}
+ {{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>
+ {{ end }}
+ </url>
+ {{ end }}
+</urlset>
+```
+
+The change frequency will be `hourly` for the news page, and `monthly` for other pages.
+
+[sitemap templates]: /templates/sitemap/
--- /dev/null
- To render a link to the home page of the site corresponding to the default content language:
+---
+title: Sites
+description: Returns a collection of all Site objects, one for each language, ordered by language weight.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [PAGE.Sites]
+---
+
+This is a convenience method to access `.Site.Sites`.
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range .Sites }}
+ <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
+ <li><a href="https://example.org/en/">Project Documentation</a></li>
+</ul>
+```
+
++To render a link to the home page of the [default site](g):
+
+```go-html-template
+{{ with .Sites.Default }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index .Sites 0 }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
--- /dev/null
- 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.
+---
+title: Colors
+description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]images.Color'
+ signatures: [RESOURCE.Colors]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{< new-in 0.125.0 />}}
-
++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
+
+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
+
+(`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]
+> Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments.
+>
+> Hugo renders an `images.Color` object as a hexadecimal color value.
+
+## Sorting
+
+As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <table>
+ <thead>
+ <tr>
+ <th>Color</th>
+ <th>Relative luminance</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range .Colors }}
+ <tr>
+ <td>{{ .ColorHex }}</td>
+ <td>{{ .Luminance | lang.FormatNumber 4 }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+{{ end }}
+```
+
+Hugo renders this to:
+
+ColorHex|Relative luminance
+:--|:--
+`#bebebd`|`0.5145`
+`#514947`|`0.0697`
+`#768a9a`|`0.2436`
+`#647789`|`0.1771`
+`#90725e`|`0.1877`
+`#a48974`|`0.2704`
+
+To sort by dominance with the least dominant color first:
+
+```go-html-template
+{{ range .Colors | collections.Reverse }}
+```
+
+To sort by relative luminance with the darkest color first:
+
+```go-html-template
+{{ range sort .Colors "Luminance" }}
+```
+
+To sort by relative luminance with the lightest color first, use either of these constructs:
+
+```go-html-template
+{{ range sort .Colors "Luminance" | collections.Reverse }}
+{{ range sort .Colors "Luminance" "desc" }}
+```
+
+## Examples
+
+### Image borders
+
+To add a 5 pixel border to an image using the most dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $mostDominant := index .Colors 0 }}
+ {{ $filter := images.Padding 5 $mostDominant }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To add a 5 pixel border to an image using the darkest dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $filter := images.Padding 5 $darkest }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+### Light text on dark background
+
+To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ <div style="background: {{ $darkest }};">
+ <div style="color: {{ $lightest }};">
+ <p>This is light text on a dark background.</p>
+ </div>
+ </div>
+{{ end }}
+```
+
+### WCAG contrast ratio
+
+In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
+
+The WCAG defines the [contrast ratio] as:
+
+$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
+
+where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
+
+Calculate the contrast ratio to determine WCAG conformance:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $cr := div
+ (add $lightest.Luminance 0.05)
+ (add $darkest.Luminance 0.05)
+ }}
+ {{ if ge $cr 7.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
+ {{ else if ge $cr 4.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
+ {{ else }}
+ {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
+ {{ end }}
+{{ end }}
+```
+
+[`images.Dither`]: /functions/images/dither/
+[`images.Padding`]: /functions/images/padding/
+[`images.Text`]: /functions/images/text/
+[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
+[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
--- /dev/null
- description: Applicable to images, returns an image resource cropped to the given dimensions without resizing.
+---
+title: Crop
- signatures: [RESOURCE.Crop SPEC]
++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
- Crop an image to match the given dimensions without resizing. You must provide both width and height.
++ signatures: [RESOURCE.Crop SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Crop "200x200" }}
++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 topright webp q85 lanczos" }}
++ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ 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" }}
- filterArgs="crop 200x200 topright webp q85 lanczos"
++ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="crop 200x200 TopRight"
+ example=true
+>}}
++
++[processing specification]: #processing-specification
--- /dev/null
- description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an EXIF object containing image metadata.
+---
+title: Exif
- keywords: []
++description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
+categories: []
- returnType: exif.ExifInfo
++keywords: ['metadata']
+params:
+ functions_and_methods:
- Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metadata.
++ returnType: meta.ExifInfo
+ signatures: [RESOURCE.Exif]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- (`float64`) Returns the GPS latitude in degrees.
++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
+
+### Date
+
+(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
+
+### Lat
+
- (`float64`) Returns the GPS longitude in degrees.
++(`float64`) Returns the GPS latitude in degrees from Exif metadata.
+
+### Long
+
- (`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
++(`float64`) Returns the GPS longitude in degrees from Exif metadata.
+
+### Tags
+
- To list the creation date, location, and EXIF tags:
++(`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
+
- <p>Date: {{ .Date }}</p>
- <p>Lat/Long: {{ .Lat }}/{{ .Long }}</p>
- {{ with .Tags }}
- <p>Tags</p>
- <table>
- <thead>
- <tr><th>Tag</th><th>Value</th></tr>
- </thead>
- <tbody>
- {{ range $k, $v := . }}
- <tr><td>{{ $k }}</td><td>{{ $v }}</td></tr>
- {{ end }}
- </tbody>
- </table>
- {{ end }}
++To list the creation date, latitude, and longitude:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Exif }}
++ <pre>
++ {{ printf "%-25s %v\n" "Date" .Date }}
++ {{ printf "%-25s %v\n" "Latitude" .Lat }}
++ {{ printf "%-25s %v\n" "Longitude" .Long }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list the available Exif fields:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with .Exif }}
- To list specific values:
++ <pre>
++ {{ range $k, $v := .Tags -}}
++ {{ printf "%-25s %v\n" $k $v }}
++ {{ end }}
++ </pre>
+ {{ end }}
+{{ end }}
+```
+
- <ul>
- {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
- {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
- {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
- {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
- {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
- {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
- </ul>
++To list specific Exif fields:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with .Exif }}
- [exif]: https://en.wikipedia.org/wiki/Exif
++ <pre>
++ {{ with .Tags.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
++ {{ with .Tags.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
++ </pre>
+ {{ 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
--- /dev/null
- description: Applicable to images, returns an image resource cropped and resized to the given dimensions.
+---
+title: Fill
- signatures: [RESOURCE.Fill SPEC]
++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
- Crop and resize an image to match the given dimensions. You must provide both width and height.
++ signatures: [RESOURCE.Fill SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Fill "200x200" }}
++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 top webp q85 lanczos" }}
++ {{ with .Fill "500x200 TopRight lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ 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" }}
- filterArgs="fill 200x200 top webp q85 lanczos"
++ {{ with .Fill "500x200 TopRight lanczos webp q85" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="fill 500x200 TopRight lanczos webp q85"
+ example=true
+>}}
++
++[`Resize`]: /methods/resource/resize/
++[processing specification]: #processing-specification
--- /dev/null
- keywords: []
+---
+title: Filter
+description: Applicable to images, applies one or more image filters to the given image resource.
+categories: []
++keywords: [filter]
+params:
++ alt_title: RESOURCE.Filter
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Filter FILTER...]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+Apply one or more [image filters](#image-filters) to the given image.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`images.Filter`] function.
+
+[`images.Filter`]: /functions/images/filter/
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `Filter` method.
+
+{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
--- /dev/null
- description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio.
+---
+title: Fit
- signatures: [RESOURCE.Fit SPEC]
++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
- Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.
++ signatures: [RESOURCE.Fit SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Fit "200x200" }}
++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 "300x175 webp q85 lanczos" }}
++ {{ with .Fit "300x175 lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ 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" }}
- filterArgs="fit 300x175 webp q85 lanczos"
++ {{ with .Fit "300x175 lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="fit 300x175 lanczos"
+ example=true
+>}}
++
++[`Resize`]: /methods/resource/resize/
++[`Fill`]: /methods/resource/fill/
++[processing specification]: #processing-specification
--- /dev/null
--- /dev/null
++---
++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 }}
++ <pre>
++ {{ printf "%-25s %v\n" "Date" .Date }}
++ {{ printf "%-25s %v\n" "Latitude" .Lat }}
++ {{ printf "%-25s %v\n" "Longitude" .Long }}
++ {{ printf "%-25s %v\n" "Orientation" .Orientation }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list the available Exif fields:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Meta }}
++ <pre>
++ {{ range $k, $v := .Exif -}}
++ {{ printf "%-25s %v\n" $k $v }}
++ {{ end }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list the available IPTC fields:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Meta }}
++ <pre>
++ {{ range $k, $v := .IPTC -}}
++ {{ printf "%-25s %v\n" $k $v }}
++ {{ end }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list the available XMP fields:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Meta }}
++ <pre>
++ {{ range $k, $v := .XMP -}}
++ {{ printf "%-25s %v\n" $k $v }}
++ {{ end }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list the available Exif, IPTC, and XMP fields together:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Meta }}
++ <pre>
++ {{ range $k, $v := merge .Exif .IPTC .XMP -}}
++ {{ printf "%-25s %v\n" $k $v }}
++ {{ end }}
++ </pre>
++ {{ end }}
++{{ end }}
++```
++
++To list specific values:
++
++```go-html-template
++{{ with resources.Get "images/a.jpg" }}
++ {{ with .Meta }}
++ <pre>
++ {{ 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 }}
++ </pre>
++ {{ 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
--- /dev/null
- description: Applicable to images, returns an image resource processed with the given specification.
+---
+title: Process
- keywords: []
++description: Applicable to images, returns a new image resource processed according to the given processing specification.
+categories: []
- signatures: [RESOURCE.Process SPEC]
++keywords: [process]
+params:
++ alt_title: RESOURCE.Process
+ functions_and_methods:
+ returnType: images.ImageResource
- 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`].
++ signatures: [RESOURCE.Process SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Process "crop 200x200" }}
++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 topright webp q85 lanczos" }}
++ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ 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
+{{/* Rotate 90 degrees counter-clockwise. */}}
+{{ $image := $image.Process "r90" }}
+
+{{/* Convert to WebP. */}}
+{{ $image := $image.Process "webp" }}
+```
+
+The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`].
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- filterArgs="crop 200x200 topright webp q85 lanczos"
++ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
- [`Crop`]: /methods/resource/crop/
- [`Fill`]: /methods/resource/fill/
- [`Fit`]: /methods/resource/fit/
- [`Resize`]: /methods/resource/resize/
++ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
+
+[`images.Process`]: /functions/images/process/
++[processing specification]: #processing-specification
--- /dev/null
- description: Applicable to images, returns an image resource resized to the given width and/or height.
+---
+title: Resize
- signatures: [RESOURCE.Resize SPEC]
++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
- 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.
++ signatures: [RESOURCE.Resize SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Resize "300x" }}
++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 webp q85 lanczos" }}
++ {{ with .Resize "300x lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ 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" }}
- filterArgs="resize 300x webp q85 lanczos"
++ {{ with .Resize "300x lanczos" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="resize 300x lanczos"
+ example=true
+>}}
++
++[processing specification]: #processing-specification
--- /dev/null
--- /dev/null
++---
++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
++```
--- /dev/null
- 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.
+---
+title: Language
+description: Returns the language object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [SITE.Language]
+---
+
- The examples below assume the following in your 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
+
- (`string`) The language tag as defined by [RFC 5646].
++The examples below assume the following in the site configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+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]. This is the lower cased key from the site configuration.
+
+```go-html-template
+{{ .Site.Language.Lang }} → de
+```
+
+### LanguageCode
+
+(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+
+```go-html-template
+{{ .Site.Language.LanguageCode }} → de-DE
+```
+
+### LanguageDirection
+
+(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+
+```go-html-template
+{{ .Site.Language.LanguageDirection }} → ltr
+```
+
+### LanguageName
+
+(`string`) The language name from the site configuration.
+
+```go-html-template
+{{ .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.
+
+```go-html-template
+{{ .Site.Language.Weight }} → 1
+```
+
+## Example
+
+Some of the methods above are commonly used in a base template as attributes for the `html` element.
+
+```go-html-template
+<html
+ lang="{{ .Site.Language.LanguageCode }}"
+ dir="{{ or .Site.Language.LanguageDirection `ltr` }}"
+>
+```
+
++[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[details]: /methods/page/language/
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- {{< new-in 0.123.0 />}}
-
+---
+title: Lastmod
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [SITE.Lastmod]
+---
+
+The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
+
+```go-html-template
+{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
+[functions]: /functions/time/
+[methods]: /methods/time/
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- To render a link to the home page of the site corresponding to the default content language:
+---
+title: Sites
+description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [SITE.Sites]
+---
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+languageCode = 'de-DE'
+languageDirection = 'ltr'
+languageName = 'Deutsch'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageDirection = 'ltr'
+languageName = 'English'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Sites }}
+ <li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
+ <li><a href="https://example.org/en/">Project Documentation</a></li>
+</ul>
+```
+
++To render a link to the home page of the [default site](g):
+
+```go-html-template
+{{ with .Site.Sites.Default }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index .Site.Sites 0 }}
+ <a href="{{ .Home.Permalink }}">{{ .Title }}</a>
+{{ end }}
+```
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- {{< new-in 0.125.0 />}}
-
+---
+title: Page
+description: Returns the taxonomy page or nil if the taxonomy has no terms.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [TAXONOMY.Page]
+---
+
+This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
+
+```go-html-template
+{{ with .Site.Taxonomies.tags.Page }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+This is rendered to:
+
+```html
+<a href="/tags/">Tags</a>
+```
--- /dev/null
--- /dev/null
++---
++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 (`.`).
--- /dev/null
- 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.
+---
+title: build
+---
+
++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.
--- /dev/null
- See [page bundle](g).
+---
+title: bundle
+---
+
++See [_page bundle_](g).
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- 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`.
+---
+title: chain
+---
+
++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`.
--- /dev/null
+---
+title: CI/CD
+params:
+ reference: https://en.wikipedia.org/wiki/CI/CD
+---
+
+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/
--- /dev/null
+---
+title: component
+---
+
+A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo website. These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g).
+
+ Each component has a dedicated directory within the unified file system:
+
+ Component|Directory within the unified file system
+ :--|:--
+ archetypes|`archetypes`
+ assets|`assets`
+ content|`content`
+ data|`data`
+ templates|`layouts`
+ translation tables|`i18n`
+ static files|`static`
++ {class="!mt-0"}
--- /dev/null
--- /dev/null
++---
++title: content dimension
++---
++
++See [_dimension_](g).
--- /dev/null
- 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.
+---
+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_](g) template to use when creating new content.
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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_.
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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.*.*)`.
--- /dev/null
- 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.
+---
+title: interpreted string literal
+reference: https://go.dev/ref/spec#String_literals
+---
+
++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.
--- /dev/null
- 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).
+---
+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).
--- /dev/null
- To _marshal_ is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string.
+---
+title: marshal
+reference: /functions/transform/remarshal/
+---
+
++To _marshal_ (verb) is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string.
--- /dev/null
- 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.
+---
+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.
--- /dev/null
--- /dev/null
++---
++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).
--- /dev/null
- To _paginate_ is to split a list page into two or more subsets.
+---
+title: paginate
+---
+
++To _paginate_ (verb) is to split a list page into two or more subsets.
--- /dev/null
--- /dev/null
++---
++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/
--- /dev/null
- 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.
+---
+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.
+
+[`Permalink`]: /methods/page/permalink/
+[`RelPermalink`]: /methods/page/relpermalink/
+[outputs configuration]: /configuration/outputs/
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- 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.
+---
+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.
--- /dev/null
- 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.
+---
+title: resource type
+---
+
++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.
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
- 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.
+---
+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.
--- /dev/null
- A _segment_ is a subset of a site, filtered by [_logical path_](g), language, [_page kind_](g), or [_output format_](g).
+---
+title: segment
+---
+
++A _segment_ is a subset of a site, filtered by [_logical path_](g), [_sites matrix_](g), [_page kind_](g), or [_output format_](g).
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
--- /dev/null
++---
++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).
--- /dev/null
--- /dev/null
++---
++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
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
--- /dev/null
++---
++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).
--- /dev/null
--- /dev/null
++---
++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).
--- /dev/null
- reference: content-management/taxonomies/#order-taxonomies
+---
+title: taxonomic weight
++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.
--- /dev/null
- A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [weighted pages](g) associated with each term.
+---
+title: taxonomy object
+---
+
++A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [_weighted pages_](g) associated with each term.
--- /dev/null
- 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.
+---
+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.
--- /dev/null
- See [content type](g).
+---
+title: type
+---
+
++See [_content type_](g).
--- /dev/null
- 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.
+---
+title: unmarshal
+reference: /functions/transform/unmarshal/
+---
+
++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.
--- /dev/null
--- /dev/null
++---
++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.
--- /dev/null
- To _walk_ is to recursively traverse a nested data structure. For example, rendering a multilevel menu.
+---
+title: walk
+---
+
++To _walk_ (verb) is to recursively traverse a nested data structure. For example, rendering a multilevel menu.
--- /dev/null
- 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.
+---
+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, [_roles_](g), versions, and output formats.
--- /dev/null
--- /dev/null
++---
++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)
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: Code block render hooks
+linkTitle: Code blocks
+description: Create code block render hook templates to override the rendering of Markdown code blocks to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+This Markdown example contains a fenced code block:
+
+````text {file="content/example.md"}
+```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+declare a=1
+echo "$a"
+exit
+```
+````
+
+A fenced code block consists of:
+
+- A leading [code fence]
+- An optional [info string]
+- A code sample
+- A trailing code fence
+
+In the previous example, the info string contains:
+
+- The language of the code sample (the first word)
+- An optional space-delimited or comma-delimited list of attributes (everything within braces)
+
+The attributes in the info string can be generic attributes or highlighting options.
+
+In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.
+
+In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
+
+> [!note]
+> Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
+
+## Context
+
+Code block _render hook_ templates receive the following [context](g):
+
+Attributes
+: (`map`) The generic attributes from the info string.
+
+Inner
+: (`string`) The content between the leading and trailing code fences, excluding the info string.
+
+Options
+: (`map`) The highlighting options from the info string. This map is empty if [`Type`](#type) is an empty string or a code language that is not supported by the Chroma syntax highlighter. However, in this case, the highlighting options are available in the [`Attributes`](#attributes) map.
+
+Ordinal
+: (`int`) The zero-based ordinal of the code block on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+Position
+: (`text.Position`) The position of the code block within the page content.
+
+Type
+: (`string`) The first word of the info string, typically the code language.
+
+## Examples
+
+In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-codeblock.html" copy=true}
+{{ $result := transform.HighlightCodeBlock . }}
+{{ $result.Wrapped }}
+```
+
+Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
+
+```text
+layouts/
+ └── _markup/
+ ├── render-codeblock-mermaid.html
+ ├── render-codeblock-python.html
+ └── render-codeblock.html
+```
+
+For example, to create a code block render hook to render [Mermaid] diagrams:
+
+```go-html-template {file="layouts/_markup/render-codeblock-mermaid.html" copy=true}
+<pre class="mermaid">
+ {{ .Inner | htmlEscape | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
+```
+
+Then include this snippet at the _bottom_ of your base template, before the closing `body` tag:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+{{ if .Store.Get "hasMermaid" }}
+ <script type="module">
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+ mermaid.initialize({ startOnLoad: true });
+ </script>
+{{ end }}
+```
+
+See the [diagrams] page for details.
+
+## Embedded
+
+Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[Chroma]: https://github.com/alecthomas/chroma/
+[code fence]: https://spec.commonmark.org/current/#code-fence
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
+[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
+[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+[highlighting options]: /functions/transform/highlight/#options
+[info string]: https://spec.commonmark.org/current/#info-string
+[Mermaid]: https://mermaid.js.org/
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: Heading render hooks
+linkTitle: Headings
+description: Create heading render hook templates to override the rendering of Markdown headings to HTML.
+categories: []
+keywords: []
+---
+
+## Context
+
+Heading _render hook_ templates receive the following [context](g):
+
+Anchor
+: (`string`) The `id` attribute of the heading element.
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser.attribute]
+ title = true
+ {{< /code-toggle >}}
+
+Level
+: (`int`) The heading level, 1 through 6.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The heading text as plain text.
+
+Text
+: (`template.HTML`) The heading text.
+
+[Markdown attributes]: /content-management/markdown-attributes/
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+## Examples
+
+In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+```go-html-template {file="layouts/_markup/render-heading.html" copy=true}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{- .Text -}}
+</h{{ .Level }}>
+```
+
+To add an anchor link to the right of each heading:
+
+```go-html-template {file="layouts/_markup/render-heading.html" copy=true}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{ .Text }}
+ <a href="#{{ .Anchor }}">#</a>
+</h{{ .Level }}>
+```
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: Image render hooks
+linkTitle: Images
+description: Create image render hook templates to override the rendering of Markdown images to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown image has three components: the image description, the image destination, and optionally the image title.
+
+```text
+
+ ------------ ------------------ ---------
+ description destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Image _render hook_ templates receive the following context:
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser]
+ wrapStandAloneImageWithinParagraph = false
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+Destination
+: (`string`) The image destination.
+
+IsBlock
+: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.
+
+Ordinal
+: (`int`) The zero-based ordinal of the image on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
- {{< new-in 0.123.0 />}}
-
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The image description as plain text.
+
+Text
+: (`template.HTML`) The image description.
+
+Title
+: (`string`) The image title.
+
+## Examples
+
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+
+In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+<img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+{{- /* chomp trailing newline */ -}}
+```
+
+To render standalone images within `figure` elements:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+{{- if .IsBlock -}}
+ <figure>
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ >
+ {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
+ </figure>
+{{- else -}}
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ >
+{{- end -}}
+```
+
+Note that the above requires the following site configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+{{< /code-toggle >}}
+
+## Embedded
+
+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 >}}
+[markup.goldmark.renderHooks.image]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
+When set to `auto` as shown above, Hugo automatically uses 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.
+
+You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhooksimageuseembedded).
+
+The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: <{{% eturl render-image %}}>
+[Markdown attributes]: /content-management/markdown-attributes/
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: Link render hooks
+linkTitle: Links
+description: Create a link render hook to override the rendering of Markdown links to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown link has three components: the link text, the link destination, and optionally the link title.
+
+```text
+[Post 1](/posts/post-1 "My first post")
+ ------ ------------- -------------
+ text destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Link _render hook_ templates receive the following context:
+
+Destination
+: (`string`) The link destination.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
- {{< new-in 0.123.0 />}}
-
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The link description as plain text.
+
+Text
+: (`template.HTML`) The link description.
+
+Title
+: (`string`) The link title.
+
+## Examples
+
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+
+In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+To include a `rel` attribute set to `external` for external links:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+{{- $u := urls.Parse .Destination -}}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ {{- if $u.IsAbs }} rel="external"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+## Embedded
+
+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 >}}
+[markup.goldmark.renderHooks.link]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
+When set to `auto` as shown above, Hugo automatically uses 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.
+
+You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: <{{% eturl render-link %}}>
--- /dev/null
- : {{< new-in 0.125.0 />}}
+---
+title: YouTube shortcode
+linkTitle: YouTube
+description: Embed a YouTube video in your content using the youtube shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+To display a YouTube video with this URL:
+
+```text
+https://www.youtube.com/watch?v=0RKpf3rK57I
+```
+
+Include this in your Markdown:
+
+```texts
+{{</* youtube 0RKpf3rK57I */>}}
+```
+
+Hugo renders this to:
+
+{{< youtube 0RKpf3rK57I >}}
+
+## Arguments
+
+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
+: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
+
+title
+: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
+
+Here's an example using some of the available arguments:
+
+```text
+{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.youTube />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+privacyEnhanced
+: (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`.
+
+[source code]: {{% eturl youtube %}}
--- /dev/null
- ### Not all static site generators are created equal
+---
+title: 1Password Support
+date: 2018-02-22
+description: 'Showcase: "Compiles 400 pages in five languages in the blink of an eye."'
+siteURL: https://support.1password.com/
+byline: "[Mitch Cohen](https://github.com/mitchchn), Documentation Team Lead"
+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
+
+Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo:
+
+**Hugo is static**. We're a security company, so we swear by static sites and use them wherever possible. We feel much safer pointing customers at HTML files than at a complicated server which needs to be hardened.
+
+**Hugo is Go**. We love the Go programming language at 1Password, and we were delighted to learn that Hugo used the same Go template syntax that our designers and front-end developers had already mastered.
+
+**Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye.
+
+**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and directory structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/).
+
+**Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax.
+
+**Hugo has an amazing developer community**. Hugo updates are frequent and filled to the brim with features and fixes. As we developed the multilingual version of our site, we submitted PRs for features we needed and were helped through the process by [@bep](https://github.com/bep) and others.
+
+**Hugo is simple to deploy**. Hugo has just the right amount of configuration options to fit into our build system without being too complicated.
+
+### Tech specs
+
+- [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016.
+- Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks.
+- Writers build and preview the site on their computers and contribute content using pull requests.
+- We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages.
+- Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files.
+- The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS.
--- /dev/null
- ### Why Hugo?
+---
+title: Forestry.io
+date: 2018-03-16
+description: 'Showcase: "Seeing Hugo in action is a whole different world of awesome."'
+siteURL: https://forestry.io/
+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?
+
+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.
+
+We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look:
+
+```text
+ | EN
++------------------+-----+
+ Pages | 141
+ Paginator pages | 4
+ Non-page files | 0
+ Static files | 537
+ Processed images | 0
+ Aliases | 60
+ Sitemaps | 1
+ Cleaned | 0
+
+Total in 739 ms
+```
+
+In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing.
+
+Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website.
+
+### What tools did we use?
+
+- Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it's a designer's dream come true.
+- Some say our main graphic is [mesmerizing](https://x.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
+- [**Hugo**](https://gohugo.io/) -- of course.
+- Chris can't think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization.
+- Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes.
+- We can't stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo's [custom output formats](/configuration/output-formats/).
+- [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website.
+- We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer.
+- For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/).
+- [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests.
+- We also use browser cookies and JS to customize our user's experience and give it a more dynamic feel.
--- /dev/null
- weight: 190
+---
+title: Custom 404 page
+linkTitle: 404 templates
+description: Create a template to render a 404 error page.
+categories: []
+keywords: []
++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:
+
+```go-html-template {file="layouts/404.html"}
+{{ define "main" }}
+ <h1>404 Not Found</h1>
+ <p>The page you requested cannot be found.</p>
+ <p>
+ <a href="{{ .Site.Home.RelPermalink }}">
+ Return to the home page
+ </a>
+ </p>
+{{ end }}
+```
+
+For multilingual sites, add the language key to the file name:
+
+```text
+layouts/
+├── 404.de.html
+├── 404.en.html
+└── 404.fr.html
+```
+
+Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
+
+Host|Capabilities and configuration
+:--|:--
+Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
+Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
+Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
+Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
+Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
+Caddy|See [details](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
+Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
+DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
+Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
+GitHub Pages|Redirection to is automatic and not configurable.
+GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
+NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
--- /dev/null
- weight: 170
+---
+title: Embedded partial templates
+description: Hugo provides embedded partial templates for common use cases.
+categories: []
+keywords: []
- : (`bool`) Whether to respect the browser's "do not track" setting. Default is `false`.
++weight: 180
+aliases: [/templates/internal]
+---
+
+{{< newtemplatesystem >}}
+
+## Disqus
+
+> [!note]
+> To override Hugo's embedded Disqus template, copy the [source code](<{{% eturl disqus %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "disqus.html" . }}`
+
+Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "disqus.html" . }}
+```
+
+### Configuration {#configuration-disqus}
+
+To use Hugo's Disqus template, first set up a single configuration value:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+Hugo's Disqus template accesses this value with:
+
+```go-html-template
+{{ .Site.Config.Services.Disqus.Shortname }}
+```
+
+You can also set the following in the front matter for a given piece of content:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+### Privacy {#privacy-disqus}
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.disqus />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+## Google Analytics
+
+> [!note]
+> To override Hugo's embedded Google Analytics template, copy the [source code](<{{% eturl google_analytics %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "google_analytics.html" . }}`
+
+Hugo includes an embedded template supporting [Google Analytics 4].
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+```
+
+### Configuration {#configuration-google-analytics}
+
+Provide your tracking ID in your configuration file:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+id = "G-MEASUREMENT_ID"
+{{</ code-toggle >}}
+
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+
+### Privacy {#privacy-google-analytics}
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.googleAnalytics />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+respectDoNotTrack
++: (`bool`) Whether to respect the browser's "do not track" setting. Default is `true`.
+
+## Open Graph
+
+> [!note]
+> To override Hugo's embedded Open Graph template, copy the [source code](<{{% eturl opengraph %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "opengraph.html" . }}`
+
+Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
+This format is used for Facebook and some other sites.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "opengraph.html" . }}
+```
+
+### Configuration {#configuration-open-graph}
+
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ description = 'Text about my cool site'
+ images = ['site-feature-image.jpg']
+ title = 'My cool site'
+ [params.social]
+ facebook_admin = 'jsmith'
+[taxonomies]
+ series = 'series'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = "Post title"
+description = "Text about this post"
+date = 2024-03-08T08:18:11-08:00
+images = ["post-cover.png"]
+audio = []
+videos = []
+series = []
+tags = []
+{{</ code-toggle >}}
+
+Hugo uses the page title and description for the title and description metadata.
+The first 6 URLs from the `images` array are used for image metadata.
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+
+Various optional metadata can also be set:
+
+- Date, published date, and last modified data are used to set the published time metadata if specified.
+- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
+- The first 6 `tags` on the page are used for the tags metadata.
+- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+
+If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+
+## Pagination
+
+See [details](/templates/pagination/).
+
+## Schema
+
+> [!note]
+> To override Hugo's embedded Schema template, copy the [source code](<{{% eturl schema %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "schema.html" . }}`
+
+Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "schema.html" . }}
+```
+
+## X (Twitter) Cards
+
+> [!note]
+> To override Hugo's embedded Twitter Cards template, copy the [source code](<{{% eturl twitter_cards %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "twitter_cards.html" . }}`
+
+Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
+metadata used to attach rich media to Tweets linking to your site.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "twitter_cards.html" . }}
+```
+
+### Configuration {#configuration-x-cards}
+
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ images = ["site-feature-image.jpg"]
+ description = "Text about my cool site"
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = "Post title"
+description = "Text about this post"
+images = ["post-cover.png"]
+{{</ code-toggle >}}
+
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+If no image resources with those names are found, the images defined in the [site config](/configuration/) are used instead.
+If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
+
+Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
+
+Set the value of `twitter:site` in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[params.social]
+twitter = "GoHugoIO"
+{{</ code-toggle >}}
+
+NOTE: The `@` will be added for you
+
+```html
+<meta name="twitter:site" content="@GoHugoIO"/>
+```
+
+[`partial`]: /functions/partials/include/
+[Disqus]: https://disqus.com
+[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
+[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
+[signing up]: https://disqus.com/profile/signup/
--- /dev/null
+---
+title: Introduction to templating
+linkTitle: Introduction
+description: An introduction to Hugo's templating syntax.
+categories: []
+keywords: []
+weight: 10
+---
+
+{{< newtemplatesystem >}}
+
+{{% glossary-term template %}}
+
+Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
+
+> [!note]
+> Hugo uses Go's [text/template] and [html/template] packages.
+>
+> The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
+>
+> By default, Hugo uses the html/template package when rendering HTML files.
+
+For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
+
+```go-html-template
+{{ $v1 := 6 }}
+{{ $v2 := 7 }}
+<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
+```
+
+While HTML templates are the most common, you can create templates for any [output format](g) including CSV, JSON, RSS, and plain text.
+
+## Context
+
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
+
+For example, a _page_ template receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
+
+### Current context
+
+Within a template, the dot (`.`) represents the current context.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+```
+
+In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter].
+
+The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+
+{{ range slice "foo" "bar" }}
+ <p>{{ . }}</p>
+{{ end }}
+
+{{ with "baz" }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
+
+```html
+<h2>My Page Title</h2>
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+### Template context
+
+Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
+
+```go-html-template {file="layouts/page.html"}
+{{ with "foo" }}
+ <p>{{ $.Title }} - {{ . }}</p>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>My Page Title - foo</p>
+```
+
+> [!note]
+> Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
+
+## Actions
+
+In the examples above, the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
+
+A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), the [current context](#current-context), [variables](#variables), [functions](#functions), [methods](#methods), and the [`nil`](#nil) keyword.
+
+```go-html-template {file="layouts/page.html"}
+{{ $convertToLower := true }}
+{{ if $convertToLower }}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{ end }}
+```
+
+In the example above:
+
+- `$convertToLower` is a variable
+- `true` is a literal boolean value
+- `if` is the beginning of a control structure
+- `strings.ToLower` is a function that converts all characters to lowercase
+- `Title` is a method on a the `Page` object
+- `end` is the end of a control structure
+
+Hugo renders the above to:
+
+```html {trim=false}
+
+
+ <h2>my page title</h2>
+
+```
+
+### Whitespace
+
+Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens:
+
+```go-html-template {file="layouts/page.html"}
+{{- $convertToLower := true -}}
+{{- if $convertToLower -}}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{- end -}}
+```
+
+Hugo renders this to:
+
+```html
+<h2>my page title</h2>
+```
+
+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:
+
+```go-html-template
+{{ strings.ToLower "Hugo" }} → hugo
+{{ "Hugo" | strings.ToLower }} → hugo
+```
+
+You can pipe the result of one function or method into another. For example, these are equivalent:
+
+```go-html-template
+{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
+{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
+```
+
+These are also equivalent:
+
+```go-html-template
+{{ mul 6 (add 2 5) }} → 42
+{{ 5 | add 2 | mul 6 }} → 42
+```
+
+> [!note]
+> Remember that the piped value becomes the final argument to the function or method to which you are piping.
+
+### Line splitting
+
+You can split a template action over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $v := or $arg1 $arg2 }}
+
+{{ $v := or
+ $arg1
+ $arg2
+}}
+```
+
+You can also split [raw string literals](g) over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $msg := "This is line one.\nThis is line two." }}
+
+{{ $msg := `This is line one.
+This is line two.`
+}}
+```
+
+### Nil
+
+Other than using the `nil` keyword in comparisons, you may not use it as an argument to any function or method, nor may you assign it to a variable. For example, these are valid uses of the `nil` keyword:
+
+```go-html-template
+{{ if gt 42 nil }}
+ <p>42 is greater than nil</p>
+{{ end }}
+
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+These, on the other hand, are invalid:
+
+```go-html-template
+{{ $a := nil }}
+{{ add 3 nil }}
+{{ nil | print}}
+```
+
+The actions above throw an error.
+
+## Variables
+
+A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
+
+Variables may contain [scalars](g), [slices](g), [maps](g), or [objects](g).
+
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
+
+```go-html-template
+{{ $total := 3 }}
+{{ range slice 7 11 21 }}
+ {{ $total = add $total . }}
+{{ end }}
+{{ $total }} → 42
+```
+
+Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
+
+With variables that represent a slice or map, use the [`index`] function to return the desired value.
+
+```go-html-template
+{{ $slice := slice "foo" "bar" "baz" }}
+{{ index $slice 2 }} → baz
+
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ index $map "c" }} → baz
+```
+
+> [!note]
+> Slices and arrays are zero-based; element 0 is the first element.
+
+With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
+
+```go-html-template
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ $map.c }} → baz
+
+{{ $homePage := .Site.Home }}
+{{ $homePage.Title }} → My Homepage
+```
+
+> [!note]
+> As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
+
+## Functions
+
+Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
+
+Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details.
+
+Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
+
+Function|Alias
+:--|:--
+[`strings.ToLower`](/functions/strings/tolower)|`lower`
+[`strings.ToUpper`](/functions/strings/toupper)|`upper`
+[`strings.Replace`](/functions/strings/replace)|`replace`
+
+As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
+
+When calling a function, separate the arguments from the function, and from each other, with a space. For example:
+
+```go-html-template
+{{ $total := add 1 2 3 4 }}
+```
+
+## Methods
+
+Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
+
+The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
+
+Object|Method|Description
+:--|:--|:--
+`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
+`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
+`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
+`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
+`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration.
+`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration.
+
+Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Page.Title }} → My Page Title
+```
+
+The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Title }} → My Page Title
+```
+
+Some methods take an argument. Separate the argument from the method with a space. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ $page := .Page.GetPage "/books/les-miserables" }}
+{{ $page.Title }} → Les Misérables
+```
+
+## Comments
+
+> [!note]
+> Do not attempt to use HTML comment delimiters to comment out template code.
+>
+> Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
+
+Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
+
+```text
+{{/* This is an inline comment. */}}
+{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
+```
+
+Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
+
+```text
+{{/*
+This is a block comment.
+*/}}
+
+{{- /*
+This is a block comment with
+adjacent whitespace removed.
+*/ -}}
+```
+
+You may not nest one comment inside of another.
+
+To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
+
+```go-html-template
+{{ "<!-- I am an HTML comment. -->" | safeHTML }}
+{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
+```
+
+## Include
+
+Use the [`template`] function to include one or more of Hugo's [embedded templates]:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+{{ partial "opengraph" . }}
+{{ partial "pagination.html" . }}
+{{ partial "schema.html" . }}
+{{ partial "twitter_cards.html" . }}
+```
+
+Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
+
+```go-html-template
+{{ partial "breadcrumbs.html" . }}
+{{ partialCached "css.html" . }}
+```
+
+Create your _partial_ templates in the `layouts/_partials` directory.
+
+> [!note]
+> In the examples above, note that we are passing the current context (the dot) to each of the templates.
+
+## Examples
+
+This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
+
+### Conditional blocks
+
+See documentation for [`if`], [`else`], and [`end`].
+
+```go-html-template
+{{ $var := 42 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
+```
+
+### Logical operators
+
+See documentation for [`and`] and [`or`].
+
+```go-html-template
+{{ $v1 := true }}
+{{ $v2 := false }}
+{{ $v3 := false }}
+{{ $result := false }}
+
+{{ if and $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → false
+
+{{ if or $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → true
+```
+
+### Loops
+
+See documentation for [`range`], [`else`], and [`end`].
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+To loop a specified number of times:
+
+```go-html-template
+{{ $s := slice }}
+{{ range 3 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0 1 2]
+```
+
+### Rebind context
+
+See documentation for [`with`], [`else`], and [`end`].
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+To test multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+ {{ . }}
+{{ else with $v2 }}
+ {{ . }} → 42
+{{ else }}
+ {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
+### Access site parameters
+
+See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
+
+With this site configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'ABC Widgets'
+baseURL = 'https://example.org'
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
+
+Access the custom site parameters by chaining the identifiers:
+
+```go-html-template
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+```
+
+### Access page parameters
+
+See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
+
+By way of example, consider this front matter:
+
+{{< code-toggle file=content/annual-conference.md fm=true >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+[params]
+display_related = true
+key-with-hyphens = 'must use index function'
+[params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
+The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined.
+
+Access the custom fields by [chaining](g) the [identifiers](g) when needed:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.email }} → jsmith@example.org
+{{ .Params.author.name }} → John Smith
+```
+
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → must use index function
+```
+
+[`and`]: /functions/go-template/and
+[`else`]: /functions/go-template/else/
+[`end`]: /functions/go-template/end/
+[`if`]: /functions/go-template/if/
+[`index`]: /functions/collections/indexfunction/
+[`or`]: /functions/go-template/or
+[`Page`]: /methods/page/
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[`range`]: /functions/go-template/range/
+[`safeHTML`]: /functions/safe/html
+[`Site`]: /methods/site/
+[`template`]: /functions/go-template/template/
+[`Title`]: /methods/page/title
+[`with`]: /functions/go-template/with/
+[current context]: #current-context
+[embedded templates]: /templates/embedded/
+[front matter fields]: /content-management/front-matter/#fields
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[go-templates]: /functions/go-template/
+[html/template]: https://pkg.go.dev/html/template
+[methods]: /methods/
+[partial templates]: /templates/types/#partial
+[templates]: /templates/
+[text/template]: https://pkg.go.dev/text/template
+[variables]: #variables
--- /dev/null
- | 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`.|
+---
+title: New template system in Hugo v0.146.0
+linktitle: New template system
+description: Overview of the new template system in Hugo v0.146.0.
+categories: []
+keywords: []
+weight: 1
+---
+
+In [Hugo v0.146.0], we performed a full re-implementation of how Go templates are handled in Hugo. This includes structural changes to the `layouts` folder and a new, more powerful template lookup system.
+
+We have aimed to maintain as much backward compatibility as possible by mapping "old to new," but some reported breakages have occurred. We're working on a full overhaul of the documentation on this topic – until then, this is a one-pager with the most important changes.
+
+## Changes to the `layouts` folder
+
- | 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]|
++| 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.
+
+## Changes to template lookup order
+
+We have consolidated the template lookup so it works the same across all [template types]. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
+
+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] |
+
+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:
+
+- `layouts/docs/api/_markup/render-link.html` will be used to render links from the Page path `/docs/api` and below.
+- `layouts/docs/baseof.html` will be used as the base template for the Page path `/docs` and below.
+- `layouts/tags/term.html` will be used for all `term` rendering in the `tags` taxonomy, except for the `blue` term, which will use `layouts/tags/blue/list.html`.
+
+## Example folder structure
+
+```text
+layouts
+├── baseof.html
+├── baseof.term.html
+├── home.html
+├── page.html
+├── section.html
+├── taxonomy.html
+├── term.html
+├── term.mylayout.en.rss.xml
+├── _markup
+│ ├── render-codeblock-go.term.mylayout.no.rss.xml
+│ └── render-link.html
+├── _partials
+│ └── mypartial.html
+├── _shortcodes
+│ ├── myshortcode.html
+│ └── myshortcode.section.mylayout.en.rss.xml
+├── docs
+│ ├── baseof.html
+│ ├── _shortcodes
+│ │ └── myshortcode.html
+│ └── api
+│ ├── mylayout.html
+│ ├── page.html
+│ └── _markup
+│ └── render-link.html
+└── tags
+ ├── taxonomy.html
+ ├── term.html
+ └── blue
+ └── list.html
+```
+
+[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
+[^internal]: The old way of doing it made it very hard/impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name.
+
+[Example folder structure]: #example-folder-structure
+[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
+[Page kinds]: https://gohugo.io/methods/page/kind/
+[Page path]: https://gohugo.io/methods/page/path/
+[template types]: /templates/types/
--- /dev/null
--- /dev/null
++---
++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" . }}
++ <p>Everything in this block will be wrapped.</p>
++ <p>{{ .Content | transform.Plainify | strings.Truncate 200 }}</p>
++{{ 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}
++<div class="wrapper-styling">
++ {{ templates.Inner . }}
++</div>
++```
++
++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 }}
++ <div class="grid-wrapper">
++ {{ 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) }}
++ <p>
++ {{ .page.Content | plainify | strings.Truncate 240 }}
++ </p>
++ {{ end }}
++ {{ end }}
++ {{ end }}
++ </div>
++{{ end }}
++```
++
++The section component provides a semantic container and an optional heading:
++
++```go-html-template {file="layouts/_partials/components/section.html" copy=true}
++<section class="content-section">
++ {{ with .label }}
++ <h2 class="section-label">{{ . }}</h2>
++ {{ end }}
++ <div class="section-content">
++ {{ templates.Inner . }}
++ </div>
++</section>
++```
++
++The column component manages layout width by applying a CSS class:
++
++```go-html-template {file="layouts/_partials/components/column.html" copy=true}
++<div class="{{ .class | default `column-default` }}">
++ {{ templates.Inner . }}
++</div>
++```
++
++The card component defines the visual boundary for the content:
++
++```go-html-template {file="layouts/_partials/components/card.html" copy=true}
++<div class="card">
++ {{ with .title }}
++ <h2 class="card-title">
++ {{ if $.url }}
++ <a href="{{ $.url }}">{{ . }}</a>
++ {{ else }}
++ {{ . }}
++ {{ end }}
++ </h2>
++ {{ end }}
++
++ <div class="card-body">
++ {{ templates.Inner . }}
++ </div>
++
++ {{ with .url }}
++ <div class="card-footer">
++ <a href="{{ . }}">Read more</a>
++ </div>
++ {{ end }}
++</div>
++```
++
++[`with`]: /functions/go-template/with/
--- /dev/null
- weight: 180
+---
+title: robots.txt template
+linkTitle: robots.txt templates
+description: Hugo can generate a customized robots.txt in the same way as any other template.
+categories: []
+keywords: []
++weight: 190
+aliases: [/extras/robots-txt/]
+---
+
+To generate a robots.txt file from a template, change the [site configuration]:
+
+{{< code-toggle file=hugo >}}
+enableRobotsTXT = true
+{{< /code-toggle >}}
+
+By default, Hugo generates robots.txt using an [embedded template].
+
+```text
+User-agent: *
+```
+
+Search engines that honor the Robots Exclusion Protocol will interpret this as permission to crawl everything on the site.
+
+## robots.txt template lookup order
+
+You may overwrite the internal template with a custom template. Hugo selects the template using this lookup order:
+
+1. `/layouts/robots.txt`
+1. `/themes/<THEME>/layouts/robots.txt`
+
+## robots.txt template example
+
+```text {file="layouts/robots.txt"}
+User-agent: *
+{{ range .Pages }}
+Disallow: {{ .RelPermalink }}
+{{ end }}
+```
+
+This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site.
+
+> [!note]
+> To create a robots.txt file without using a template:
+>
+> 1. Set `enableRobotsTXT` to `false` in the site configuration.
+> 1. Create a robots.txt file in the `static` directory.
+>
+> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your site.
+
+[embedded template]: <{{% eturl robots %}}>
+[site configuration]: /configuration/
--- /dev/null
- getcsv:
- dir: :cacheDir/:project
- maxAge: -1
- getjson:
- dir: :cacheDir/:project
- maxAge: -1
+chroma:
+ lexers:
+ - Aliases:
+ - abap
+ Name: ABAP
+ - Aliases:
+ - abnf
+ Name: ABNF
+ - Aliases:
+ - as
+ - actionscript
+ Name: ActionScript
+ - Aliases:
+ - as3
+ - actionscript3
+ Name: ActionScript 3
+ - Aliases:
+ - ada
+ - ada95
+ - ada2005
+ Name: Ada
+ - Aliases:
+ - agda
+ Name: Agda
+ - Aliases:
+ - al
+ Name: AL
+ - Aliases:
+ - alloy
+ Name: Alloy
+ - Aliases:
+ - ng2
+ Name: Angular2
+ - Aliases:
+ - antlr
+ Name: ANTLR
+ - Aliases:
+ - apacheconf
+ - aconf
+ - apache
+ Name: ApacheConf
+ - Aliases:
+ - apl
+ Name: APL
+ - Aliases:
+ - applescript
+ Name: AppleScript
+ - Aliases:
+ - aql
+ Name: ArangoDB AQL
+ - Aliases:
+ - arduino
+ Name: Arduino
+ - Aliases:
+ - armasm
+ Name: ArmAsm
+ - Aliases:
+ - atl
+ Name: ATL
+ - Aliases:
+ - autohotkey
+ - ahk
+ Name: AutoHotkey
+ - Aliases:
+ - autoit
+ Name: AutoIt
+ - Aliases:
+ - awk
+ - gawk
+ - mawk
+ - nawk
+ Name: Awk
+ - Aliases:
+ - ballerina
+ Name: Ballerina
+ - Aliases:
+ - bash
+ - sh
+ - ksh
+ - zsh
+ - shell
+ Name: Bash
+ - Aliases:
+ - bash-session
+ - console
+ - shell-session
+ Name: Bash Session
+ - Aliases:
+ - bat
+ - batch
+ - dosbatch
+ - winbatch
+ Name: Batchfile
+ - Aliases:
+ - beef
+ Name: Beef
+ - Aliases:
+ - bib
+ - bibtex
+ Name: BibTeX
+ - Aliases:
+ - bicep
+ Name: Bicep
+ - Aliases:
+ - blitzbasic
+ - b3d
+ - bplus
+ Name: BlitzBasic
+ - Aliases:
+ - bnf
+ Name: BNF
+ - Aliases:
+ - bqn
+ Name: BQN
+ - Aliases:
+ - brainfuck
+ - bf
+ Name: Brainfuck
+ - Aliases:
+ - c
+ Name: C
+ - Aliases:
+ - csharp
+ - 'c#'
+ Name: 'C#'
+ - Aliases:
+ - cpp
+ - c++
+ Name: C++
+ - Aliases:
+ - c3
+ Name: C3
+ - Aliases:
+ - caddyfile
+ - caddy
+ Name: Caddyfile
+ - Aliases:
+ - caddyfile-directives
+ - caddyfile-d
+ - caddy-d
+ Name: Caddyfile Directives
+ - Aliases:
+ - capnp
+ Name: Cap'n Proto
+ - Aliases:
+ - cassandra
+ - cql
+ Name: Cassandra CQL
+ - Aliases:
+ - ceylon
+ Name: Ceylon
+ - Aliases:
+ - cfengine3
+ - cf3
+ Name: CFEngine3
+ - Aliases:
+ - cfs
+ Name: cfstatement
+ - Aliases:
+ - chai
+ - chaiscript
+ Name: ChaiScript
+ - Aliases:
+ - chapel
+ - chpl
+ Name: Chapel
+ - Aliases:
+ - cheetah
+ - spitfire
+ Name: Cheetah
+ - Aliases:
+ - clojure
+ - clj
+ - edn
+ Name: Clojure
+ - Aliases:
+ - cmake
+ Name: CMake
+ - Aliases:
+ - cobol
+ Name: COBOL
+ - Aliases:
+ - coffee-script
+ - coffeescript
+ - coffee
+ Name: CoffeeScript
+ - Aliases:
+ - common-lisp
+ - cl
+ - lisp
+ Name: Common Lisp
+ - Aliases:
+ - coq
+ Name: Coq
+ - Aliases:
+ - core
+ Name: Core
+ - Aliases:
+ - cr
+ - crystal
+ Name: Crystal
+ - Aliases:
+ - css
+ Name: CSS
+ - Aliases:
+ - csv
+ Name: CSV
+ - Aliases:
+ - cue
+ Name: CUE
+ - Aliases:
+ - cython
+ - pyx
+ - pyrex
+ Name: Cython
+ - Aliases:
+ - d
+ Name: D
+ - Aliases:
+ - dart
+ Name: Dart
+ - Aliases:
+ - dax
+ Name: Dax
+ - Aliases:
+ - desktop
+ - desktop_entry
+ Name: Desktop file
+ - Aliases:
+ - devicetree
+ - dts
+ Name: Devicetree
+ - Aliases:
+ - diff
+ - udiff
+ Name: Diff
+ - Aliases:
+ - django
+ - jinja
+ Name: Django/Jinja
+ - Aliases:
+ - zone
+ - bind
+ Name: dns
+ - Aliases:
+ - docker
+ - dockerfile
+ - containerfile
+ Name: Docker
+ - Aliases:
+ - dtd
+ Name: DTD
+ - Aliases:
+ - dylan
+ Name: Dylan
+ - Aliases:
+ - ebnf
+ Name: EBNF
+ - Aliases:
+ - elixir
+ - ex
+ - exs
+ Name: Elixir
+ - Aliases:
+ - elm
+ Name: Elm
+ - Aliases:
+ - emacs
+ - elisp
+ - emacs-lisp
+ Name: EmacsLisp
+ - Aliases:
+ - erlang
+ Name: Erlang
+ - Aliases:
+ - factor
+ Name: Factor
+ - Aliases:
+ - fennel
+ - fnl
+ Name: Fennel
+ - Aliases:
+ - fish
+ - fishshell
+ Name: Fish
+ - Aliases:
+ - forth
+ Name: Forth
+ - Aliases:
+ - fortran
+ - f90
+ Name: Fortran
+ - Aliases:
+ - fortranfixed
+ Name: FortranFixed
+ - Aliases:
+ - fsharp
+ Name: FSharp
+ - Aliases:
+ - gas
+ - asm
+ Name: GAS
+ - Aliases:
+ - gdscript
+ - gd
+ Name: GDScript
+ - Aliases:
+ - gdscript3
+ - gd3
+ Name: GDScript3
+ - Aliases:
+ - gemtext
+ - gmi
+ - gmni
+ - gemini
+ Name: Gemtext
+ - Aliases:
+ - genshi
+ - kid
+ - xml+genshi
+ - xml+kid
+ Name: Genshi
+ - Aliases:
+ - html+genshi
+ - html+kid
+ Name: Genshi HTML
+ - Aliases:
+ - genshitext
+ Name: Genshi Text
+ - Aliases:
+ - cucumber
+ - Cucumber
+ - gherkin
+ - Gherkin
+ Name: Gherkin
+ - Aliases:
+ - gleam
+ Name: Gleam
+ - Aliases:
+ - glsl
+ Name: GLSL
+ - Aliases:
+ - gnuplot
+ Name: Gnuplot
+ - Aliases:
+ - go
+ - golang
+ Name: Go
+ - Aliases:
+ - go-html-template
+ Name: Go HTML Template
+ - Aliases:
+ - go-template
+ Name: Go Template
+ - Aliases:
+ - go-text-template
+ Name: Go Text Template
+ - Aliases:
+ - graphql
+ - graphqls
+ - gql
+ Name: GraphQL
+ - Aliases:
+ - groff
+ - nroff
+ - man
+ Name: Groff
+ - Aliases:
+ - groovy
+ Name: Groovy
+ - Aliases:
+ - handlebars
+ - hbs
+ Name: Handlebars
+ - Aliases:
+ - hare
+ Name: Hare
+ - Aliases:
+ - haskell
+ - hs
+ Name: Haskell
+ - Aliases:
+ - hx
+ - haxe
+ - hxsl
+ Name: Haxe
+ - Aliases:
+ - hcl
+ Name: HCL
+ - Aliases:
+ - hexdump
+ Name: Hexdump
+ - Aliases:
+ - hlb
+ Name: HLB
+ - Aliases:
+ - hlsl
+ Name: HLSL
+ - Aliases:
+ - holyc
+ Name: HolyC
+ - Aliases:
+ - html
+ Name: HTML
+ - Aliases:
+ - http
+ Name: HTTP
+ - Aliases:
+ - hylang
+ Name: Hy
+ - Aliases:
+ - idris
+ - idr
+ Name: Idris
+ - Aliases:
+ - igor
+ - igorpro
+ Name: Igor
+ - Aliases:
+ - ini
+ - cfg
+ - dosini
+ Name: INI
+ - Aliases:
+ - io
+ Name: Io
+ - Aliases:
+ - iscdhcpd
+ Name: ISCdhcpd
+ - Aliases:
+ - j
+ Name: J
+ - Aliases:
+ - janet
+ Name: Janet
+ - Aliases:
+ - java
+ Name: Java
+ - Aliases:
+ - js
+ - javascript
+ Name: JavaScript
+ - Aliases:
+ - json
+ Name: JSON
+ - Aliases:
+ - jsonata
+ Name: JSONata
+ - Aliases:
+ - jsonnet
+ Name: Jsonnet
+ - Aliases:
+ - julia
+ - jl
+ Name: Julia
+ - Aliases:
+ - jungle
+ Name: Jungle
+ - Aliases:
+ - kak
+ - kakoune
+ - kakrc
+ - kakscript
+ Name: Kakoune
+ - Aliases:
+ - kdl
+ Name: KDL
+ - Aliases:
+ - kotlin
+ Name: Kotlin
+ - Aliases:
+ - lean4
+ - lean
+ Name: Lean4
+ - Aliases:
+ - lighty
+ - lighttpd
+ Name: Lighttpd configuration file
+ - Aliases:
+ - llvm
+ Name: LLVM
+ - Aliases: null
+ Name: lox
+ - Aliases:
+ - lua
+ - luau
+ Name: Lua
+ - Aliases:
+ - make
+ - makefile
+ - mf
+ - bsdmake
+ Name: Makefile
+ - Aliases:
+ - mako
+ Name: Mako
+ - Aliases:
+ - md
+ - mkd
+ Name: markdown
+ - Aliases:
+ - mess
+ Name: Markless
+ - Aliases:
+ - mason
+ Name: Mason
+ - Aliases:
+ - materialize
+ - mzsql
+ Name: Materialize SQL dialect
+ - Aliases:
+ - mathematica
+ - mma
+ - nb
+ Name: Mathematica
+ - Aliases:
+ - matlab
+ Name: Matlab
+ - Aliases:
+ - mcfunction
+ - mcf
+ Name: MCFunction
+ - Aliases:
+ - meson
+ - meson.build
+ Name: Meson
+ - Aliases:
+ - metal
+ Name: Metal
+ - Aliases:
+ - µcad
+ Name: microcad
+ - Aliases:
+ - minizinc
+ - MZN
+ - mzn
+ Name: MiniZinc
+ - Aliases:
+ - mlir
+ Name: MLIR
+ - Aliases:
+ - modelica
+ Name: Modelica
+ - Aliases:
+ - modula2
+ - m2
+ Name: Modula-2
+ - Aliases:
+ - mojo
+ - 🔥
+ Name: Mojo
+ - Aliases:
+ - monkeyc
+ Name: MonkeyC
+ - Aliases:
+ - moonbit
+ - mbt
+ Name: MoonBit
+ - Aliases:
+ - moonscript
+ - moon
+ Name: MoonScript
+ - Aliases:
+ - morrowind
+ - mwscript
+ Name: MorrowindScript
+ - Aliases:
+ - myghty
+ Name: Myghty
+ - Aliases:
+ - mysql
+ - mariadb
+ Name: MySQL
+ - Aliases:
+ - nasm
+ Name: NASM
+ - Aliases:
+ - natural
+ Name: Natural
+ - Aliases:
+ - ndisasm
+ Name: NDISASM
+ - Aliases:
+ - newspeak
+ Name: Newspeak
+ - Aliases:
+ - nginx
+ Name: Nginx configuration file
+ - Aliases:
+ - nim
+ - nimrod
+ Name: Nim
+ - Aliases:
+ - nixos
+ - nix
+ Name: Nix
+ - Aliases:
+ - nsis
+ - nsi
+ - nsh
+ Name: NSIS
+ - Aliases:
+ - nu
+ Name: Nu
+ - Aliases:
+ - objective-c
+ - objectivec
+ - obj-c
+ - objc
+ Name: Objective-C
+ - Aliases:
+ - objectpascal
+ Name: ObjectPascal
+ - Aliases:
+ - ocaml
+ Name: OCaml
+ - Aliases:
+ - octave
+ Name: Octave
+ - Aliases:
+ - odin
+ Name: Odin
+ - Aliases:
+ - ones
+ - onesenterprise
+ - 1S
+ - 1S:Enterprise
+ Name: OnesEnterprise
+ - Aliases:
+ - openedge
+ - abl
+ - progress
+ - openedgeabl
+ Name: OpenEdge ABL
+ - Aliases:
+ - openscad
+ Name: OpenSCAD
+ - Aliases:
+ - org
+ - orgmode
+ Name: Org Mode
+ - Aliases:
+ - pacmanconf
+ Name: PacmanConf
+ - Aliases:
+ - perl
+ - pl
+ Name: Perl
+ - Aliases:
+ - php
+ - php3
+ - php4
+ - php5
+ Name: PHP
+ - Aliases:
+ - phtml
+ Name: PHTML
+ - Aliases:
+ - pig
+ Name: Pig
+ - Aliases:
+ - pkgconfig
+ Name: PkgConfig
+ - Aliases:
+ - plpgsql
+ Name: PL/pgSQL
+ - Aliases:
+ - text
+ - plain
+ - no-highlight
+ Name: plaintext
+ - Aliases:
+ - plutus-core
+ - plc
+ Name: Plutus Core
+ - Aliases:
+ - pony
+ Name: Pony
+ - Aliases:
+ - postgresql
+ - postgres
+ Name: PostgreSQL SQL dialect
+ - Aliases:
+ - postscript
+ - postscr
+ Name: PostScript
+ - Aliases:
+ - pov
+ Name: POVRay
+ - Aliases:
+ - powerquery
+ - pq
+ Name: PowerQuery
+ - Aliases:
+ - powershell
+ - posh
+ - ps1
+ - psm1
+ - psd1
+ - pwsh
+ Name: PowerShell
+ - Aliases:
+ - prolog
+ Name: Prolog
+ - Aliases:
+ - promela
+ Name: Promela
+ - Aliases:
+ - promql
+ Name: PromQL
+ - Aliases:
+ - java-properties
+ Name: properties
+ - Aliases:
+ - protobuf
+ - proto
+ Name: Protocol Buffer
+ - Aliases:
+ - txtpb
+ Name: Protocol Buffer Text Format
+ - Aliases:
+ - prql
+ Name: PRQL
+ - Aliases:
+ - psl
+ Name: PSL
+ - Aliases:
+ - puppet
+ Name: Puppet
+ - Aliases:
+ - python
+ - py
+ - sage
+ - python3
+ - py3
+ - starlark
+ Name: Python
+ - Aliases:
+ - python2
+ - py2
+ Name: Python 2
+ - Aliases:
+ - qbasic
+ - basic
+ Name: QBasic
+ - Aliases:
+ - qml
+ - qbs
+ Name: QML
+ - Aliases:
+ - splus
+ - s
+ - r
+ Name: R
+ - Aliases:
+ - racket
+ - rkt
+ Name: Racket
+ - Aliases:
+ - ragel
+ Name: Ragel
+ - Aliases:
+ - perl6
+ - pl6
+ - raku
+ Name: Raku
+ - Aliases:
+ - jsx
+ - react
+ Name: react
+ - Aliases:
+ - reason
+ - reasonml
+ Name: ReasonML
+ - Aliases:
+ - registry
+ Name: reg
+ - Aliases:
+ - rego
+ Name: Rego
+ - Aliases:
+ - rst
+ - rest
+ - restructuredtext
+ Name: reStructuredText
+ - Aliases:
+ - rexx
+ - arexx
+ Name: Rexx
+ - Aliases:
+ - rgbasm
+ Name: RGBDS Assembly
+ - Aliases:
+ - ring
+ Name: Ring
+ - Aliases:
+ - SQLRPGLE
+ - RPG IV
+ Name: RPGLE
+ - Aliases:
+ - spec
+ Name: RPMSpec
+ - Aliases:
+ - rb
+ - ruby
+ - duby
+ Name: Ruby
+ - Aliases:
+ - rust
+ - rs
+ Name: Rust
+ - Aliases:
+ - sas
+ Name: SAS
+ - Aliases:
+ - sass
+ Name: Sass
+ - Aliases:
+ - scala
+ Name: Scala
+ - Aliases:
+ - scheme
+ - scm
+ Name: Scheme
+ - Aliases:
+ - scilab
+ Name: Scilab
+ - Aliases:
+ - scss
+ Name: SCSS
+ - Aliases:
+ - sed
+ - gsed
+ - ssed
+ Name: Sed
+ - Aliases:
+ - sieve
+ Name: Sieve
+ - Aliases:
+ - smali
+ Name: Smali
+ - Aliases:
+ - smalltalk
+ - squeak
+ - st
+ Name: Smalltalk
+ - Aliases:
+ - smarty
+ Name: Smarty
+ - Aliases:
+ - snbt
+ Name: SNBT
+ - Aliases:
+ - snobol
+ Name: Snobol
+ - Aliases:
+ - sol
+ - solidity
+ Name: Solidity
+ - Aliases:
+ - sp
+ Name: SourcePawn
+ - Aliases:
+ - sparql
+ Name: SPARQL
+ - Aliases:
+ - sql
+ Name: SQL
+ - Aliases:
+ - squidconf
+ - squid.conf
+ - squid
+ Name: SquidConf
+ - Aliases:
+ - sml
+ Name: Standard ML
+ - Aliases: null
+ Name: stas
+ - Aliases:
+ - stylus
+ Name: Stylus
+ - Aliases:
+ - svelte
+ Name: Svelte
+ - Aliases:
+ - swift
+ Name: Swift
+ - Aliases:
+ - systemd
+ Name: SYSTEMD
+ - Aliases:
+ - systemverilog
+ - sv
+ Name: systemverilog
+ - Aliases:
+ - tablegen
+ Name: TableGen
+ - Aliases:
+ - tal
+ - uxntal
+ Name: Tal
+ - Aliases:
+ - tasm
+ Name: TASM
+ - Aliases:
+ - tcl
+ Name: Tcl
+ - Aliases:
+ - tcsh
+ - csh
+ Name: Tcsh
+ - Aliases:
+ - termcap
+ Name: Termcap
+ - Aliases:
+ - terminfo
+ Name: Terminfo
+ - Aliases:
+ - terraform
+ - tf
+ - hcl
+ Name: Terraform
+ - Aliases:
+ - tex
+ - latex
+ Name: TeX
+ - Aliases:
+ - thrift
+ Name: Thrift
+ - Aliases:
+ - toml
+ Name: TOML
+ - Aliases:
+ - tradingview
+ - tv
+ Name: TradingView
+ - Aliases:
+ - tsql
+ - t-sql
+ Name: Transact-SQL
+ - Aliases:
+ - turing
+ Name: Turing
+ - Aliases:
+ - turtle
+ Name: Turtle
+ - Aliases:
+ - twig
+ Name: Twig
+ - Aliases:
+ - ts
+ - tsx
+ - typescript
+ Name: TypeScript
+ - Aliases:
+ - typoscript
+ Name: TypoScript
+ - Aliases:
+ - typoscriptcssdata
+ Name: TypoScriptCssData
+ - Aliases:
+ - typoscripthtmldata
+ Name: TypoScriptHtmlData
+ - Aliases:
+ - typst
+ Name: Typst
+ - Aliases: null
+ Name: ucode
+ - Aliases:
+ - v
+ - vlang
+ Name: V
+ - Aliases:
+ - vsh
+ - vshell
+ Name: V shell
+ - Aliases:
+ - vala
+ - vapi
+ Name: Vala
+ - Aliases:
+ - vb.net
+ - vbnet
+ Name: VB.net
+ - Aliases:
+ - verilog
+ - v
+ Name: verilog
+ - Aliases:
+ - vhdl
+ Name: VHDL
+ - Aliases:
+ - vhs
+ - tape
+ - cassette
+ Name: VHS
+ - Aliases:
+ - vim
+ Name: VimL
+ - Aliases:
+ - vue
+ - vuejs
+ Name: vue
+ - Aliases: null
+ Name: WDTE
+ - Aliases:
+ - wast
+ - wat
+ Name: WebAssembly Text Format
+ - Aliases:
+ - wgsl
+ Name: WebGPU Shading Language
+ - Aliases:
+ - vtt
+ Name: WebVTT
+ - Aliases:
+ - whiley
+ Name: Whiley
+ - Aliases:
+ - xml
+ Name: XML
+ - Aliases:
+ - xorg.conf
+ Name: Xorg
+ - Aliases:
+ - yaml
+ Name: YAML
+ - Aliases:
+ - yang
+ Name: YANG
+ - Aliases:
+ - z80
+ Name: Z80 Assembly
+ - Aliases:
+ - zed
+ Name: Zed
+ - Aliases:
+ - zig
+ Name: Zig
+ styles:
+ - RPGLE
+ - abap
+ - algol
+ - algol_nu
+ - arduino
+ - ashen
+ - aura-theme-dark
+ - aura-theme-dark-soft
+ - autumn
+ - average
+ - base16-snazzy
+ - borland
+ - bw
+ - catppuccin-frappe
+ - catppuccin-latte
+ - catppuccin-macchiato
+ - catppuccin-mocha
+ - colorful
+ - doom-one
+ - doom-one2
+ - dracula
+ - emacs
+ - evergarden
+ - friendly
+ - fruity
+ - github
+ - github-dark
+ - gruvbox
+ - gruvbox-light
+ - hr_high_contrast
+ - hrdark
+ - igor
+ - lovelace
+ - manni
+ - modus-operandi
+ - modus-vivendi
+ - monokai
+ - monokailight
+ - murphy
+ - native
+ - nord
+ - nordic
+ - onedark
+ - onesenterprise
+ - paraiso-dark
+ - paraiso-light
+ - pastie
+ - perldoc
+ - pygments
+ - rainbow_dash
+ - rose-pine
+ - rose-pine-dawn
+ - rose-pine-moon
+ - rrt
+ - solarized-dark
+ - solarized-dark256
+ - solarized-light
+ - swapoff
+ - tango
+ - tokyonight-day
+ - tokyonight-moon
+ - tokyonight-night
+ - tokyonight-storm
+ - trac
+ - vim
+ - vs
+ - vulcan
+ - witchhazel
+ - xcode
+ - xcode-dark
+config:
+ HTTPCache:
+ cache:
+ for:
+ excludes:
+ - '**'
+ includes: null
+ polls:
+ - disable: true
+ for:
+ excludes: null
+ includes:
+ - '**'
+ high: 0s
+ low: 0s
+ respectCacheControlNoStoreInRequest: true
+ respectCacheControlNoStoreInResponse: false
+ archeTypeDir: archetypes
+ assetDir: assets
+ author: {}
+ baseURL: ''
+ build:
+ buildStats:
+ disableClasses: false
+ disableIDs: false
+ disableTags: false
+ enable: false
+ cacheBusters:
+ - source: '(postcss|tailwind)\.config\.js'
+ target: (css|styles|scss|sass)
+ noJSConfigInAssets: false
+ useResourceCacheWhen: fallback
+ buildDrafts: false
+ buildExpired: false
+ buildFuture: false
+ cacheDir: ''
+ caches:
+ assets:
+ dir: :resourceDir/_gen
+ maxAge: -1
- paginate: 0
- paginatePath: ''
+ getresource:
+ dir: :cacheDir/:project
+ maxAge: -1
+ images:
+ dir: :resourceDir/_gen
+ maxAge: -1
+ misc:
+ dir: :cacheDir/:project
+ maxAge: -1
+ modulequeries:
+ dir: :cacheDir/modules
+ maxAge: 24h
+ modules:
+ dir: :cacheDir/modules
+ maxAge: -1
+ canonifyURLs: false
+ capitalizeListTitles: true
+ cascade: null
+ cleanDestinationDir: false
+ contentDir: content
+ contentTypes:
+ text/asciidoc: {}
+ text/html: {}
+ text/markdown: {}
+ text/org: {}
+ text/pandoc: {}
+ text/rst: {}
+ copyright: ''
+ dataDir: data
+ defaultContentLanguage: en
+ defaultContentLanguageInSubdir: false
+ defaultContentRole: guest
+ defaultContentRoleInSubdir: false
+ defaultContentVersion: ''
+ defaultContentVersionInSubdir: false
+ defaultOutputFormat: html
+ deployment:
+ confirm: false
+ dryRun: false
+ force: false
+ invalidateCDN: true
+ matchers: null
+ maxDeletes: 256
+ order: null
+ target: ''
+ targets: null
+ workers: 10
+ disableAliases: false
+ disableDefaultLanguageRedirect: false
+ disableDefaultSiteRedirect: false
+ disableHugoGeneratorInject: false
+ disableKinds: null
+ disableLanguages: null
+ disableLiveReload: false
+ disablePathToLower: false
+ enableEmoji: false
+ enableGitInfo: false
+ enableMissingTranslationPlaceholders: false
+ enableRobotsTXT: false
+ environment: production
+ frontmatter:
+ date:
+ - date
+ - publishdate
+ - pubdate
+ - published
+ - lastmod
+ - modified
+ expiryDate:
+ - expirydate
+ - unpublishdate
+ lastmod:
+ - :git
+ - lastmod
+ - modified
+ - date
+ - publishdate
+ - pubdate
+ - published
+ publishDate:
+ - publishdate
+ - pubdate
+ - published
+ - date
+ hasCJKLanguage: false
+ i18nDir: i18n
+ ignoreCache: false
+ ignoreFiles: null
+ ignoreLogs: null
+ ignoreVendorPaths: ''
+ imaging:
+ bgColor: '#ffffff'
+ compression: lossy
+ hint: photo
+ quality: 75
+ resampleFilter: box
+ webp:
+ method: 4
+ useSharpYuv: true
+ languageCode: ''
+ languages:
+ en:
+ disabled: false
+ languageCode: ''
+ languageDirection: ''
+ languageName: ''
+ title: ''
+ weight: 0
+ layoutDir: layouts
+ mainSections: null
+ markup:
+ asciiDocExt:
+ attributes: {}
+ backend: html5
+ extensions: []
+ failureLevel: fatal
+ noHeaderOrFooter: true
+ preserveTOC: false
+ safeMode: unsafe
+ sectionNumbers: false
+ trace: false
+ verbose: false
+ workingFolderCurrent: false
+ defaultMarkdownHandler: goldmark
+ goldmark:
+ duplicateResourceFiles: false
+ extensions:
+ cjk:
+ eastAsianLineBreaks: false
+ eastAsianLineBreaksStyle: simple
+ enable: false
+ escapedSpace: false
+ definitionList: true
+ extras:
+ delete:
+ enable: false
+ insert:
+ enable: false
+ mark:
+ enable: false
+ subscript:
+ enable: false
+ superscript:
+ enable: false
+ footnote:
+ backlinkHTML: '↩︎'
+ enable: true
+ enableAutoIDPrefix: false
+ linkify: true
+ linkifyProtocol: https
+ passthrough:
+ delimiters:
+ block: []
+ inline: []
+ enable: false
+ strikethrough: true
+ table: true
+ taskList: true
+ typographer:
+ apostrophe: '’'
+ disable: false
+ ellipsis: '…'
+ emDash: '—'
+ enDash: '–'
+ leftAngleQuote: '«'
+ leftDoubleQuote: '“'
+ leftSingleQuote: '‘'
+ rightAngleQuote: '»'
+ rightDoubleQuote: '”'
+ rightSingleQuote: '’'
+ parser:
+ attribute:
+ block: false
+ title: true
+ autoDefinitionTermID: false
+ autoHeadingID: true
+ autoIDType: github
+ wrapStandAloneImageWithinParagraph: true
+ renderHooks:
+ image:
+ enableDefault: false
+ useEmbedded: auto
+ link:
+ enableDefault: false
+ useEmbedded: auto
+ renderer:
+ hardWraps: false
+ unsafe: false
+ xhtml: false
+ highlight:
+ anchorLineNos: false
+ codeFences: true
+ guessSyntax: false
+ hl_Lines: ''
+ hl_inline: false
+ lineAnchors: ''
+ lineNoStart: 1
+ lineNos: false
+ lineNumbersInTable: true
+ noClasses: true
+ style: monokai
+ tabWidth: 4
+ wrapperClass: highlight
+ tableOfContents:
+ endLevel: 3
+ ordered: false
+ startLevel: 2
+ mediaTypes:
+ application/json:
+ delimiter: .
+ suffixes:
+ - json
+ application/manifest+json:
+ delimiter: .
+ suffixes:
+ - webmanifest
+ application/octet-stream:
+ delimiter: .
+ application/pdf:
+ delimiter: .
+ suffixes:
+ - pdf
+ application/rss+xml:
+ delimiter: .
+ suffixes:
+ - xml
+ - rss
+ application/toml:
+ delimiter: .
+ suffixes:
+ - toml
+ application/wasm:
+ delimiter: .
+ suffixes:
+ - wasm
+ application/xml:
+ delimiter: .
+ suffixes:
+ - xml
+ application/yaml:
+ delimiter: .
+ suffixes:
+ - yaml
+ - yml
+ font/otf:
+ delimiter: .
+ suffixes:
+ - otf
+ font/ttf:
+ delimiter: .
+ suffixes:
+ - ttf
+ image/bmp:
+ delimiter: .
+ suffixes:
+ - bmp
+ image/gif:
+ delimiter: .
+ suffixes:
+ - gif
+ image/jpeg:
+ delimiter: .
+ suffixes:
+ - jpg
+ - jpeg
+ - jpe
+ - jif
+ - jfif
+ image/png:
+ delimiter: .
+ suffixes:
+ - png
+ image/svg+xml:
+ delimiter: .
+ suffixes:
+ - svg
+ image/tiff:
+ delimiter: .
+ suffixes:
+ - tif
+ - tiff
+ image/webp:
+ delimiter: .
+ suffixes:
+ - webp
+ text/asciidoc:
+ delimiter: .
+ suffixes:
+ - adoc
+ - asciidoc
+ - ad
+ text/calendar:
+ delimiter: .
+ suffixes:
+ - ics
+ text/css:
+ delimiter: .
+ suffixes:
+ - css
+ text/csv:
+ delimiter: .
+ suffixes:
+ - csv
+ text/html:
+ delimiter: .
+ suffixes:
+ - html
+ - htm
+ text/javascript:
+ delimiter: .
+ suffixes:
+ - js
+ - jsm
+ - mjs
+ text/jsx:
+ delimiter: .
+ suffixes:
+ - jsx
+ text/markdown:
+ delimiter: .
+ suffixes:
+ - md
+ - mdown
+ - markdown
+ text/org:
+ delimiter: .
+ suffixes:
+ - org
+ text/pandoc:
+ delimiter: .
+ suffixes:
+ - pandoc
+ - pdc
+ text/plain:
+ delimiter: .
+ suffixes:
+ - txt
+ text/rst:
+ delimiter: .
+ suffixes:
+ - rst
+ text/tsx:
+ delimiter: .
+ suffixes:
+ - tsx
+ text/typescript:
+ delimiter: .
+ suffixes:
+ - ts
+ text/x-gotmpl:
+ delimiter: .
+ suffixes:
+ - gotmpl
+ text/x-sass:
+ delimiter: .
+ suffixes:
+ - sass
+ text/x-scss:
+ delimiter: .
+ suffixes:
+ - scss
+ video/3gpp:
+ delimiter: .
+ suffixes:
+ - 3gpp
+ - 3gp
+ video/mp4:
+ delimiter: .
+ suffixes:
+ - mp4
+ video/mpeg:
+ delimiter: .
+ suffixes:
+ - mpg
+ - mpeg
+ video/ogg:
+ delimiter: .
+ suffixes:
+ - ogv
+ video/webm:
+ delimiter: .
+ suffixes:
+ - webm
+ video/x-msvideo:
+ delimiter: .
+ suffixes:
+ - avi
+ menus: {}
+ minify:
+ disableCSS: false
+ disableHTML: false
+ disableJS: false
+ disableJSON: false
+ disableSVG: false
+ disableXML: false
+ minifyOutput: false
+ tdewolff:
+ css:
+ inline: false
+ precision: 0
+ version: 0
+ html:
+ keepComments: false
+ keepConditionalComments: false
+ keepDefaultAttrVals: true
+ keepDocumentTags: true
+ keepEndTags: true
+ keepQuotes: false
+ keepSpecialComments: true
+ keepWhitespace: false
+ templateDelims:
+ - ''
+ - ''
+ js:
+ keepVarNames: false
+ precision: 0
+ version: 2022
+ json:
+ keepNumbers: false
+ precision: 0
+ svg:
+ keepComments: false
+ precision: 0
+ xml:
+ keepWhitespace: false
+ module:
+ auth: ''
+ hugoVersion:
+ extended: false
+ max: ''
+ min: ''
+ imports: null
+ mounts:
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: content
+ target: content
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: data
+ target: data
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: layouts
+ target: layouts
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: i18n
+ target: i18n
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: archetypes
+ target: archetypes
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: assets
+ target: assets
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: static
+ target: static
+ noProxy: none
+ noVendor: ''
+ params: null
+ private: '*.*'
+ proxy: direct
+ replacements: null
+ vendorClosest: false
+ workspace: 'off'
+ newContentEditor: ''
+ noBuildLock: false
+ noChmod: false
+ noTimes: false
+ outputFormats:
+ '404':
+ baseName: ''
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: true
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: true
+ weight: 0
+ alias:
+ baseName: ''
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: true
+ weight: 0
+ amp:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: amp
+ permalinkable: true
+ protocol: ''
+ rel: amphtml
+ root: false
+ ugly: false
+ weight: 0
+ calendar:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/calendar
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: webcal://
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ css:
+ baseName: styles
+ isHTML: false
+ isPlainText: true
+ mediaType: text/css
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: stylesheet
+ root: false
+ ugly: false
+ weight: 0
+ csv:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/csv
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ gotmpl:
+ baseName: ''
+ isHTML: false
+ isPlainText: true
+ mediaType: text/x-gotmpl
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: false
+ weight: 0
+ html:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: true
+ protocol: ''
+ rel: canonical
+ root: false
+ ugly: false
+ weight: 10
+ json:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: application/json
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ markdown:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/markdown
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ robots:
+ baseName: robots
+ isHTML: false
+ isPlainText: true
+ mediaType: text/plain
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: true
+ ugly: false
+ weight: 0
+ rss:
+ baseName: index
+ isHTML: false
+ isPlainText: false
+ mediaType: application/rss+xml
+ noUgly: true
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ sitemap:
+ baseName: sitemap
+ isHTML: false
+ isPlainText: false
+ mediaType: application/xml
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: sitemap
+ root: false
+ ugly: true
+ weight: 0
+ sitemapindex:
+ baseName: sitemap
+ isHTML: false
+ isPlainText: false
+ mediaType: application/xml
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: sitemap
+ root: true
+ ugly: true
+ weight: 0
+ webappmanifest:
+ baseName: manifest
+ isHTML: false
+ isPlainText: true
+ mediaType: application/manifest+json
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: manifest
+ root: false
+ ugly: false
+ weight: 0
+ outputs:
+ home:
+ - html
+ - rss
+ page:
+ - html
+ rss:
+ - rss
+ section:
+ - html
+ - rss
+ taxonomy:
+ - html
+ - rss
+ term:
+ - html
+ - rss
+ page:
+ nextPrevInSectionSortOrder: desc
+ nextPrevSortOrder: desc
-
+ pagination:
+ disableAliases: false
+ pagerSize: 10
+ path: page
+ panicOnWarning: false
+ params: {}
+ permalinks:
+ page: {}
+ section: {}
+ taxonomy: {}
+ term: {}
+ pluralizeListTitles: true
+ printI18nWarnings: false
+ printPathWarnings: false
+ printUnusedTemplates: false
+ privacy:
+ disqus:
+ disable: false
+ googleAnalytics:
+ disable: false
+ respectDoNotTrack: true
+ instagram:
+ disable: false
+ simple: false
+ vimeo:
+ disable: false
+ enableDNT: false
+ simple: false
+ x:
+ disable: false
+ enableDNT: false
+ simple: false
+ youTube:
+ disable: false
+ privacyEnhanced: false
+ publishDir: public
+ refLinksErrorLevel: ''
+ refLinksNotFoundURL: ''
+ related:
+ includeNewer: false
+ indices:
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: keywords
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 100
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: date
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 10
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: tags
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 80
+ threshold: 80
+ toLower: false
+ relativeURLs: false
+ removePathAccents: false
+ renderSegments: null
+ resourceDir: resources
+ roles:
+ guest:
+ weight: 0
+ sectionPagesMenu: ''
+ security:
+ enableInlineShortcodes: false
+ exec:
+ allow:
+ - ^(dart-)?sass(-embedded)?$
+ - ^go$
+ - ^git$
+ - ^npx$
+ - ^postcss$
+ - ^tailwindcss$
+ osEnv:
+ - '(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE|PROGRAMDATA)$'
+ funcs:
+ getenv:
+ - ^HUGO_
+ - ^CI$
+ http:
+ mediaTypes: null
+ methods:
+ - (?i)GET|POST
+ urls:
+ - .*
+ segments: {}
+ server:
+ headers: null
+ redirects:
+ - force: false
+ from: /**
+ fromHeaders: null
+ fromRe: ''
+ status: 404
+ to: /404.html
+ services:
+ disqus:
+ shortname: ''
+ googleAnalytics:
+ id: ''
+ rss:
+ limit: -1
+ x:
+ disableInlineCSS: false
+ sitemap:
+ changeFreq: ''
+ disable: false
+ filename: sitemap.xml
+ priority: -1
+ social: null
+ staticDir:
+ - static
+ staticDir0: null
+ staticDir1: null
+ staticDir10: null
+ staticDir2: null
+ staticDir3: null
+ staticDir4: null
+ staticDir5: null
+ staticDir6: null
+ staticDir7: null
+ staticDir8: null
+ staticDir9: null
+ summaryLength: 70
+ taxonomies:
+ category: categories
+ tag: tags
+ templateMetrics: false
+ templateMetricsHints: false
+ theme: null
+ themesDir: themes
+ timeZone: ''
+ timeout: 60s
+ title: ''
+ titleCaseStyle: AP
+ uglyURLs: {}
+ versions:
+ v1.0.0:
+ weight: 0
+ workingDir: ''
+config_helpers:
+ mergeStrategy:
+ build:
+ _merge: none
+ caches:
+ _merge: none
+ cascade:
+ _merge: none
+ contenttypes:
+ _merge: none
+ deployment:
+ _merge: none
+ frontmatter:
+ _merge: none
+ httpcache:
+ _merge: none
+ imaging:
+ _merge: none
+ languages:
+ _merge: none
+ en:
+ _merge: none
+ menus:
+ _merge: shallow
+ params:
+ _merge: deep
+ markup:
+ _merge: none
+ mediatypes:
+ _merge: shallow
+ menus:
+ _merge: shallow
+ minify:
+ _merge: none
+ module:
+ _merge: none
+ outputformats:
+ _merge: shallow
+ outputs:
+ _merge: none
+ page:
+ _merge: none
+ pagination:
+ _merge: none
+ params:
+ _merge: deep
+ permalinks:
+ _merge: none
+ privacy:
+ _merge: none
+ related:
+ _merge: none
+ roles:
+ _merge: none
+ security:
+ _merge: none
+ segments:
+ _merge: none
+ server:
+ _merge: none
+ services:
+ _merge: none
+ sitemap:
+ _merge: none
+ taxonomies:
+ _merge: none
+ versions:
+ _merge: none
+output:
+ layouts: {}
+tpl:
+ funcs:
+ cast:
+ ToFloat:
+ Aliases:
+ - float
+ Args:
+ - v
+ Description: ToFloat converts v to a float.
+ Examples:
+ - - '{{ "1234" | float | printf "%T" }}'
+ - float64
+ ToInt:
+ Aliases:
+ - int
+ Args:
+ - v
+ Description: ToInt converts v to an int.
+ Examples:
+ - - '{{ "1234" | int | printf "%T" }}'
+ - int
+ ToString:
+ Aliases:
+ - string
+ Args:
+ - v
+ Description: ToString converts v to a string.
+ Examples:
+ - - '{{ 1234 | string | printf "%T" }}'
+ - string
+ collections:
+ After:
+ Aliases:
+ - after
+ Args:
+ - 'n'
+ - l
+ Description: After returns all the items after the first n items in list l.
+ Examples: []
+ Append:
+ Aliases:
+ - append
+ Args:
+ - args
+ 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:
+ Aliases:
+ - apply
+ Args:
+ - ctx
+ - c
+ - fname
+ - args
+ Description: Apply takes an array or slice c and returns a new slice with the function fname applied over it.
+ Examples: []
+ Complement:
+ Aliases:
+ - complement
+ Args:
+ - ls
+ 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") }}'
+ - '[a f]'
+ D:
+ Aliases: null
+ Args:
+ - seed
+ - 'n'
+ - hi
+ Description: 'D returns a sorted slice of unique random integers in the half-open interval\n[0, hi) using the provided seed value. The number of elements in the\nresulting slice is n or hi, whichever is less.\n\nIf n <= hi, it returns a sorted random sample of size n using J. S. Vitter’s\nMethod D for sequential random sampling.\n\nIf n > hi, it returns the full, sorted range [0, hi) of size hi.\n\nIf n == 0 or hi == 0, it returns an empty slice.\n\nReference:\n\n\tJ. S. Vitter, "An efficient algorithm for sequential random sampling," ACM Trans. Math. Softw., vol. 11, no. 1, pp. 37–57, 1985.\n\tSee also: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/'
+ Examples: []
+ Delimit:
+ Aliases:
+ - delimit
+ Args:
+ - ctx
+ - l
+ - sep
+ - last
+ Description: |-
+ Delimit takes a given list l and returns a string delimited by sep.
+ If last is passed to the function, it will be used as the final delimiter.
+ Examples:
+ - - '{{ delimit (slice "A" "B" "C") ", " " and " }}'
+ - A, B and C
+ Dictionary:
+ Aliases:
+ - dict
+ Args:
+ - values
+ Description: |-
+ Dictionary creates a new map from the given parameters by
+ treating values as key-value pairs. The number of values must be even.
+ The keys can be string slices, which will create the needed nested structure.
+ Examples: []
+ First:
+ Aliases:
+ - first
+ Args:
+ - limit
+ - l
+ Description: First returns the first limit items in list l.
+ Examples: []
+ Group:
+ Aliases:
+ - group
+ Args:
+ - key
+ - items
+ Description: |-
+ Group groups a set of items by the given key.
+ This is currently only supported for Pages.
+ Examples: []
+ In:
+ Aliases:
+ - in
+ Args:
+ - l
+ - v
+ Description: In returns whether v is in the list l. l may be an array or slice.
+ Examples:
+ - - '{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}'
+ - Substring found!
+ Index:
+ Aliases:
+ - index
+ Args:
+ - item
+ - args
+ Description: |-
+ 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:
+ Aliases:
+ - intersect
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Intersect returns the common elements in the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ Examples: []
+ IsSet:
+ Aliases:
+ - isSet
+ - isset
+ Args:
+ - c
+ - key
+ Description: |-
+ IsSet returns whether a given array, channel, slice, or map in c has the given key
+ defined.
+ Examples: []
+ KeyVals:
+ Aliases:
+ - keyVals
+ Args:
+ - key
+ - values
+ Description: KeyVals creates a key and values wrapper.
+ Examples:
+ - - '{{ keyVals "key" "a" "b" }}'
+ - 'key: [a b]'
+ Last:
+ Aliases:
+ - last
+ Args:
+ - limit
+ - l
+ Description: Last returns the last limit items in the list l.
+ Examples: []
+ Merge:
+ Aliases:
+ - merge
+ Args:
+ - params
+ 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 }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") (dict "title" "Hugo Rocks!") | sort }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") (dict "title" "Hugo Rocks!") (dict "extra" "For reals!") | sort }}'
+ - '[Yes, Hugo Rocks! For reals! Hugo Rocks!]'
+ NewScratch:
+ Aliases:
+ - newScratch
+ Args: null
+ Description: |-
+ NewScratch creates a new Scratch which can be used to store values in a
+ thread safe way.
+ Examples:
+ - - '{{ $scratch := newScratch }}{{ $scratch.Add "b" 2 }}{{ $scratch.Add "b" 2 }}{{ $scratch.Get "b" }}'
+ - '4'
+ Querify:
+ Aliases:
+ - querify
+ Args:
+ - params
+ Description: |-
+ Querify returns a URL query string composed of the given key-value pairs,
+ encoded and sorted by key.
+ Examples:
+ - - '{{ (querify "foo" 1 "bar" 2 "baz" "with spaces" "qux" "this&that=those") | safeHTML }}'
+ - bar=2&baz=with+spaces&foo=1&qux=this%26that%3Dthose
+ - - <a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
+ - <a href="https://www.google.com?page=3&q=test">Search</a>
+ - - '{{ slice "foo" 1 "bar" 2 | querify | safeHTML }}'
+ - bar=2&foo=1
+ Reverse:
+ Aliases: null
+ Args:
+ - l
+ Description: Reverse creates a copy of the list l and reverses it.
+ Examples: []
+ Seq:
+ Aliases:
+ - seq
+ Args:
+ - 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
+ 1 4 => 1, 2, 3, 4
+ 1 -2 => 1, 0, -1, -2
+ Examples:
+ - - '{{ seq 3 }}'
+ - '[1 2 3]'
+ Shuffle:
+ Aliases:
+ - shuffle
+ Args:
+ - l
+ Description: Shuffle returns list l in a randomized order.
+ Examples: []
+ Slice:
+ Aliases:
+ - slice
+ Args:
+ - args
+ Description: Slice returns a slice of all passed arguments.
+ Examples:
+ - - '{{ slice "B" "C" "A" | sort }}'
+ - '[A B C]'
+ Sort:
+ Aliases:
+ - sort
+ Args:
+ - ctx
+ - l
+ - args
+ Description: Sort returns a sorted copy of the list l.
+ Examples: []
+ SymDiff:
+ Aliases:
+ - symdiff
+ Args:
+ - s2
+ - s1
+ Description: |-
+ SymDiff returns the symmetric difference of s1 and s2.
+ Arguments must be either a slice or an array of comparable types.
+ Examples:
+ - - '{{ slice 1 2 3 | symdiff (slice 3 4) }}'
+ - '[1 2 4]'
+ Union:
+ Aliases:
+ - union
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Union returns the union of the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ If l1 and l2 aren't of the same type then l1 will be returned.
+ If either l1 or l2 is nil then the non-nil list will be returned.
+ Examples:
+ - - '{{ union (slice 1 2 3) (slice 3 4 5) }}'
+ - '[1 2 3 4 5]'
+ Uniq:
+ Aliases:
+ - uniq
+ Args:
+ - l
+ Description: Uniq returns a new list with duplicate elements in the list l removed.
+ Examples:
+ - - '{{ slice 1 2 3 2 | uniq }}'
+ - '[1 2 3]'
+ Where:
+ Aliases:
+ - where
+ Args:
+ - ctx
+ - c
+ - key
+ - args
+ Description: Where returns a filtered subset of collection c.
+ Examples: []
+ compare:
+ Conditional:
+ Aliases:
+ - cond
+ Args:
+ - cond
+ - v1
+ - v2
+ Description: |-
+ Conditional can be used as a ternary operator.
- FNV32a:
- Aliases: null
- Args:
- - v
- Description: 'FNV32a hashes v using fnv32a algorithm.\n<docsmeta>{"newIn": "0.98.0" }</docsmeta>'
- Examples: []
++
+ It returns v1 if cond is true, else v2.
+ Examples:
+ - - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}'
+ - 2+2 is 4
+ Default:
+ Aliases:
+ - default
+ Args:
+ - defaultv
+ - givenv
+ Description: |-
+ Default checks whether a givenv is set and returns the default value defaultv if it
+ is not. "Set" in this context means non-zero for numeric types and times;
+ non-zero length for strings, arrays, slices, and maps;
+ any boolean or struct value; or non-nil for any other types.
+ Examples:
+ - - '{{ "Hugo Rocks!" | default "Hugo Rules!" }}'
+ - Hugo Rocks!
+ - - '{{ "" | default "Hugo Rules!" }}'
+ - Hugo Rules!
+ Eq:
+ Aliases:
+ - eq
+ Args:
+ - first
+ - others
+ Description: Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3 || arg1 == arg4.
+ Examples:
+ - - '{{ if eq .Section "blog" }}current-section{{ end }}'
+ - current-section
+ Ge:
+ Aliases:
+ - ge
+ Args:
+ - first
+ - others
+ Description: Ge returns the boolean truth of arg1 >= arg2 && arg1 >= arg3 && arg1 >= arg4.
+ Examples:
+ - - '{{ if ge hugo.Version "0.80" }}Reasonable new Hugo version!{{ end }}'
+ - Reasonable new Hugo version!
+ Gt:
+ Aliases:
+ - gt
+ Args:
+ - first
+ - others
+ Description: Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 && arg1 > arg4.
+ Examples: []
+ Le:
+ Aliases:
+ - le
+ Args:
+ - first
+ - others
+ Description: Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3 && arg1 <= arg4.
+ Examples: []
+ Lt:
+ Aliases:
+ - lt
+ Args:
+ - first
+ - others
+ Description: Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
+ Examples: []
+ LtCollate:
+ Aliases: null
+ Args:
+ - collator
+ - first
+ - others
+ Description: |-
+ LtCollate returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
+ The provided collator will be used for string comparisons.
+ This is for internal use.
+ Examples: []
+ Ne:
+ Aliases:
+ - ne
+ Args:
+ - first
+ - others
+ Description: Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3 && arg1 != arg4.
+ Examples: []
+ crypto:
- 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: []
+ HMAC:
+ Aliases:
+ - hmac
+ Args:
+ - h
+ - k
+ - m
+ - e
+ Description: HMAC returns a cryptographic hash that uses a key to sign a message.
+ Examples:
+ - - '{{ hmac "sha256" "Secret key" "Hello world, gophers!" }}'
+ - b6d11b6c53830b9d87036272ca9fe9d19306b8f9d8aa07b15da27d89e6e34f40
+ MD5:
+ Aliases:
+ - md5
+ Args:
+ - v
+ Description: MD5 hashes the v and returns its MD5 checksum.
+ Examples:
+ - - '{{ md5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ - - '{{ crypto.MD5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ SHA1:
+ Aliases:
+ - sha1
+ Args:
+ - v
+ Description: SHA1 hashes v and returns its SHA1 checksum.
+ Examples:
+ - - '{{ sha1 "Hello world, gophers!" }}'
+ - c8b5b0e33d408246e30f53e32b8f7627a7a649d4
+ SHA256:
+ Aliases:
+ - sha256
+ Args:
+ - v
+ Description: SHA256 hashes v and returns its SHA256 checksum.
+ Examples:
+ - - '{{ sha256 "Hello world, gophers!" }}'
+ - 6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46
+ css:
+ PostCSS:
+ Aliases:
+ - postCSS
+ Args:
+ - args
+ Description: PostCSS processes the given Resource with PostCSS.
+ Examples: []
+ Quoted:
+ Aliases: null
+ Args:
+ - v
+ Description: Quoted returns a string that needs to be quoted in CSS.
+ Examples: []
+ Sass:
+ Aliases:
+ - toCSS
+ Args:
+ - args
+ Description: Sass processes the given Resource with SASS.
+ Examples: []
+ TailwindCSS:
+ Aliases: null
+ Args:
+ - args
+ Description: TailwindCSS processes the given Resource with tailwindcss.
+ Examples: []
+ Unquoted:
+ Aliases: null
+ Args:
+ - v
+ Description: Unquoted returns a string that does not need to be quoted in CSS.
+ Examples: []
-
+ debug:
+ Dump:
+ Aliases: null
+ Args:
+ - val
+ Description: |-
+ 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:
+ - - '{{ $m := newScratch }}\n{{ $m.Set "Hugo" "Rocks!" }}\n{{ $m.Values | debug.Dump | safeHTML }}'
+ - '{\n "Hugo": "Rocks!"\n}'
+ TestDeprecationErr:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ TestDeprecationInfo:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ TestDeprecationWarn:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ Timer:
+ Aliases: null
+ Args:
+ - name
+ Description: ''
+ Examples: []
+ VisualizeSpaces:
+ Aliases: null
+ Args:
+ - val
+ Description: VisualizeSpaces returns a string with spaces replaced by a visible string.
+ Examples: []
+ diagrams:
+ Goat:
+ Aliases: null
+ Args:
+ - v
+ Description: Goat creates a new SVG diagram from input v.
+ Examples: []
+ encoding:
+ Base64Decode:
+ Aliases:
+ - base64Decode
+ Args:
+ - content
+ Description: Base64Decode returns the base64 decoding of the given content.
+ Examples:
+ - - '{{ "SGVsbG8gd29ybGQ=" | base64Decode }}'
+ - Hello world
+ - - '{{ 42 | base64Encode | base64Decode }}'
+ - '42'
+ Base64Encode:
+ Aliases:
+ - base64Encode
+ Args:
+ - content
+ Description: Base64Encode returns the base64 encoding of the given content.
+ Examples:
+ - - '{{ "Hello world" | base64Encode }}'
+ - SGVsbG8gd29ybGQ=
+ Jsonify:
+ Aliases:
+ - jsonify
+ Args:
+ - args
+ Description: |-
+ Jsonify encodes a given object to JSON. To pretty print the JSON, pass a map
+ or dictionary of options as the first value in args. Supported options are
+ "prefix" and "indent". Each JSON element in the output will begin on a new
+ line beginning with prefix followed by one or more copies of indent according
+ to the indentation nesting.
+ Examples:
+ - - '{{ (slice "A" "B" "C") | jsonify }}'
+ - '["A","B","C"]'
+ - - '{{ (slice "A" "B" "C") | jsonify (dict "indent" " ") }}'
+ - '[\n "A",\n "B",\n "C"\n]'
+ fmt:
+ Errorf:
+ Aliases:
+ - errorf
+ Args:
+ - format
+ - args
+ Description: |-
+ Errorf formats args according to a format specifier and logs an ERROR.
+ It returns an empty string.
+ Examples:
+ - - '{{ errorf "%s." "failed" }}'
+ - ''
+ Erroridf:
+ Aliases:
+ - erroridf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Erroridf formats args according to a format specifier and logs an ERROR and
+ an information text that the error with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ erroridf "my-err-id" "%s." "failed" }}'
+ - ''
+ Errormf:
+ Aliases: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Errormf is experimental and subject to change at any time.
+ Examples: []
+ Print:
+ Aliases:
+ - print
+ Args:
+ - args
+ Description: Print returns a string representation of args.
+ Examples:
+ - - '{{ print "works!" }}'
+ - works!
+ Printf:
+ Aliases:
+ - printf
+ Args:
+ - format
+ - args
+ Description: Printf returns string representation of args formatted with the layout in format.
+ Examples:
+ - - '{{ printf "%s!" "works" }}'
+ - works!
+ Println:
+ Aliases:
+ - println
+ Args:
+ - args
+ Description: Println returns string representation of args ending with a newline.
+ Examples:
+ - - '{{ println "works!" }}'
+ - |
+ works!
+ Warnf:
+ Aliases:
+ - warnf
+ Args:
+ - format
+ - args
+ Description: |-
+ Warnf formats args according to a format specifier and logs a WARNING.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnf "%s." "warning" }}'
+ - ''
+ Warnidf:
+ Aliases:
+ - warnidf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Warnidf formats args according to a format specifier and logs an WARNING and
+ an information text that the warning with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnidf "my-warn-id" "%s." "warning" }}'
+ - ''
+ Warnmf:
+ Aliases: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Warnmf is experimental and subject to change at any time.
+ Examples: []
+ hash:
+ FNV32a:
+ Aliases: null
+ Args:
+ - v
+ Description: FNV32a hashes v using fnv32a algorithm.
+ Examples:
+ - - '{{ hash.FNV32a "Hugo Rocks!!" }}'
+ - '1515779328'
+ XxHash:
+ Aliases:
+ - xxhash
+ Args:
+ - v
+ Description: XxHash returns the xxHash of the input string.
+ Examples:
+ - - '{{ hash.XxHash "The quick brown fox jumps over the lazy dog" }}'
+ - 0b242d361fda71bc
+ hugo:
+ Deps:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Generator:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsDevelopment:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsExtended:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultiHost:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultihost:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultilingual:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsProduction:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsServer:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Store:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ WorkingDir:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ images:
+ AutoOrient:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Brightness:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ColorBalance:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Colorize:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Config:
+ Aliases:
+ - imageConfig
+ Args:
+ - path
+ Description: |-
+ Config returns the image.Config for the specified path relative to the
+ working directory.
+ Examples: []
+ Contrast:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Dither:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Filter:
+ Aliases: null
+ Args:
+ - args
+ Description: Filter applies the given filters to the image given as the last element in args.
+ Examples: []
+ Gamma:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GaussianBlur:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Grayscale:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Hue:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Invert:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Mask:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Opacity:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Overlay:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Padding:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Pixelate:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Process:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ QR:
+ Aliases: null
+ Args:
+ - args
+ Description: |-
+ QR encodes the given text into a QR code using the specified options,
+ returning an image resource.
+ Examples: []
+ Saturation:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sepia:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sigmoid:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Text:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ UnsharpMask:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ inflect:
+ Humanize:
+ Aliases:
+ - humanize
+ Args:
+ - 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:
+ - - '{{ humanize "my-first-post" }}'
+ - My first post
+ - - '{{ humanize "myCamelPost" }}'
+ - My camel post
+ - - '{{ humanize "52" }}'
+ - 52nd
+ - - '{{ humanize 103 }}'
+ - 103rd
+ Pluralize:
+ Aliases:
+ - pluralize
+ Args:
+ - v
+ Description: Pluralize returns the plural form of the single word in v.
+ Examples:
+ - - '{{ "cat" | pluralize }}'
+ - cats
+ Singularize:
+ Aliases:
+ - singularize
+ Args:
+ - v
+ Description: Singularize returns the singular form of a single word in v.
+ Examples:
+ - - '{{ "cats" | singularize }}'
+ - cat
+ js:
+ Babel:
+ Aliases:
+ - babel
+ Args:
+ - args
+ Description: Babel processes the given Resource with Babel.
+ Examples: []
+ Batch:
+ Aliases: null
+ Args:
+ - id
+ Description: |-
+ Batch creates a new Batcher with the given ID.
+ Repeated calls with the same ID will return the same Batcher.
+ The ID will be used to name the root directory of the batch.
+ Forward slashes in the ID is allowed.
+ Examples: []
+ Build:
+ Aliases: null
+ Args:
+ - args
+ Description: Build processes the given Resource with ESBuild.
+ Examples: []
+ lang:
+ FormatAccounting:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ 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" }}'
+ - NOK512.50
+ FormatCurrency:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ Description: |-
+ FormatCurrency returns the currency representation of number for the given currency and precision
+ for the current language.
- 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: []
++
+ The return value is formatted with at least two decimal places.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}'
+ - $512.50
+ FormatNumber:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: FormatNumber formats number with the given precision for the current language.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatNumber 2 }}'
+ - '512.50'
+ FormatNumberCustom:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ - options
+ Description: 'FormatNumberCustom formats a number with the given precision. The first\noptions parameter is a space-delimited string of characters to represent\nnegativity, the decimal point, and grouping. The default value is `- . ,`.\nThe second options parameter defines an alternate delimiting character.\n\nNote that numbers are rounded up at 5 or greater.\nSo, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.\n\nFor a simpler function that adapts to the current language, see FormatNumber.'
+ Examples:
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 }}'
+ - 12,345.68
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 "- , ." }}'
+ - 12.345,68
+ - - '{{ lang.FormatNumberCustom 6 -12345.6789 "- ." }}'
+ - '-12345.678900'
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }}'
+ - -12,346
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }}'
+ - -12 346
+ - - '{{ -98765.4321 | lang.FormatNumberCustom 2 }}'
+ - -98,765.43
+ FormatPercent:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: |-
+ FormatPercent formats number with the given precision for the current language.
+ Note that the number is assumed to be a percentage.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatPercent 2 }}'
+ - 512.50%
+ Merge:
+ Aliases: null
+ Args:
+ - p2
+ - p1
+ Description: Merge creates a union of pages from two languages.
+ Examples: []
+ Translate:
+ Aliases:
+ - i18n
+ - T
+ Args:
+ - ctx
+ - id
+ - args
+ Description: Translate returns a translated string for id.
+ Examples: []
+ math:
+ Abs:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Abs returns the absolute value of n.
+ Examples:
+ - - '{{ math.Abs -2.1 }}'
+ - '2.1'
+ Acos:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Acos returns the arccosine, in radians, of n.
+ Examples:
+ - - '{{ math.Acos 1 }}'
+ - '0'
+ Add:
+ Aliases:
+ - add
+ Args:
+ - inputs
+ Description: Add adds the multivalued addends n1 and n2 or more values.
+ Examples:
+ - - '{{ add 1 2 }}'
+ - '3'
+ Asin:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Asin returns the arcsine, in radians, of n.
+ Examples:
+ - - '{{ math.Asin 1 }}'
+ - '1.5707963267948966'
+ Atan:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Atan returns the arctangent, in radians, of n.
+ Examples:
+ - - '{{ math.Atan 1 }}'
+ - '0.7853981633974483'
+ Atan2:
+ Aliases: null
+ Args:
+ - 'n'
+ - m
+ Description: Atan2 returns the arc tangent of n/m, using the signs of the two to determine the quadrant of the return value.
+ Examples:
+ - - '{{ math.Atan2 1 2 }}'
+ - '0.4636476090008061'
+ Ceil:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Ceil returns the least integer value greater than or equal to n.
+ Examples:
+ - - '{{ math.Ceil 2.1 }}'
+ - '3'
+ Cos:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Cos returns the cosine of the radian argument n.
+ Examples:
+ - - '{{ math.Cos 1 }}'
+ - '0.5403023058681398'
+ Counter:
+ Aliases: null
+ Args: null
+ Description: 'Counter increments and returns a global counter.\nThis was originally added to be used in tests where now.UnixNano did not\nhave the needed precision (especially on Windows).\nNote that given the parallel nature of Hugo, you cannot use this to get sequences of numbers,\nand the counter will reset on new builds.\n<docsmeta>{"identifiers": ["now.UnixNano"] }</docsmeta>'
+ Examples: []
+ Div:
+ Aliases:
+ - div
+ Args:
+ - inputs
+ Description: Div divides n1 by n2.
+ Examples:
+ - - '{{ div 6 3 }}'
+ - '2'
+ Floor:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Floor returns the greatest integer value less than or equal to n.
+ Examples:
+ - - '{{ math.Floor 1.9 }}'
+ - '1'
+ Log:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Log returns the natural logarithm of the number n.
+ Examples:
+ - - '{{ math.Log 1 }}'
+ - '0'
+ Max:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Max returns the greater of all numbers in inputs. Any slices in inputs are flattened.
+ Examples:
+ - - '{{ math.Max 1 2 }}'
+ - '2'
+ MaxInt64:
+ Aliases: null
+ Args: null
+ Description: MaxInt64 returns the maximum value for a signed 64-bit integer.
+ Examples:
+ - - '{{ math.MaxInt64 }}'
+ - '9223372036854775807'
+ Min:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Min returns the smaller of all numbers in inputs. Any slices in inputs are flattened.
+ Examples:
+ - - '{{ math.Min 1 2 }}'
+ - '1'
+ Mod:
+ Aliases:
+ - mod
+ Args:
+ - n1
+ - n2
+ Description: Mod returns n1 % n2.
+ Examples:
+ - - '{{ mod 15 3 }}'
+ - '0'
+ ModBool:
+ Aliases:
+ - modBool
+ Args:
+ - n1
+ - n2
+ Description: ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return true.
+ Examples:
+ - - '{{ modBool 15 3 }}'
+ - 'true'
+ Mul:
+ Aliases:
+ - mul
+ Args:
+ - inputs
+ Description: Mul multiplies the multivalued numbers n1 and n2 or more values.
+ Examples:
+ - - '{{ mul 2 3 }}'
+ - '6'
+ Pi:
+ Aliases: null
+ Args: null
+ Description: Pi returns the mathematical constant pi.
+ Examples:
+ - - '{{ math.Pi }}'
+ - '3.141592653589793'
+ Pow:
+ Aliases:
+ - pow
+ Args:
+ - n1
+ - n2
+ Description: Pow returns n1 raised to the power of n2.
+ Examples:
+ - - '{{ math.Pow 2 3 }}'
+ - '8'
+ Product:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Product returns the product of all numbers in inputs. Any slices in inputs are flattened.
+ Examples: []
+ Rand:
+ Aliases: null
+ Args: null
+ Description: Rand returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
+ Examples:
+ - - '{{ math.Rand }}'
+ - '0.6312770459590062'
+ Round:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Round returns the integer nearest to n, rounding half away from zero.
+ Examples:
+ - - '{{ math.Round 1.5 }}'
+ - '2'
+ Sin:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Sin returns the sine of the radian argument n.
+ Examples:
+ - - '{{ math.Sin 1 }}'
+ - '0.8414709848078965'
+ Sqrt:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Sqrt returns the square root of the number n.
+ Examples:
+ - - '{{ math.Sqrt 81 }}'
+ - '9'
+ Sub:
+ Aliases:
+ - sub
+ Args:
+ - inputs
+ Description: Sub subtracts multivalued.
+ Examples:
+ - - '{{ sub 3 2 }}'
+ - '1'
+ Sum:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Sum returns the sum of all numbers in inputs. Any slices in inputs are flattened.
+ Examples: []
+ Tan:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Tan returns the tangent of the radian argument n.
+ Examples:
+ - - '{{ math.Tan 1 }}'
+ - '1.557407724654902'
+ ToDegrees:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: ToDegrees converts radians into degrees.
+ Examples:
+ - - '{{ math.ToDegrees 1.5707963267948966 }}'
+ - '90'
+ ToRadians:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: ToRadians converts degrees into radians.
+ Examples:
+ - - '{{ math.ToRadians 90 }}'
+ - '1.5707963267948966'
+ openapi3:
+ Unmarshal:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: []
+ os:
+ FileExists:
+ Aliases:
+ - fileExists
+ Args:
+ - i
+ Description: FileExists checks whether a file exists under the given path.
+ Examples:
+ - - '{{ fileExists "foo.txt" }}'
+ - 'false'
+ Getenv:
+ Aliases:
+ - getenv
+ Args:
+ - key
+ Description: |-
+ Getenv retrieves the value of the environment variable named by the key.
+ It returns the value, which will be empty if the variable is not present.
+ Examples: []
+ ReadDir:
+ Aliases:
+ - readDir
+ Args:
+ - i
+ Description: ReadDir lists the directory contents relative to the configured WorkingDir.
+ Examples:
+ - - '{{ range (readDir "files") }}{{ .Name }}{{ end }}'
+ - README.txt
+ ReadFile:
+ Aliases:
+ - readFile
+ Args:
+ - i
+ Description: |-
+ ReadFile reads the file named by filename relative to the configured WorkingDir.
+ It returns the contents as a string.
+ There is an upper size limit set at 1 megabytes.
+ Examples:
+ - - '{{ readFile "files/README.txt" }}'
+ - Hugo Rocks!
+ Stat:
+ Aliases: null
+ Args:
+ - i
+ Description: Stat returns the os.FileInfo structure describing file.
+ Examples: []
+ partials:
+ Include:
+ Aliases:
+ - partial
+ Args:
+ - ctx
+ - name
+ - contextList
+ Description: |-
+ Include executes the named partial.
+ If the partial contains a return statement, that value will be returned.
+ Else, the rendered output will be returned:
+ A string if the partial is a text/template, or template.HTML when html/template.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples:
+ - - '{{ partial "header.html" . }}'
+ - <title>Hugo Rocks!</title>
+ IncludeCached:
+ Aliases:
+ - partialCached
+ Args:
+ - ctx
+ - name
+ - context
+ - variants
+ Description: |-
+ IncludeCached executes and caches partial templates. The cache is created with name+variants as the key.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples: []
+ path:
+ Base:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Base returns the last element of path.
+ Trailing slashes are removed before extracting the last element.
+ If the path is empty, Base returns ".".
+ If the path consists entirely of slashes, Base returns "/".
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ BaseName:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ BaseName returns the last element of path, removing the extension if present.
+ Trailing slashes are removed before extracting the last element.
+ If the path is empty, Base returns ".".
+ If the path consists entirely of slashes, Base returns "/".
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Clean:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Clean replaces the separators used with standard slashes and then
+ extraneous slashes are removed.
+ Examples: []
+ Dir:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Dir returns all but the last element of path, typically the path's directory.
+ After dropping the final element using Split, the path is Cleaned and trailing
+ slashes are removed.
+ If the path is empty, Dir returns ".".
+ If the path consists entirely of slashes followed by non-slash bytes, Dir
+ returns a single slash. In any other case, the returned path does not end in a
+ slash.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Ext:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Ext returns the file name extension used by path.
+ The extension is the suffix beginning at the final dot
+ in the final slash-separated element of path;
+ it is empty if there is no dot.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Join:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ Join joins any number of path elements into a single path, adding a
+ separating slash if necessary. All the input
+ path elements are passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The result is Cleaned; in particular,
+ all empty strings are ignored.
+ Examples:
+ - - '{{ slice "my/path" "filename.txt" | path.Join }}'
+ - my/path/filename.txt
+ - - '{{ path.Join "my" "path" "filename.txt" }}'
+ - my/path/filename.txt
+ - - '{{ "my/path/filename.txt" | path.Ext }}'
+ - .txt
+ - - '{{ "my/path/filename.txt" | path.Base }}'
+ - filename.txt
+ - - '{{ "my/path/filename.txt" | path.Dir }}'
+ - my/path
+ Split:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Split splits path immediately following the final slash,
+ separating it into a directory and file name component.
+ If there is no slash in path, Split returns an empty dir and
+ file set to path.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The returned values have the property that path = dir+file.
+ Examples:
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ reflect:
+ IsImageResource:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMap:
+ Aliases: null
+ Args:
+ - v
+ Description: IsMap reports whether v is a map.
+ Examples:
+ - - '{{ if reflect.IsMap (dict "a" 1) }}Map{{ end }}'
+ - Map
+ IsPage:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsResource:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsSite:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsSlice:
+ Aliases: null
+ Args:
+ - v
+ Description: IsSlice reports whether v is a slice.
+ Examples:
+ - - '{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}'
+ - Slice
+ resources:
-
+ ByType:
+ Aliases: null
+ Args:
+ - typ
+ Description: ByType returns resources of a given resource type (e.g. "image").
+ Examples: []
+ Concat:
+ Aliases: null
+ Args:
+ - targetPathIn
+ - r
+ Description: |-
+ Concat concatenates a slice of Resource objects. These resources must
+ (currently) be of the same Media Type.
+ Examples: []
+ Copy:
+ Aliases: null
+ Args:
+ - s
+ - r
+ Description: Copy copies r to the new targetPath in s.
+ Examples: []
+ ExecuteAsTemplate:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ ExecuteAsTemplate creates a Resource from a Go template, parsed and executed with
+ the given data, and published to the relative target path.
+ Examples: []
+ Fingerprint:
+ Aliases:
+ - fingerprint
+ Args:
+ - args
+ Description: |-
+ Fingerprint transforms the given Resource with a MD5 hash of the content in
+ the RelPermalink and Permalink.
+ Examples: []
+ FromString:
+ Aliases: null
+ Args:
+ - targetPathIn
+ - contentIn
+ Description: FromString creates a Resource from a string published to the relative target path.
+ Examples: []
+ Get:
+ Aliases: null
+ Args:
+ - filename
+ Description: |-
+ Get locates the filename given in Hugo's assets filesystem
+ and creates a Resource object that can be used for further transformations.
+ Examples: []
+ GetMatch:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GetRemote:
+ Aliases: null
+ Args:
+ - args
+ Description: 'GetRemote gets the URL (via HTTP(s)) in the first argument in args and creates Resource object that can be used for\nfurther transformations.\n\nA second argument may be provided with an option map.\n\nNote: This method does not return any error as a second return value,\nfor any error situations the error can be checked in .Err.'
+ Examples: []
+ Match:
+ Aliases: null
+ Args:
+ - pattern
+ Description: |-
+ Match gets all resources matching the given base path prefix, e.g
+ "*.png" will match all png files. The "*" does not match path delimiters (/),
+ 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.
- 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: []
++
+ See Match for a more complete explanation about the rules used.
+ Examples: []
+ Minify:
+ Aliases:
+ - minify
+ Args:
+ - r
+ Description: |-
+ Minify minifies the given Resource using the MediaType to pick the correct
+ minifier.
+ 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: []
+ PostProcess:
+ Aliases: null
+ Args:
+ - r
+ Description: PostProcess processes r after the build.
+ Examples: []
- Author:
- Aliases: null
- Args: null
- Description: ''
- Examples: null
- Authors:
- Aliases: null
- Args: null
- Description: ''
- Examples: null
+ safe:
+ CSS:
+ Aliases:
+ - safeCSS
+ Args:
+ - s
+ Description: CSS returns the string s as html/template CSS content.
+ Examples:
+ - - '{{ "Bat&Man" | safeCSS | safeCSS }}'
+ - Bat&Man
+ HTML:
+ Aliases:
+ - safeHTML
+ Args:
+ - s
+ Description: HTML returns the string s as html/template HTML content.
+ Examples:
+ - - '{{ "Bat&Man" | safeHTML | safeHTML }}'
+ - Bat&Man
+ - - '{{ "Bat&Man" | safeHTML }}'
+ - Bat&Man
+ HTMLAttr:
+ Aliases:
+ - safeHTMLAttr
+ Args:
+ - s
+ Description: HTMLAttr returns the string s as html/template HTMLAttr content.
+ Examples: []
+ JS:
+ Aliases:
+ - safeJS
+ Args:
+ - s
+ Description: JS returns the given string as a html/template JS content.
+ Examples:
+ - - '{{ "(1*2)" | safeJS | safeJS }}'
+ - (1*2)
+ JSStr:
+ Aliases:
+ - safeJSStr
+ Args:
+ - s
+ Description: JSStr returns the given string as a html/template JSStr content.
+ Examples: []
+ URL:
+ Aliases:
+ - safeURL
+ Args:
+ - s
+ Description: URL returns the string s as html/template URL content.
+ Examples:
+ - - '{{ "http://gohugo.io" | safeURL | safeURL }}'
+ - http://gohugo.io
+ site:
+ AllPages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
- IsMultiLingual:
- Aliases: null
- Args: null
- Description: ''
- Examples: null
+ BaseURL:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ BuildDrafts:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ CheckReady:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Config:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Copyright:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Current:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Data:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Dimension:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ForEeachIdentityByName:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GetPage:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Home:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Hugo:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
- LastChange:
- Aliases: null
- Args: null
- Description: ''
- Examples: null
+ Key:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Language:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ LanguageCode:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ LanguagePrefix:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Languages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
- Social:
- Aliases: null
- Args: null
- Description: ''
- Examples: null
+ Lastmod:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ MainSections:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Menus:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Pages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Param:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Params:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ RegularPages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Role:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sections:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ServerPort:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sites:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
-
+ Store:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ String:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Taxonomies:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Title:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ strings:
+ Chomp:
+ Aliases:
+ - chomp
+ Args:
+ - s
+ Description: Chomp returns a copy of s with all trailing newline characters removed.
+ Examples:
+ - - '{{ chomp "<p>Blockhead</p>\n" | safeHTML }}'
+ - <p>Blockhead</p>
+ Contains:
+ Aliases: null
+ Args:
+ - s
+ - substr
+ Description: Contains reports whether substr is in s.
+ Examples:
+ - - '{{ strings.Contains "abc" "b" }}'
+ - 'true'
+ - - '{{ strings.Contains "abc" "d" }}'
+ - 'false'
+ ContainsAny:
+ Aliases: null
+ Args:
+ - s
+ - chars
+ Description: ContainsAny reports whether any Unicode code points in chars are within s.
+ Examples:
+ - - '{{ strings.ContainsAny "abc" "bcd" }}'
+ - 'true'
+ - - '{{ strings.ContainsAny "abc" "def" }}'
+ - 'false'
+ ContainsNonSpace:
+ Aliases: null
+ Args:
+ - s
+ Description: 'ContainsNonSpace reports whether s contains any non-space characters as defined\nby Unicode''s White Space property,\n<docsmeta>{"newIn": "0.111.0" }</docsmeta>'
+ Examples: []
+ Count:
+ Aliases: null
+ Args:
+ - substr
+ - s
+ Description: |-
+ Count counts the number of non-overlapping instances of substr in s.
+ If substr is an empty string, Count returns 1 + the number of Unicode code points in s.
+ Examples:
+ - - '{{ "aabab" | strings.Count "a" }}'
+ - '3'
+ CountRunes:
+ Aliases:
+ - countrunes
+ Args:
+ - s
+ Description: CountRunes returns the number of runes in s, excluding whitespace.
+ Examples: []
+ CountWords:
+ Aliases:
+ - countwords
+ Args:
+ - s
+ Description: CountWords returns the approximate word count in s.
+ Examples: []
+ Diff:
+ Aliases: null
+ Args:
+ - oldname
+ - old
+ - newname
+ - new
+ Description: |-
+ Diff returns an anchored diff of the two texts old and new in the “unified
+ diff” format. If old and new are identical, Diff returns an empty string.
+ Examples: []
+ FindRE:
+ Aliases:
+ - findRE
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRE returns a list of strings that match the regular expression. By default all matches
+ will be included. The number of matches can be limited with an optional third parameter.
+ Examples:
+ - - '{{ findRE "[G|g]o" "Hugo is a static side generator written in Go." 1 }}'
+ - '[go]'
+ FindRESubmatch:
+ Aliases:
+ - findRESubmatch
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRESubmatch returns a slice of all successive matches of the regular
+ 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.
+ Examples:
+ - - '{{ findRESubmatch `<a\s*href="(.+?)">(.+?)</a>` `<li><a href="#foo">Foo</a></li> <li><a href="#bar">Bar</a></li>` | print | safeHTML }}'
+ - '[[<a href="#foo">Foo</a> #foo Foo] [<a href="#bar">Bar</a> #bar Bar]]'
+ FirstUpper:
+ Aliases: null
+ Args:
+ - s
+ Description: FirstUpper converts s making the first character upper case.
+ Examples:
+ - - '{{ "hugo rocks!" | strings.FirstUpper }}'
+ - Hugo rocks!
+ HasPrefix:
+ Aliases:
+ - hasPrefix
+ Args:
+ - s
+ - prefix
+ Description: HasPrefix tests whether the input s begins with prefix.
+ Examples:
+ - - '{{ hasPrefix "Hugo" "Hu" }}'
+ - 'true'
+ - - '{{ hasPrefix "Hugo" "Fu" }}'
+ - 'false'
+ HasSuffix:
+ Aliases:
+ - hasSuffix
+ Args:
+ - s
+ - suffix
+ Description: HasSuffix tests whether the input s begins with suffix.
+ Examples:
+ - - '{{ hasSuffix "Hugo" "go" }}'
+ - 'true'
+ - - '{{ hasSuffix "Hugo" "du" }}'
+ - 'false'
+ Repeat:
+ Aliases: null
+ Args:
+ - 'n'
+ - s
+ Description: Repeat returns a new string consisting of n copies of the string s.
+ Examples:
+ - - '{{ "yo" | strings.Repeat 4 }}'
+ - yoyoyoyo
+ Replace:
+ Aliases:
+ - replace
+ Args:
+ - s
+ - old
+ - new
+ - limit
+ Description: |-
+ Replace returns a copy of the string s with all occurrences of old replaced
+ with new. The number of replacements can be limited with an optional fourth
+ parameter.
+ Examples:
+ - - '{{ replace "Batman and Robin" "Robin" "Catwoman" }}'
+ - Batman and Catwoman
+ - - '{{ replace "aabbaabb" "a" "z" 2 }}'
+ - zzbbaabb
+ ReplaceRE:
+ Aliases:
+ - replaceRE
+ Args:
+ - pattern
+ - repl
+ - s
+ - 'n'
+ Description: |-
+ ReplaceRE returns a copy of s, replacing all matches of the regular
+ expression pattern with the replacement text repl. The number of replacements
+ can be limited with an optional fourth parameter.
+ Examples:
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" }}'
+ - XbXbX
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" 1 }}'
+ - Xbaabbab
+ RuneCount:
+ Aliases: null
+ Args:
+ - s
+ Description: RuneCount returns the number of runes in s.
+ Examples: []
+ SliceString:
+ Aliases:
+ - slicestr
+ Args:
+ - a
+ - startEnd
+ Description: |-
+ SliceString slices a string by specifying a half-open range with
+ two indices, start and end. 1 and 4 creates a slice including elements 1 through 3.
+ The end index can be omitted, it defaults to the string's length.
+ Examples:
+ - - '{{ slicestr "BatMan" 0 3 }}'
+ - Bat
+ - - '{{ slicestr "BatMan" 3 }}'
+ - Man
+ Split:
+ Aliases:
+ - split
+ Args:
+ - a
+ - delimiter
+ Description: Split slices an input string into all substrings separated by delimiter.
+ Examples: []
+ Substr:
+ Aliases:
+ - substr
+ Args:
+ - a
+ - nums
+ Description: 'Substr extracts parts of a string, beginning at the character at the specified\nposition, and returns the specified number of characters.\n\nIt normally takes two parameters: start and length.\nIt can also take one parameter: start, i.e. length is omitted, in which case\nthe substring starting from start until the end of the string will be returned.\n\nTo extract characters from the end of the string, use a negative start number.\n\nIn addition, borrowing from the extended behavior described at http://php.net/substr,\nif length is given and is negative, then that many characters will be omitted from\nthe end of string.'
+ Examples:
+ - - '{{ substr "BatMan" 0 -3 }}'
+ - Bat
+ - - '{{ substr "BatMan" 3 3 }}'
+ - Man
+ Title:
+ Aliases:
+ - title
+ Args:
+ - s
+ Description: |-
+ Title returns a copy of the input s with all Unicode letters that begin words
+ mapped to their title case.
+ Examples:
+ - - '{{ title "Bat man" }}'
+ - Bat Man
+ - - '{{ title "somewhere over the rainbow" }}'
+ - Somewhere Over the Rainbow
+ ToLower:
+ Aliases:
+ - lower
+ Args:
+ - s
+ Description: |-
+ ToLower returns a copy of the input s with all Unicode letters mapped to their
+ lower case.
+ Examples:
+ - - '{{ lower "BatMan" }}'
+ - batman
+ ToUpper:
+ Aliases:
+ - upper
+ Args:
+ - s
+ Description: |-
+ ToUpper returns a copy of the input s with all Unicode letters mapped to their
+ upper case.
+ Examples:
+ - - '{{ upper "BatMan" }}'
+ - BATMAN
+ Trim:
+ Aliases:
+ - trim
+ Args:
+ - s
+ - cutset
+ Description: |-
+ Trim returns converts the strings s removing all leading and trailing characters defined
+ contained.
+ Examples:
+ - - '{{ trim "++Batman--" "+-" }}'
+ - Batman
+ TrimLeft:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimLeft returns a slice of the string s with all leading characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimLeft "a" }}'
+ - bbaa
+ TrimPrefix:
+ Aliases: null
+ Args:
+ - prefix
+ - s
+ Description: |-
+ TrimPrefix returns s without the provided leading prefix string. If s doesn't
+ start with prefix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimPrefix "a" }}'
+ - abbaa
+ - - '{{ "aabbaa" | strings.TrimPrefix "aa" }}'
+ - bbaa
+ TrimRight:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimRight returns a slice of the string s with all trailing characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimRight "a" }}'
+ - aabb
+ TrimSpace:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ TrimSpace returns the given string, removing leading and trailing whitespace
+ as defined by Unicode.
+ Examples: []
+ TrimSuffix:
+ Aliases: null
+ Args:
+ - suffix
+ - s
+ Description: |-
+ TrimSuffix returns s without the provided trailing suffix string. If s
+ doesn't end with suffix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimSuffix "a" }}'
+ - aabba
+ - - '{{ "aabbaa" | strings.TrimSuffix "aa" }}'
+ - aabb
+ Truncate:
+ Aliases:
+ - truncate
+ Args:
+ - s
+ - options
+ Description: Truncate truncates the string in s to the specified length.
+ Examples:
+ - - '{{ "this is a very long text" | truncate 10 " ..." }}'
+ - this is a ...
+ - - '{{ "With [Markdown](/markdown) inside." | markdownify | truncate 14 }}'
+ - With <a href="/markdown">Markdown …</a>
+ templates:
+ Current:
+ Aliases: null
+ Args:
+ - ctx
+ Description: Get information about the currently executing template.
+ Examples: []
+ Defer:
+ Aliases: null
+ Args:
+ - args
+ Description: Defer defers the execution of a template block.
+ Examples: []
+ DoDefer:
+ Aliases:
+ - doDefer
+ Args:
+ - ctx
+ - id
+ - optsv
+ Description: |-
+ DoDefer defers the execution of a template block.
+ For internal use only.
+ Examples: []
+ Exists:
+ Aliases: null
+ Args:
+ - name
+ Description: |-
+ Exists returns whether the template with the given name exists.
+ Note that this is the Unix-styled relative path including filename suffix,
+ e.g. partials/header.html
+ Examples:
+ - - '{{ if (templates.Exists "_partials/header.html") }}Yes!{{ end }}'
+ - Yes!
+ - - '{{ if not (templates.Exists "_partials/doesnotexist.html") }}No!{{ end }}'
+ - No!
+ Inner:
+ Aliases:
+ - inner
+ Args:
+ - ctx
+ - data
+ Description: |-
+ Inner executes the inner content of a partial decorator.
+ Note that there is only one inner block per partial decorator, but inner may be called multiple times with, typically, different data.
+ Examples: []
+ time:
+ AsTime:
+ Aliases: null
+ Args:
+ - v
+ - args
+ Description: |-
+ AsTime converts the textual representation of the datetime string into
+ a time.Time interface.
+ Examples:
+ - - '{{ (time "2015-01-21").Year }}'
+ - '2015'
+ Duration:
+ Aliases:
+ - duration
+ Args:
+ - unit
+ - number
+ Description: |-
+ Duration converts the given number to a time.Duration.
+ Unit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.
+ Examples:
+ - - '{{ mul 60 60 | duration "second" }}'
+ - 1h0m0s
+ Format:
+ Aliases:
+ - dateFormat
+ Args:
+ - layout
+ - v
+ Description: |-
+ Format converts the textual representation of the datetime string in v into
+ time.Time if needed and formats it with the given layout.
+ Examples:
+ - - 'dateFormat: {{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}'
+ - 'dateFormat: Wednesday, Jan 21, 2015'
+ In:
+ Aliases: null
+ Args:
+ - timeZoneName
+ - t
+ Description: |-
+ In returns the time t in the IANA time zone specified by timeZoneName.
+ If timeZoneName is "" or "UTC", the time is returned in UTC.
+ If timeZoneName is "Local", the time is returned in the system's local time zone.
+ Otherwise, timeZoneName must be a valid IANA location name (e.g., "Europe/Oslo").
+ Examples: []
+ Now:
+ Aliases:
+ - now
+ Args: null
+ Description: Now returns the current local time or `clock` time
+ Examples: []
+ ParseDuration:
+ Aliases: null
+ Args:
+ - s
+ Description: 'ParseDuration parses the duration string s.\nA duration string is a possibly signed sequence of\ndecimal numbers, each with optional fraction and a unit suffix,\nsuch as "300ms", "-1.5h" or "2h45m".\nValid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".\nSee https://golang.org/pkg/time/#ParseDuration'
+ Examples:
+ - - '{{ "1h12m10s" | time.ParseDuration }}'
+ - 1h12m10s
+ transform:
+ CanHighlight:
+ Aliases: null
+ Args:
+ - language
+ Description: CanHighlight returns whether the given code language is supported by the Chroma highlighter.
+ Examples: []
+ Emojify:
+ Aliases:
+ - emojify
+ Args:
+ - 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 }}'
+ - I ❤️ Hugo
+ HTMLEscape:
+ Aliases:
+ - htmlEscape
+ Args:
+ - s
+ Description: HTMLEscape returns a copy of s with reserved HTML characters escaped.
+ Examples:
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" }}'
+ - Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ HTMLToMarkdown:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ This was added in Hugo v0.151.0 and should be considered experimental for now.
+ We need to test this out in the wild for a while before committing to this API,
+ and there will eventually be more options here.
+ Examples: []
+ HTMLUnescape:
+ Aliases:
+ - htmlUnescape
+ Args:
+ - s
+ Description: |-
+ HTMLUnescape returns a copy of s with HTML escape requences converted to plain
+ text.
+ Examples:
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlEscape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ Highlight:
+ Aliases:
+ - highlight
+ Args:
+ - s
+ - lang
+ - opts
+ Description: |-
+ Highlight returns a copy of s as an HTML string with syntax
+ highlighting applied.
+ Examples: []
+ HighlightCodeBlock:
+ Aliases: null
+ Args:
+ - ctx
+ - opts
+ Description: HighlightCodeBlock highlights a code block on the form received in the codeblock render hooks.
+ Examples: []
+ Markdownify:
+ Aliases:
+ - markdownify
+ Args:
+ - ctx
+ - s
+ Description: Markdownify renders s from Markdown to HTML.
+ Examples:
+ - - '{{ .Title | markdownify }}'
+ - <strong>BatMan</strong>
+ Plainify:
+ Aliases:
+ - plainify
+ Args:
+ - s
+ Description: Plainify returns a copy of s with all HTML tags removed.
+ Examples:
+ - - '{{ plainify "Hello <strong>world</strong>, gophers!" }}'
+ - Hello world, gophers!
+ PortableText:
+ Aliases: null
+ Args:
+ - v
+ Description: |-
+ PortableText converts the portable text in v to Markdown.
+ We may add more options in the future.
+ Examples: []
+ Remarshal:
+ Aliases: null
+ Args:
+ - format
+ - data
+ Description: |-
+ Remarshal is used in the Hugo documentation to convert configuration
+ examples from YAML to JSON, TOML (and possibly the other way around).
+ The is primarily a helper for the Hugo docs site.
+ It is not a general purpose YAML to TOML converter etc., and may
+ change without notice if it serves a purpose in the docs.
+ Format is one of json, yaml or toml.
+ Examples:
+ - - '{{ "title = \"Hello World\"" | transform.Remarshal "json" | safeHTML }}'
+ - '{\n "title": "Hello World"\n}\n'
+ ToMath:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ ToMath converts a LaTeX string to math in the given format, default MathML.
+ This uses KaTeX to render the math, see https://katex.org/.
+ Examples: []
+ Unmarshal:
+ Aliases:
+ - unmarshal
+ Args:
+ - args
+ Description: |-
+ Unmarshal unmarshals the data given, which can be either a string, json.RawMessage
+ or a Resource. Supported formats are JSON, TOML, YAML, and CSV.
+ You can optionally provide an options map as the first argument.
+ Examples:
+ - - '{{ "hello = \"Hello World\"" | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ - - '{{ "hello = \"Hello World\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ XMLEscape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ XMLEscape returns the given string, removing disallowed characters then
+ escaping the result to its XML equivalent.
+ Examples:
+ - - '{{ transform.XMLEscape "<p>abc</p>" }}'
+ - '<p>abc</p>'
+ urls:
+ AbsLangURL:
+ Aliases:
+ - absLangURL
+ Args:
+ - s
+ Description: |-
+ AbsLangURL the string s and converts it to an absolute URL according
+ to a page's position in the project directory structure and the current
+ language.
+ Examples: []
+ AbsURL:
+ Aliases:
+ - absURL
+ Args:
+ - s
+ Description: AbsURL takes the string s and converts it to an absolute URL.
+ Examples: []
+ Anchorize:
+ Aliases:
+ - anchorize
+ Args:
+ - s
+ Description: |-
+ Anchorize creates sanitized anchor name version of the string s that is compatible
+ with how your configured markdown renderer does it.
+ Examples:
+ - - '{{ "This is a title" | anchorize }}'
+ - this-is-a-title
+ JoinPath:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ JoinPath joins the provided elements into a URL string and cleans the result
+ of any ./ or ../ elements. If the argument list is empty, JoinPath returns
+ an empty string.
+ Examples:
+ - - '{{ urls.JoinPath "https://example.org" "foo" }}'
+ - https://example.org/foo
+ - - '{{ urls.JoinPath (slice "a" "b") }}'
+ - a/b
+ Parse:
+ Aliases: null
+ Args:
+ - rawurl
+ Description: |-
+ Parse parses rawurl into a URL structure. The rawurl may be relative or
+ absolute.
+ Examples: []
+ PathEscape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ PathEscape 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.
+ Examples: []
+ PathUnescape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ PathUnescape returns the given string, replacing all percent-encoded
+ sequences with the corresponding unescaped characters.
+ Examples: []
+ Ref:
+ Aliases:
+ - ref
+ Args:
+ - p
+ - args
+ Description: Ref returns the absolute URL path to a given content item from Page p.
+ Examples: []
+ RelLangURL:
+ Aliases:
+ - relLangURL
+ Args:
+ - s
+ Description: |-
+ RelLangURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure and the current language.
+ Examples: []
+ RelRef:
+ Aliases:
+ - relref
+ Args:
+ - p
+ - args
+ Description: RelRef returns the relative URL path to a given content item from Page p.
+ Examples: []
+ RelURL:
+ Aliases:
+ - relURL
+ Args:
+ - s
+ Description: |-
+ RelURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure.
+ Examples: []
+ URLize:
+ Aliases:
+ - urlize
+ Args:
+ - s
+ Description: URLize returns the strings s formatted as an URL.
+ Examples: []
--- /dev/null
+# We use the front matter keywords field to determine related content. To
+# ensure consistency, during site build we validate each keyword against the
+# entries in data/keywords.yaml.
+
+# As of March 5, 2025, this feature is experimental, pending usability
+# assessment. We anticipate that the number of additions to data/keywords.yaml
+# will decrease over time, though the initial implementation will require some
+# effort.
+
++- decorator
++- filter
+- highlight
+- menu
++- metadata
++- process
+- random
+- resource
--- /dev/null
- [[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."
+ no_query_params = true
+ link = "https://www.jetbrains.com/go/?utm_source=OSS&utm_medium=referral&utm_campaign=hugo"
+ logo = "images/sponsors/goland.svg"
+ bgcolor = "#f4f4f4"
+
+[[banners]]
+ name = "CloudCannon"
+ link = "https://cloudcannon.com/hugo-cms/?utm_campaign=HugoSponsorship&utm_content=gohugo&utm_medium=banner&utm_source=sponsor"
+ 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'"
--- /dev/null
- # See https://github.com/gohugoio/hugo/issues/13806.
- ignoreLogs = ['warning-frontmatter-params-overrides']
-
+baseURL = "https://gohugo.io/"
+defaultContentLanguage = "en"
+enableEmoji = true
+pluralizeListTitles = false
+timeZone = "Europe/Oslo"
+title = "Hugo"
+
+# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
+disableAliases = true
+
- [markup.goldmark.extensions.typographer]
- disable = false
+[build]
+ [build.buildStats]
+ disableIDs = true
+ enable = true
+ [[build.cachebusters]]
+ source = "assets/notwatching/hugo_stats\\.json"
+ target = "css"
+ [[build.cachebusters]]
+ source = "(postcss|tailwind)\\.config\\.js"
+ target = "css"
+
+[caches]
+ [caches.images]
+ dir = ":cacheDir/images"
+ maxAge = "1440h"
+ [caches.getresource]
+ dir = ':cacheDir/:project'
+ maxAge = "1h"
+
+[[cascade]]
+ [cascade.params]
+ hide_in_this_section = true
+ show_publish_date = true
+ [cascade.target]
+ kind = 'page'
+ path = '{/news/**}'
+[[cascade]]
+ [cascade.params]
+ searchable = true
+ [cascade.target]
+ kind = 'page'
+[[cascade]]
+ [cascade.params]
+ searchable = false
+ [cascade.target]
+ kind = '{home,section,taxonomy,term}'
+
+[frontmatter]
+ date = ['date'] # do not add publishdate; it will affect page sorting
+ expiryDate = ['expirydate']
+ lastmod = [':git', 'lastmod', 'publishdate', 'date']
+ publishDate = ['publishdate', 'date']
+
+[languages]
+ [languages.en]
+ languageCode = "en-US"
+ languageName = "English"
+ weight = 1
+
+[markup]
+ [markup.goldmark]
+ [markup.goldmark.extensions]
- lang = 'en'
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+ [markup.goldmark.parser]
+ autoDefinitionTermID = true
++ wrapStandAloneImageWithinParagraph = false
+ [markup.goldmark.parser.attribute]
+ block = true
+ [markup.highlight]
+ lineNumbersInTable = false
+ noClasses = false
+ style = 'solarized-dark'
+ wrapperClass = 'highlight not-prose'
+
+[mediaTypes]
+ [mediaTypes."text/netlify"]
+ delimiter = ""
+
+[module]
+ [module.hugoVersion]
+ min = "0.144.0"
+ [[module.mounts]]
+ source = "assets"
+ target = "assets"
+ [[module.mounts]]
+ source = 'content/en'
+ target = 'content'
++ [module.mounts.sites.matrix]
++ languages = ['en']
+ [[module.mounts]]
+ disableWatch = true
+ source = "hugo_stats.json"
+ target = "assets/notwatching/hugo_stats.json"
+
+[outputFormats]
+ [outputFormats.redir]
+ baseName = "_redirects"
+ isPlainText = true
+ mediatype = "text/netlify"
+ [outputFormats.headers]
+ baseName = "_headers"
+ isPlainText = true
+ mediatype = "text/netlify"
+ notAlternative = true
+
+[outputs]
+ home = ["html", "rss", "redir", "headers"]
+ page = ["html"]
+ section = ["html"]
+ taxonomy = ["html"]
+ term = ["html"]
+
+[params]
+ description = "The world’s fastest framework for building websites"
+ ghrepo = "https://github.com/gohugoio/hugoDocs/"
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+ [params.social.mastodon]
+ url = "https://fosstodon.org/@gohugoio"
+
+[related]
+ includeNewer = true
+ threshold = 80
+ toLower = true
+ [[related.indices]]
+ name = 'keywords'
+ weight = 1
+
+[security]
+ [security.funcs]
+ getenv = ['^HUGO_', '^REPOSITORY_URL$', '^BRANCH$']
+
+[server]
+ [[server.headers]]
+ for = "/*"
+ [server.headers.values]
+ X-Frame-Options = "DENY"
+ X-XSS-Protection = "1; mode=block"
+ X-Content-Type-Options = "nosniff"
+ Referrer-Policy = "no-referrer"
+ [[server.headers]]
+ for = "/**.{css,js}"
+
+[services]
+ [services.googleAnalytics]
+ ID = 'G-MBZGKNMDWC'
+
+[taxonomies]
+ category = 'categories'
+
+######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
++
+[menus]
+ [[menus.global]]
+ identifier = 'news'
+ name = 'News'
+ pageRef = '/news/'
+ weight = 1
+ [[menus.global]]
+ identifier = 'docs'
+ name = 'Docs'
+ url = '/documentation/'
+ weight = 5
+ [[menus.global]]
+ identifier = 'themes'
+ name = 'Themes'
+ url = 'https://themes.gohugo.io/'
+ weight = 10
+ [[menus.global]]
+ identifier = 'community'
+ name = 'Community'
+ post = 'external'
+ url = 'https://discourse.gohugo.io/'
+ weight = 150
+ [[menus.global]]
+ identifier = 'github'
+ name = 'GitHub'
+ post = 'external'
+ url = 'https://github.com/gohugoio/hugo'
+ weight = 200
--- /dev/null
- class=" relative flex flex-grow basis-0 items-center min-w-24 max-w-3xl overflow-x-auto">
+<header
+ x-data="navbar"
+ class="print:hidden sticky top-0 z-50 bg-blue-950 flex flex-none flex-wrap items-center justify-between px-4 py-5 shadow-md shadow-slate-900/5 transition duration-500 sm:px-6 lg:px-8 dark:shadow-none"
+ :class="$store.nav.scroll.atTop ? '': 'bg-blue-950/80'">
+ <div class="relative flex basis-0 items-center mr-2 lg:mr-8">
+ {{ with site.Home }}
+ <a
+ class="text-white text-xl font-bold upper"
+ href="{{ .RelPermalink }}"
+ aria-label="{{ .LinkTitle }}"
+ >HUGO</a
+ >
+ {{ end }}
+ </div>
+ <div
- <div class="-my-5 pl-2 grow-0">
++ class="relative hidden sm:flex flex-grow basis-0 items-center min-w-24 max-w-3xl overflow-x-auto">
+ {{ range .Site.Menus.global }}
+ <a
+ href="{{ .URL }}"
+ class="font-semibold text-gray-300 hover:text-gray-400 ml-4"
+ >{{ .Name }}</a
+ >
+ {{ end }}
+
+
+ <div class="hidden 2xl:block ml-8 text-xs text-gray-400 dark:text-gray-400">
+ {{ with hugo.Version }}
+
+ Built with Hugo
+ {{ if strings.Contains . "-DEV" }}
+ v{{ . }}
+ {{ else }}
+ <a
+ class="text-blue-600 hover:text-blue-500 ml-1"
+ href="{{ printf `https://github.com/gohugoio/hugo/releases/tag/v%s` . }}"
+ >v{{ . }}</a
+ >
+ {{ end }}
+ {{ end }}
+
+ </div>
+ </div>
+
- class="relative ml-0 md:ml-8 flex content-center basis-0 justify-end gap-0 sm:gap-1 xl:grow-1">
++ <div class="-my-5 pl-0 sm:pl-2 grow-0 flex items-center gap-0">
+ {{/* Search. */}}
+ {{ partial "layouts/search/input.html" . }}
++ {{/* Theme selector - shown inline on mobile */}}
++ <div class="sm:hidden">
++ {{ partial "layouts/header/theme.html" . }}
++ </div>
+ </div>
+ <div
- {{/* Theme selector. */}}
++ 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 - hidden on mobile (shown above) */}}
+ {{ partial "layouts/header/theme.html" . }}
+
+ {{/* Social. */}}
+ <div
+ class="hidden sm:block ml-2 sm:ml-6 h-6 fill-slate-400 group-hover:fill-slate-500 dark:group-hover:fill-slate-300">
+ {{ partial "layouts/header/githubstars.html" . }}
+ </div>
+ <div
+ class="hidden sm:block ml-2 sm:ml-6 h-6">
+ {{ partial "layouts/header/mastodon.html" . }}
+ </div>
+ </div>
++
++ {{/* Mobile menu hamburger button - only visible on small screens */}}
++ <button
++ @click="$store.nav.mobileMenu.toggle()"
++ class="sm:hidden p-2 ml-2 text-gray-300 hover:text-white rounded-md hover:bg-blue-900 transition-colors"
++ aria-label="Open menu"
++ :aria-expanded="$store.nav.mobileMenu.open">
++ <svg class="w-6 h-6">
++ <use href="#icon--bars-3"></use>
++ </svg>
++ </button>
+</header>
++
++{{/* Mobile menu panel */}}
++{{ partial "layouts/header/mobilemenu.html" . }}
--- /dev/null
--- /dev/null
++{{/* Mobile menu overlay and panel - only visible on small screens */}}
++<div
++ x-data
++ x-show="$store.nav.mobileMenu.open"
++ x-transition:enter="transition-opacity ease-out duration-200"
++ x-transition:enter-start="opacity-0"
++ x-transition:enter-end="opacity-100"
++ x-transition:leave="transition-opacity ease-in duration-150"
++ x-transition:leave-start="opacity-100"
++ x-transition:leave-end="opacity-0"
++ class="sm:hidden fixed inset-0 z-50 bg-gray-900/50 backdrop-blur-sm"
++ @click="$store.nav.mobileMenu.close()"
++ x-cloak>
++</div>
++
++{{/* Mobile menu panel */}}
++<div
++ x-data
++ x-show="$store.nav.mobileMenu.open"
++ x-transition:enter="transition ease-out duration-200"
++ x-transition:enter-start="translate-x-full"
++ x-transition:enter-end="translate-x-0"
++ x-transition:leave="transition ease-in duration-150"
++ x-transition:leave-start="translate-x-0"
++ x-transition:leave-end="translate-x-full"
++ class="sm:hidden fixed top-0 right-0 z-50 h-full w-72 bg-blue-950 shadow-xl"
++ @keydown.escape.window="$store.nav.mobileMenu.close()"
++ x-cloak>
++
++ {{/* Header with close button */}}
++ <div class="flex items-center justify-between px-4 py-5">
++ <span class="text-white text-xl font-bold">Menu</span>
++ <button
++ @click="$store.nav.mobileMenu.close()"
++ class="p-2 text-gray-300 hover:text-white rounded-md hover:bg-blue-900 transition-colors"
++ aria-label="Close menu">
++ <svg class="w-6 h-6">
++ <use href="#icon--x-mark"></use>
++ </svg>
++ </button>
++ </div>
++
++ {{/* Navigation links */}}
++ <nav class="px-4 py-2">
++ <ul class="space-y-1">
++ {{ range .Site.Menus.global }}
++ <li>
++ <a
++ href="{{ .URL }}"
++ @click="$store.nav.mobileMenu.close()"
++ class="block px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
++ {{ .Name }}
++ </a>
++ </li>
++ {{ end }}
++ </ul>
++ </nav>
++
++ {{/* Divider */}}
++ <div class="mx-4 my-4 border-t border-blue-800"></div>
++
++ {{/* Search trigger */}}
++ <div class="px-4 py-2">
++ <button
++ @click="$dispatch('search-toggle'); $store.nav.mobileMenu.close()"
++ class="w-full flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
++ <svg class="w-5 h-5 fill-current">
++ <use href="#icon--search"></use>
++ </svg>
++ Search
++ </button>
++ </div>
++
++ {{/* Divider */}}
++ <div class="mx-4 my-4 border-t border-blue-800"></div>
++
++ {{/* Social links */}}
++ <div class="px-4 py-2 space-y-1">
++ {{/* GitHub */}}
++ {{ with partialCached "helpers/funcs/get-github-info.html" . "-" }}
++ <a
++ href="{{ .html_url | safeURL }}"
++ target="_blank"
++ class="flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
++ <svg class="w-5 h-5 fill-current">
++ <use href="#icon--github"></use>
++ </svg>
++ GitHub
++ <span class="ml-auto text-sm text-gray-400">{{ .stargazers_count }} stars</span>
++ </a>
++ {{ end }}
++
++ {{/* Mastodon */}}
++ {{ with site.Params.social.mastodon.url }}
++ <a
++ href="{{ . }}"
++ target="_blank"
++ class="flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
++ <svg class="w-5 h-5" viewBox="0 0 75 79" fill="currentColor">
++ <path d="M73.8393 17.4898C72.6973 9.00165 65.2994 2.31235 56.5296 1.01614C55.05 0.797115 49.4441 0 36.4582 0H36.3612C23.3717 0 20.585 0.797115 19.1054 1.01614C10.5798 2.27644 2.79399 8.28712 0.904997 16.8758C-0.00358524 21.1056 -0.100549 25.7949 0.0682394 30.0965C0.308852 36.2651 0.355538 42.423 0.91577 48.5665C1.30307 52.6474 1.97872 56.6957 2.93763 60.6812C4.73325 68.042 12.0019 74.1676 19.1233 76.6666C26.7478 79.2728 34.9474 79.7055 42.8039 77.9162C43.6682 77.7151 44.5217 77.4817 45.3645 77.216C47.275 76.6092 49.5123 75.9305 51.1571 74.7385C51.1797 74.7217 51.1982 74.7001 51.2112 74.6753C51.2243 74.6504 51.2316 74.6229 51.2325 74.5948V68.6416C51.2321 68.6154 51.2259 68.5896 51.2142 68.5661C51.2025 68.5426 51.1858 68.522 51.1651 68.5058C51.1444 68.4896 51.1204 68.4783 51.0948 68.4726C51.0692 68.4669 51.0426 68.467 51.0171 68.4729C45.9835 69.675 40.8254 70.2777 35.6502 70.2682C26.7439 70.2682 24.3486 66.042 23.6626 64.2826C23.1113 62.762 22.7612 61.1759 22.6212 59.5646C22.6197 59.5375 22.6247 59.5105 22.6357 59.4857C22.6466 59.4609 22.6633 59.4391 22.6843 59.422C22.7053 59.4048 22.73 59.3929 22.7565 59.3871C22.783 59.3813 22.8104 59.3818 22.8367 59.3886C27.7864 60.5826 32.8604 61.1853 37.9522 61.1839C39.1768 61.1839 40.3978 61.1839 41.6224 61.1516C46.7435 61.008 52.1411 60.7459 57.1796 59.7621C57.3053 59.7369 57.431 59.7154 57.5387 59.6831C65.4861 58.157 73.0493 53.3672 73.8178 41.2381C73.8465 40.7606 73.9184 36.2364 73.9184 35.7409C73.9219 34.0569 74.4606 23.7949 73.8393 17.4898Z" />
++ </svg>
++ Mastodon
++ </a>
++ {{ end }}
++ </div>
++</div>
--- /dev/null
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--chevron-right" viewBox="0 0 20 20">
+ <path
+ fill-rule="evenodd"
+ d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z"
+ clip-rule="evenodd"></path>
+ </symbol>
+</svg>
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--search" viewBox="0 0 20 20">
+ <path
+ d="M16.293 17.707a1 1 0 0 0 1.414-1.414l-1.414 1.414ZM9 14a5 5 0 0 1-5-5H2a7 7 0 0 0 7 7v-2ZM4 9a5 5 0 0 1 5-5V2a7 7 0 0 0-7 7h2Zm5-5a5 5 0 0 1 5 5h2a7 7 0 0 0-7-7v2Zm8.707 12.293-3.757-3.757-1.414 1.414 3.757 3.757 1.414-1.414ZM14 9a4.98 4.98 0 0 1-1.464 3.536l1.414 1.414A6.98 6.98 0 0 0 16 9h-2Zm-1.464 3.536A4.98 4.98 0 0 1 9 14v2a6.98 6.98 0 0 0 4.95-2.05l-1.414-1.414Z" />
+ </symbol>
+</svg>
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--anchor" viewBox="0 0 24 24">
+ <path d="M0 0h24v24H0z" fill="none" />
+ <path
+ d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z" />
+ </symbol>
+</svg>
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--copy" viewBox="0 0 24 24">
+ <path
+ fill="none"
+ stroke="currentColor"
+ stroke-width="1.5"
+ aria-hidden="true"
+ stroke-linecap="round"
+ stroke-linejoin="round"
+ d="M9 12h3.75M9 15h3.75M9 18h3.75m3 .75H18a2.25 2.25 0 002.25-2.25V6.108c0-1.135-.845-2.098-1.976-2.192a48.424 48.424 0 00-1.123-.08m-5.801 0c-.065.21-.1.433-.1.664 0 .414.336.75.75.75h4.5a.75.75 0 00.75-.75 2.25 2.25 0 00-.1-.664m-5.8 0A2.251 2.251 0 0113.5 2.25H15c1.012 0 1.867.668 2.15 1.586m-5.8 0c-.376.023-.75.05-1.124.08C9.095 4.01 8.25 4.973 8.25 6.108V8.25m0 0H4.875c-.621 0-1.125.504-1.125 1.125v11.25c0 .621.504 1.125 1.125 1.125h9.75c.621 0 1.125-.504 1.125-1.125V9.375c0-.621-.504-1.125-1.125-1.125H8.25zM6.75 12h.008v.008H6.75V12zm0 3h.008v.008H6.75V15zm0 3h.008v.008H6.75V18z"></path>
+ </symbol>
+</svg>
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--github" viewBox="0 0 24 24" aria-hidden="true">
+ <path fill-rule="evenodd" clip-rule="evenodd" d="M12 2C6.477 2 2 6.463 2 11.97c0 4.404 2.865 8.14 6.839 9.458.5.092.682-.216.682-.48 0-.236-.008-.864-.013-1.695-2.782.602-3.369-1.337-3.369-1.337-.454-1.151-1.11-1.458-1.11-1.458-.908-.618.069-.606.069-.606 1.003.07 1.531 1.027 1.531 1.027.892 1.524 2.341 1.084 2.91.828.092-.643.35-1.083.636-1.332-2.22-.251-4.555-1.107-4.555-4.927 0-1.088.39-1.979 1.029-2.675-.103-.252-.446-1.266.098-2.638 0 0 .84-.268 2.75 1.022A9.607 9.607 0 0 1 12 6.82c.85.004 1.705.114 2.504.336 1.909-1.29 2.747-1.022 2.747-1.022.546 1.372.202 2.386.1 2.638.64.696 1.028 1.587 1.028 2.675 0 3.83-2.339 4.673-4.566 4.92.359.307.678.915.678 1.846 0 1.332-.012 2.407-.012 2.734 0 .267.18.577.688.48 3.97-1.32 6.833-5.054 6.833-9.458C22 6.463 17.522 2 12 2Z"></path>
+ </symbol>
+</svg>
+
+{{/* https://heroicons.com/mini exclamation-circle */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--exclamation-circle" viewBox="0 0 24 24" aria-hidden="true">
+ <path fill-rule="evenodd" d="M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0Zm-8-5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0v-4.5A.75.75 0 0 1 10 5Zm0 10a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z" clip-rule="evenodd" />
+ </symbol>
+</svg>
+
+{{/* https://heroicons.com/mini exclamation-triangle */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--exclamation-triangle" viewBox="0 0 24 24" aria-hidden="true">
+ <path fill-rule="evenodd" d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495ZM10 5a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 10 5Zm0 9a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z" clip-rule="evenodd" />
+ </symbol>
+</svg>
+
+{{/* https://heroicons.com/mini information-circle */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--information-circle" viewBox="0 0 24 24" aria-hidden="true">
+ <path fill-rule="evenodd" d="M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0Zm-7-4a1 1 0 1 1-2 0 1 1 0 0 1 2 0ZM9 9a.75.75 0 0 0 0 1.5h.253a.25.25 0 0 1 .244.304l-.459 2.066A1.75 1.75 0 0 0 10.747 15H11a.75.75 0 0 0 0-1.5h-.253a.25.25 0 0 1-.244-.304l.459-2.066A1.75 1.75 0 0 0 9.253 9H9Z" clip-rule="evenodd" />
+ </symbol>
+</svg>
+
+{{/* https://heroicons.com/mini light-bulb */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--light-bulb" viewBox="0 0 24 24" aria-hidden="true">
+ <path d="M10 1a6 6 0 0 0-3.815 10.631C7.237 12.5 8 13.443 8 14.456v.644a.75.75 0 0 0 .572.729 6.016 6.016 0 0 0 2.856 0A.75.75 0 0 0 12 15.1v-.644c0-1.013.762-1.957 1.815-2.825A6 6 0 0 0 10 1ZM8.863 17.414a.75.75 0 0 0-.226 1.483 9.066 9.066 0 0 0 2.726 0 .75.75 0 0 0-.226-1.483 7.553 7.553 0 0 1-2.274 0Z" />
+ </symbol>
+</svg>
++
++{{/* https://heroicons.com/outline bars-3 (hamburger menu) */}}
++<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
++ <symbol id="icon--bars-3" viewBox="0 0 24 24" fill="none" aria-hidden="true">
++ <path stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" />
++ </symbol>
++</svg>
++
++{{/* https://heroicons.com/outline x-mark (close) */}}
++<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
++ <symbol id="icon--x-mark" viewBox="0 0 24 24" fill="none" aria-hidden="true">
++ <path stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />
++ </symbol>
++</svg>
--- /dev/null
- Markdown headings (level 6) which means they are members of .Fragments. This
+{{- /*
+Renders the glossary of terms.
+
+When you call this shortcode using the {{% %}} notation, the glossary terms are
- {{- $destination = .Path }}
++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
+least not right now. Instead, we want to link to the ids rendered by this
+shortcode.
+
+@example {{% glossary %}}
+*/ -}}
+{{- $path := "/quick-reference/glossary" }}
+{{- with site.GetPage $path }}
+
+ {{- /* Build and render alphabetical index. */}}
+ {{- $m := dict }}
+ {{- range $p := .Pages.ByTitle }}
+ {{- $k := substr .Title 0 1 | strings.ToUpper }}
+ {{- if index $m $k }}
+ {{- continue }}
+ {{- end }}
+ {{- $anchor := path.BaseName .Path | anchorize }}
+ {{- $m = merge $m (dict $k $anchor) }}
+ {{- end }}
+ {{- range $k, $v := $m }}
+[{{ $k }}](#{{ $v }}) {{/* Do not indent. */}}
+ {{- end }}
+
+ {{/* Render glossary terms. */}}
+ {{- range $p := .Pages.ByTitle }}
+{{ .Title }}{{/* Do not indent. */}}
+: {{ .RawContent | strings.TrimSpace | safeHTML }}{{/* Do not indent. */}}
+ {{ with .Params.reference }}
+ {{- $destination := "" }}
+ {{- with $u := urls.Parse . }}
+ {{- if $u.IsAbs }}
+ {{- $destination = $u.String }}
+ {{- else }}
+ {{- with site.GetPage $u.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 }}
+ {{- end }}
+ {{- end }}
+: See [details]({{ $destination }}).{{/* Do not indent. */}}
+ {{- end }}
+ {{ end }}
+
+{{- else }}
+ {{- errorf "The %q shortcode was unable to get %s: see %s" .Name $path .Position}}
+{{- end }}
--- /dev/null
- command = "hugo --gc --minify"
+[build]
+ publish = "public"
- HUGO_VERSION = "0.152.2"
++ command = "npm ls && hugo --gc --minify"
+
+ [build.environment]
- command = "hugo --gc --minify --enableGitInfo"
++ HUGO_VERSION = "0.155.3"
+
+[context.production.environment]
+ HUGO_ENV = "production"
+ HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
- command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo"
++ command = "npm ls && hugo --gc --minify --enableGitInfo"
+
+ [context.split1.environment]
+ HUGO_ENV = "production"
+
+[context.deploy-preview]
- command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
++ command = "npm ls && hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo"
+
+[context.branch-deploy]
++ command = "npm ls && hugo --gc --minify -b $DEPLOY_PRIME_URL"
+
+[context.next.environment]
+ HUGO_ENABLEGITINFO = "true"
+
+[[headers]]
+ for = "/*.jpg"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.png"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.css"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.js"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.ttf"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
--- /dev/null
- "@alpinejs/focus": "~3.15.3",
- "@alpinejs/persist": "~3.15.3",
- "@hotwired/turbo": "~8.0.20",
- "alpinejs": "~3.15.3"
+{
+ "name": "hugoDocs",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "scripts": {
+ "test": "echo \"Error: no test specified\" && exit 1"
+ },
+ "author": "",
+ "license": "",
+ "devDependencies": {
+ "@awmottaz/prettier-plugin-void-html": "~2.0.0",
+ "@tailwindcss/cli": "~4.1.18",
+ "@tailwindcss/typography": "~0.5.19",
+ "prettier": "~3.7.4",
+ "prettier-plugin-go-template": "~0.0.15",
+ "tailwindcss": "~4.1.18"
+ },
+ "dependencies": {
++ "@alpinejs/focus": "3.15.3",
++ "@alpinejs/persist": "3.15.3",
++ "@hotwired/turbo": "8.0.20",
++ "alpinejs": "3.15.3"
+ }
+}
projects / brevno-suite / hugo / commitdiff