content: Define canonical output format and default site

jmooring · jmooring · commit 33691da51ed6 · 2026-02-06T22:44:10.000-08:00
Closes gohugoio#3339
diff --git a/content/en/_common/methods/output-formats/to-use-this-method.md b/content/en/_common/methods/output-formats/to-use-this-method.md
@@ -0,0 +1,9 @@
+---
+_comment: Do not remove front matter.
+---
+
+To use this method you must first select a specific [output format](g) from a page's [`OutputFormats`][] collection using the [`Get`][] or [`Canonical`][] methods.
+
+[`Canonical`]: /methods/page/outputformats/#canonical
+[`Get`]: /methods/page/outputformats/#get
+[`OutputFormats`]: /methods/page/outputformats/
diff --git a/content/en/_common/methods/page/output-format-methods.md b/content/en/_common/methods/page/output-format-methods.md
diff --git a/content/en/about/features.md b/content/en/about/features.md
@@ -60,7 +60,7 @@ weight: 20
 
 ## Content management
 
-[Multi-dimensional content model]
+[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]
@@ -123,7 +123,7 @@ weight: 20
 [Syntax highlighting]: /content-management/syntax-highlighting/
 [Shortcodes]: /content-management/shortcodes/
 
-[Multi-dimensional content model]: /quick-reference/glossary/#sites-matrix
+[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
 [Content adapters]: /content-management/content-adapters/
 [Taxonomies]: /content-management/taxonomies/
 [Data]: /content-management/data-sources/
diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md
@@ -94,7 +94,7 @@ disableDefaultLanguageRedirect
 
 disableDefaultSiteRedirect
 : {{< new-in 0.154.5 />}}
-: (bool) Whether to disable generation of the alias redirect to the default site. 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`.
+: (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`.
diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md
@@ -212,7 +212,7 @@ backend
 : (`string`) The backend output file format. Default is `html5`.
 
 extensions
-: (`string array`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
+: (`[]string`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
 
   > [!note]
   > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
diff --git a/content/en/configuration/output-formats.md b/content/en/configuration/output-formats.md
@@ -65,7 +65,7 @@ protocol
 : (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`.
 
 rel
-: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
+: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`.
 
 root
 : (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
@@ -41,7 +41,7 @@ The most common front matter fields are `date`, `draft`, `title`, and `weight`,
 [parameters]: #parameters
 
 aliases
-: (`string array`) An array of one or more [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.
+: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
 
 build
 : (`map`) A map of [build options].
@@ -68,7 +68,7 @@ isCJKLanguage
 : (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
 
 keywords
-: (`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
+: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
 
 lastmod
 : (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
@@ -83,13 +83,13 @@ markup
 : (`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
 
 menus
-: (`string`, `string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
 
 modified
 : Alias to [lastmod](#lastmod).
 
 outputs
-: (`string array`) The [output formats] to render. See [configure outputs] for more information.
+: (`[]string`) The [output formats] to render. See [configure outputs] for more information.
 
 params
 : (`map`) A map of custom [page parameters].
diff --git a/content/en/functions/images/Dither.md b/content/en/functions/images/Dither.md
@@ -13,7 +13,7 @@ params:
 ## Options
 
 colors
-: (`string array`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
+: (`[]string`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
 
 [hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
 
diff --git a/content/en/methods/output-format/MediaType.md b/content/en/methods/output-format/MediaType.md
@@ -0,0 +1,36 @@
+---
+title: MediaType
+description: Returns the media type of the given output format.
+categories: []
+keywords: []
+params:
+  functions_and_methods:
+    returnType: media.Type
+    signatures: [OUTPUTFORMAT.MediaType]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+  {{ with .MediaType }}
+    {{ .Type }}       → application/rss+xml
+    {{ .MainType }}   → application
+    {{ .SubType }}    → rss
+  {{ end }}
+{{ end }}
+```
+
+## Methods
+
+### MainType
+
+(`string`) Returns the main type of the output format's media type.
+
+### SubType
+
+(`string`) Returns the subtype of the current format's media type.
+
+### Type
+
+(`string`) Returns the the current format's media type.
diff --git a/content/en/methods/output-format/Name.md b/content/en/methods/output-format/Name.md
@@ -0,0 +1,18 @@
+---
+title: Name
+description: Returns the identifier of the given output format.
+categories: []
+keywords: []
+params:
+  functions_and_methods:
+    returnType: string
+    signatures: [OUTPUTFORMAT.Name]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+  {{ .Name }} → rss
+{{ end }}
+```
diff --git a/content/en/methods/output-format/Permalink.md b/content/en/methods/output-format/Permalink.md
@@ -0,0 +1,18 @@
+---
+title: Permalink
+description: Returns the permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+  functions_and_methods:
+    returnType: string
+    signatures: [OUTPUTFORMAT.Permalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+  {{ .Permalink }} → https://example.org/index.xml
+{{ end }}
+```
diff --git a/content/en/methods/output-format/Rel.md b/content/en/methods/output-format/Rel.md
@@ -0,0 +1,18 @@
+---
+title: Rel
+description: Returns the rel value of the given output format, either the default or as defined in the site configuration.
+categories: []
+keywords: []
+params:
+  functions_and_methods:
+    returnType: string
+    signatures: [OUTPUTFORMAT.Rel]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+  {{ .Rel }} → alternate
+{{ end }}
+```
diff --git a/content/en/methods/output-format/RelPermalink.md b/content/en/methods/output-format/RelPermalink.md
@@ -0,0 +1,18 @@
+---
+title: RelPermalink
+description: Returns the relative permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+  functions_and_methods:
+    returnType: string
+    signatures: [OUTPUTFORMAT.RelPermalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+  {{ .RelPermalink }} → /index.xml
+{{ end }}
+```
diff --git a/content/en/methods/output-format/_index.md b/content/en/methods/output-format/_index.md
@@ -0,0 +1,7 @@
+---
+title: Output format methods
+linkTitle: Output format
+description: Use these methods with an OutputFormat object.
+categories: []
+keywords: []
+---
diff --git a/content/en/methods/page/AlternativeOutputFormats.md b/content/en/methods/page/AlternativeOutputFormats.md
@@ -13,30 +13,17 @@ params:
 
 The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See&nbsp;[details](/configuration/output-formats/).
 
-## 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:
+For example, to generate a `link` element for each of the alternative output formats:
 
 ```go-html-template
-<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>
+{{ range .AlternativeOutputFormats }}
+  {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
+{{ end }}
 ```
 
-On the site's home page, Hugo renders this to:
+Hugo renders this to something like:
 
 ```html
-<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets, Inc.">
+<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">
 ```
diff --git a/content/en/methods/page/OutputFormats.md b/content/en/methods/page/OutputFormats.md
@@ -15,24 +15,59 @@ The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat`
 
 ## Methods
 
-{{% include "/_common/methods/page/output-format-methods.md" %}}
+### Canonical
 
-## Example
+{{< new-in "0.154.4" />}}
 
-To link to the RSS feed for the current page:
+(`page.OutputFormat`) Returns the [canonical output format](g) for the current page, if defined. Once you have captured the object, use any of its [associated methods][].
 
 ```go-html-template
-{{ with .OutputFormats.Get "rss" }}
-  <a href="{{ .RelPermalink }}">RSS Feed</a>
+{{ 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 }}
 ```
 
-On the site's home page, Hugo renders this to:
+To render an anchor element pointing to the `rss` output format for the current page:
 
-```html
-<a href="/index.xml">RSS Feed</a>
+```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
diff --git a/content/en/methods/page/Sites.md b/content/en/methods/page/Sites.md
@@ -51,7 +51,7 @@ Produces a list of links to each home page:
 </ul>
 ```
 
-To render a link to the home page of the site corresponding to the default content language:
+To render a link to the home page of the [default site](g):
 
 ```go-html-template
 {{ with .Sites.Default }}
diff --git a/content/en/methods/site/Dimension.md b/content/en/methods/site/Dimension.md
diff --git a/content/en/methods/site/Sites.md b/content/en/methods/site/Sites.md
diff --git a/content/en/quick-reference/glossary/canonical-output-format.md b/content/en/quick-reference/glossary/canonical-output-format.md
diff --git a/content/en/quick-reference/glossary/default-site.md b/content/en/quick-reference/glossary/default-site.md
diff --git a/content/en/quick-reference/glossary/dimension.md b/content/en/quick-reference/glossary/dimension.md
diff --git a/content/en/quick-reference/glossary/site.md b/content/en/quick-reference/glossary/site.md
diff --git a/content/en/quick-reference/glossary/sites-matrix.md b/content/en/quick-reference/glossary/sites-matrix.md
