content: Miscellaneous edits

Author: jmooring

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`:

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
 

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
 

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

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&nbsp;`".*"`.
+: (`string`) A [regular expression](g) matching the tags to include when extracting EXIF data. To include all available tags, set this value to&nbsp;`".*"`.
 
 > [!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/

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

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

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/

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.

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.

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 }}

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.

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

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/

layouts/shortcodes/root-configuration-keys.html

@@ -5,20 +5,40 @@
 @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 "<a href=%q><code>%s</code></a>" .RelPermalink $key) }}
+{{- range $k, $v := $s.Values }}
+  {{- $path := printf "/configuration/%s" $v }}
+  {{- with site.GetPage $path }}
+    {{- $links = $links | append (printf "<a href=%q><code>%s</code></a>" .RelPermalink $k) }}
+  {{- else }}
+    {{- errorf "The %q shortcode was unable to find the page %s. See %s." $.Name $path $.Position }}
   {{- end }}
 {{- end }}