diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md index 43ea3f33b..9bc05057f 100644 --- a/content/en/configuration/all.md +++ b/content/en/configuration/all.md @@ -123,7 +123,7 @@ ignoreCache : (`bool`) Whether to ignore the cache directory. Default is `false`. ignoreFiles -: (`[]string]`) A slice of regular expressions used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts]. +: (`[]string]`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts]. ignoreLogs : (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`]. @@ -298,8 +298,8 @@ 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: -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 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]. On Unix systems, per the [XDG base directory specification], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. +1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) vendors, please read their documentation. For an CircleCI example, see [this configuration]. +1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir] function. On Unix systems, per the [XDG base directory specification], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`. 1. In a `hugo_cache_$USER` directory below the OS temp dir. To determine the current `cacheDir`: diff --git a/content/en/configuration/build.md b/content/en/configuration/build.md index 4f69bf676..116294f05 100644 --- a/content/en/configuration/build.md +++ b/content/en/configuration/build.md @@ -18,7 +18,7 @@ cachebusters : See the [cache busters](#cache-busters) section below. noJSConfigInAssets -: (`bool`) Whether to disable writing a `jsconfig.json` into your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. +: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. useResourceCacheWhen : (`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`. @@ -48,10 +48,10 @@ The `build.cachebusters` configuration option was added to support development u When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example. source -: (`string`) A regular expression matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`. +: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`. target -: (`string`) A regular expression matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`. +: (`string`) A [regular expression](g) matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`. ## Build stats diff --git a/content/en/configuration/caches.md b/content/en/configuration/caches.md index af2e2c8a8..03b499dcb 100644 --- a/content/en/configuration/caches.md +++ b/content/en/configuration/caches.md @@ -16,7 +16,7 @@ dir : (`string`) The absolute file system path where the cached files will be stored. You can begin the path with the `:cacheDir` or `:resourceDir` token. These tokens will be replaced with the actual configured cache directory and resource directory paths, respectively. maxAge -: (`string`) The `duration` a cached entry remains valid before being evicted. A value of `0` disables the cache. A value of `-1` means the cache entry never expires (the default). +: (`string`) The [duration](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). ## Tokens diff --git a/content/en/configuration/deployment.md b/content/en/configuration/deployment.md index f0beb12d0..fad50da63 100644 --- a/content/en/configuration/deployment.md +++ b/content/en/configuration/deployment.md @@ -34,7 +34,7 @@ matchers : (`[]*Matcher`) A slice of [matchers](#matchers-1). order -: (`[]string`) An ordered slice of [RE2] regular expressions that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary 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. @@ -45,8 +45,6 @@ targets workers : (`int`) The number of concurrent workers to use when uploading files. Default is `10`. -[RE2]: https://github.com/google/re2/wiki/Syntax/ - ## Targets A target represents a deployment target such as "staging" or "production". @@ -93,7 +91,7 @@ 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`) An [RE2] regular expression used to match paths. Paths are converted to use forward slashes (`/`) before matching. +: (`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 diff --git a/content/en/configuration/imaging.md b/content/en/configuration/imaging.md index 286c30f14..13ecf9c26 100644 --- a/content/en/configuration/imaging.md +++ b/content/en/configuration/imaging.md @@ -20,7 +20,7 @@ resampleFilter = 'box' {{< /code-toggle >}} anchor -: (`string`) When using the Crop or Fill method, the anchor determines the placement of the crop box. One of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. +: (`string`) 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`. bgColor : (`string`) The background color of the resulting image. Applicable when converting from a format that supports transparency to a format that does not support transparency, for example, when converting from PNG to JPEG. Expressed as an RGB [hexadecimal] value. Default is `#ffffff`. @@ -55,12 +55,15 @@ disableLatLong : (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`. excludeFields -: (`string`) A regular expression matching the tags to exclude when extracting EXIF data. +: (`string`) A [regular expression](g) matching the tags to exclude when extracting EXIF data. includeFields -: (`string`) A regular expression 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 tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`. > [!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. + +[`Crop`]: /methods/resource/crop/ +[`Fill`]: /methods/resource/fill/ diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md index 45634329a..540cfd34f 100644 --- a/content/en/configuration/languages.md +++ b/content/en/configuration/languages.md @@ -44,9 +44,9 @@ disabled languageCode : (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate: - - The `lang` attribute of the `html` element in the [built-in alias template] - - The `language` element in the [built-in RSS template] - - The `locale` property in the [built-in OpenGraph template] + - 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] Access this value from a template using the [`Language.LanguageCode`] method on a `Site` or `Page` object. @@ -185,9 +185,9 @@ public [`Language.LanguageName`]: /methods/site/language/#languagename [`Language.Weight`]: /methods/site/language/#weight [`Title`]: /methods/site/title/ -[built-in alias template]: {{% eturl alias %}} -[built-in OpenGraph template]: {{% eturl opengraph %}} -[built-in RSS template]: {{% eturl rss %}} +[embedded alias template]: {{% eturl alias %}} +[embedded OpenGraph template]: {{% eturl opengraph %}} +[embedded RSS template]: {{% eturl rss %}} [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 [translating by file name]: /content-management/multilingual/#translation-by-file-name diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md index 3006f6f18..b6135cee5 100644 --- a/content/en/configuration/markup.md +++ b/content/en/configuration/markup.md @@ -120,7 +120,7 @@ duplicateResourceFiles : (`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. + > 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`. @@ -159,7 +159,7 @@ renderHooks.link.enableDefault : (`bool`) Whether to enable the [embedded link render hook]. Default is `false`. > [!note] - > The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. + > The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites. renderer.hardWraps : (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`. @@ -335,3 +335,7 @@ ordered [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 +[AsciiDoc]: https://asciidoc.org/ +[Emacs Org Mode]: https://orgmode.org/ +[Pandoc]: https://www.pandoc.org/ +[reStructuredText]: https://docutils.sourceforge.io/rst.html diff --git a/content/en/configuration/output-formats.md b/content/en/configuration/output-formats.md index a42ef313e..2627c6df4 100644 --- a/content/en/configuration/output-formats.md +++ b/content/en/configuration/output-formats.md @@ -95,7 +95,7 @@ You can create new output formats as needed. For example, you may wish to create ### Step 1 -You must specify a media type when you create an output format. Because `application/atom+xml`, the media type for Atom feeds, is not a [default media type], begin by creating a new one: +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'] @@ -202,7 +202,7 @@ Output format|Template path [configure media types]: /configuration/media-types/ [configure outputs]: /configuration/outputs/ [configured media types]: /configuration/media-types/ -[default media type]: /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/ diff --git a/content/en/configuration/security.md b/content/en/configuration/security.md index a7d0cc578..1c128c1f2 100644 --- a/content/en/configuration/security.md +++ b/content/en/configuration/security.md @@ -19,19 +19,19 @@ exec.allow : (`[]string`) A slice of [regular expressions](g) matching the names of external executables that Hugo is allowed to run. exec.osEnv -: (`[]string`) A slice of regular expressions matching the names of operating system environment variables that Hugo is allowed to access. +: (`[]string`) A slice of [regular expression](g) matching the names of operating system environment variables that Hugo is allowed to access. funcs.getenv -: (`[]string`) A slice of regular expressions matching the names of operating system environment variables that Hugo is allowed to access with the [`os.Getenv`] function. +: (`[]string`) A slice of [regular expression](g) matching the names of operating system environment variables that Hugo is allowed to access with the [`os.Getenv`] function. http.methods -: (`[]string`) A slice of regular expressions matching the HTTP methods that the [`resources.GetRemote`] function is allowed to use. +: (`[]string`) A slice of [regular expression](g) matching the HTTP methods that the [`resources.GetRemote`] function is allowed to use. http.mediaTypes -: (`[]string`) Applicable to the `resources.GetRemote` function, a slice of regular expressions matching the `Content-Type` in HTTP responses that Hugo trusts, bypassing file content analysis for media type detection. +: (`[]string`) Applicable to the `resources.GetRemote` function, a slice of [regular expression](g) matching the `Content-Type` in HTTP responses that Hugo trusts, bypassing file content analysis for media type detection. http.urls -: (`[]string`) A slice of regular expressions matching the URLs that the `resources.GetRemote` function is allowed to access. +: (`[]string`) A slice of [regular expression](g) matching the URLs that the `resources.GetRemote` function is allowed to access. > [!note] > Setting an allow list to the string `none` will completely disable the associated feature. diff --git a/content/en/configuration/server.md b/content/en/configuration/server.md index c38ece466..92f0f0cfa 100644 --- a/content/en/configuration/server.md +++ b/content/en/configuration/server.md @@ -37,7 +37,7 @@ fromHeaders fromRe : {{< new-in 0.144.0 />}} -: (`string`) A regular expression 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. +: (`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. diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index 68433f384..3468bb728 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -99,7 +99,7 @@ Returns a persistent “scratch pad” to store and manipulate data. The main us ### EnableAllLanguages -By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages. +By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file. Use this method to activate the content adapter for all languages. ```go-html-template {file="content/books/_content.gotmpl"} {{ .EnableAllLanguages }} diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index 67c87a68d..1df84afc4 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -88,7 +88,7 @@ Use any of the following logical operators: `like` : {{< new-in 0.116.0 />}} -: (`bool`) Reports whether the given field value matches the regular expression 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. +: (`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. diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index b83a642b1..7866da9f7 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -230,7 +230,7 @@ mediaTypes = ['^image/avif$','^application/vnd\.api\+json$'] Note that the entry above is: - An _addition_ to the allowlist; it does not _replace_ the allowlist -- An array of regular expressions +- An array of [regular expression](g) [allowlist]: https://en.wikipedia.org/wiki/Whitelist [Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type diff --git a/content/en/methods/menu-entry/Name.md b/content/en/methods/menu-entry/Name.md index d4174b4e7..706d0f8c8 100644 --- a/content/en/methods/menu-entry/Name.md +++ b/content/en/methods/menu-entry/Name.md @@ -11,7 +11,7 @@ params: If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`]. -If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. +If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. [`LinkTitle`]: /methods/page/linktitle/ [`Title`]: /methods/page/title/ diff --git a/layouts/shortcodes/root-configuration-keys.html b/layouts/shortcodes/root-configuration-keys.html index 8d51ee639..46a6e074f 100644 --- a/layouts/shortcodes/root-configuration-keys.html +++ b/layouts/shortcodes/root-configuration-keys.html @@ -5,20 +5,40 @@ Renders a comma-separated list of links to the root key configuration pages. @example {{< root-configuration-keys >}} */ -}} {{/* prettier-ignore-end */ -}} -{{- $keys := slice }} -{{- range $k, $_ := site.Data.docs.config }} +{{- /* Create scratch map of key:filename. */}} +{{- $s := newScratch }} +{{- range $k, $v := site.Data.docs.config }} {{- if or (reflect.IsMap .) (reflect.IsSlice .) }} - {{- $keys = $keys | append $k }} + {{- $s.Set $k ($k | humanize | anchorize) }} {{- end }} {{- end }} -{{- $keys = $keys | append "uglyURLs" }} -{{- $keys = $keys | complement (slice "author" "ignoreFiles" "staticDir") }} -{{- $keys = apply $keys "strings.ToLower" "." | sort }} + +{{/* Deprecated. */}} +{{- $s.Delete "author" }} + +{{/* Use mounts instead. */}} +{{- $s.Delete "staticDir" }} +{{- $s.Delete "ignoreFiles" }} + +{{/* This key is "HTTPCache" not "httpCache". */}} +{{- $s.Set "HTTPCache" "http-cache" }} + +{{/* This key is "frontmatter" not "frontMatter" */}} +{{- $s.Set "frontmatter" "front-matter" }} + +{{/* The page title is "Related content" not "related". */}} +{{- $s.Set "related" "related-content" }} + +{{/* It can be configured as bool or map; we want to show map. */}} +{{- $s.Set "uglyURLs" "ugly-urls" }} {{- $links := slice }} -{{- range $key := $keys }} - {{- with site.GetPage (printf "/configuration/%s" .) }} - {{- $links = $links | append (printf "%s" .RelPermalink $key) }} +{{- range $k, $v := $s.Values }} + {{- $path := printf "/configuration/%s" $v }} + {{- with site.GetPage $path }} + {{- $links = $links | append (printf "%s" .RelPermalink $k) }} + {{- else }} + {{- errorf "The %q shortcode was unable to find the page %s. See %s." $.Name $path $.Position }} {{- end }} {{- end }}