New API for next Hugo version

[bep]

This document provides an overview of the new features, terms, and API changes in this version.

New and Changed API

• Page.Rotate("language"|"version"|"role"): Returns a list of pages for the given dimension, holding the other two dimensions constant.
• Site.Dimension("language"|"version"|"role"): Returns the current dimension object (Language, Version, or Role).
• {language|version|role}.IsDefault: Returns true if the given dimension object is the default.
• {language|version|role}.Name: Returns the name of the dimension object (e.g., "en", "v2.0.0", "guest"). This is the lower cased key used in the configuration.

New Concepts

• 3D Build Matrix: Content can now be built for a three-dimensional matrix of Languages, Versions, and Roles.
• Sites Matrix: Defines what sites content should be built for.
• Sites Complements: Defines what sites content should complement.
• Site Vector: Internally, each unique Site is identified by a vector (e.g., {0,0,0}), which represents a specific combination of language, version, and role.

Sites Matrix and Complements

The sites.matrix and sites.complements can be configured in:

• File mounts (currently relevant for content and layouts mounts).

• Content front matter.

• Site and content cascade configuration.

• For content:

  • sites.matrix builds the content to every combination of matching languages, versions and roles.
  • sites.complements complements, fills in any gaps of missing content, in sites matching the configured languages, versions and roles. This will not create new URLs.
  • When selecting a complement candidate, Hugo prefers closer matches. For equally close matches, it prioritizes the one that appears first in the sorted dimension configuration. For example, if languages are ordered no, sv, da, and content is configured to complement da, a sv match will be chosen over a no match because it is "closer" in the list.

• For layouts:

  • sites.matrix determines which template is used to render a piece of content.
  • sites.complements is not currently relevant for layouts.

Precedence and Filtering:

• Configuration in front matter has higher precedence than in file mounts.
• File mounts with a sites.matrix containing Glob patterns that don't match any active sites will be skipped.
• sites.matrix can also be used as a filter in segments (https://gohugo.io/configuration/segments/#segment-definition).
• When using cascade, the sites.matrix is applied in steps: first, cascades without a sites.matrix filter are applied; second, the
  sites.matrix is built; finally, cascades with a sites.matrix filter are applied, and the matrix is rebuilt if it changed.

Sites Matrix and Filenames

• For content and layout files, it's still possible to add one language identifier to the filename, e.g. /content/mypost.en.md or /layouts/home.en.html
• You can now also create custom, shared identifiers for content files by wrapping the identifier in underscores. For example,
  mypost._scandinavian_.md can be used to associate that file with a custom sites.matrix definition (see issue Add custom identifier prefix in content filenames #14001).

Content Adapters

Before this version, a _content.gotmpl file was executed once for the Site that matched its language. You could invoke .EnableAllLanguages to execute the template for all sites.

Now, with a 3D matrix, a _content.gotmpl file is, by default, executed only once for the first matching Site. You can use
.EnableAllDimensions to run it for all sites. However, the recommended approach is to use the sites.matrix configuration (in the mount or front matter) to control which sites the content is generated for.

Glob Negation Prefix

Many Glob filters in Hugo now support the negation prefix "! " (an exclamation mark followed by a single space) to exclude
patterns. This is supported in:

• sites.matrix and sites.complements:
  • languages: ["! {sv,no,nn,da}", "**"] (matches all languages except Scandinavian ones).
• File mount filtering:
  • files: ["! .{html,txt}", ""] (includes all files except those with .html or .txt extensions).
• Segment filtering.

Notes

• Build Order: Hugo builds sites based on the sorted dimensions (see below). In earlier versions, we built the sites starting with the default content language. This change is also reflected in the sort order of .Site.Sites to make it consistent with .Site.Languages.
• Sort Order: The dimensions are sorted as follows, which affects build order and complement selection:
  • languages: By weight, then by name.
  • versions: By weight, then by semantic versioning (descending).
  • roles: By weight, then by name.
• Deprecations:
  • The lang option on mounts (https://gohugo.io/configuration/module/#mounts) and segments
    (https://gohugo.io/configuration/segments/#segment-definition) is deprecated in favor of the more powerful sites.matrix
    option.
  • File mount includeFiles and excludeFiles` are deprecated in favor of the new files filter, which supports negation.
• Logging: We no longer log warnings about potential duplicate content paths, as this becomes impractical to reason about with a
  complex sites matrix.