• Page.Rotate({language,version,role})
• Site.Dimension{language,version,role})
• {language,version,role}.IsDefault, {language,version,role}.Name (same as the key in config)

New concepts

• 3D build matrix: Languages, versions, roles.
• Sites matrix (see below)
• Sites fallbacks (see below)
• Technically, a Site is identified by a site vector, e.g. {0,0,0} which is the single identifier for common, simple sites.

Custom identifier in content filenames

• Wrap the idenfifier in underscores, e.g. mypost._scandinavian_.md, see Add custom identifier prefix in content filenames #14001

Sites matrix and fallbacks

Sites matrix and fallbacks can be configured on

• File mounts (currently only relevant for content and layouts mounts).
• Content front matter
• Site and content cascade configuration.
• As sites.matrix is both a cascade field value and a target filter, we apply the cascades like this: 1. Apply the cascade items without any sites.matrix filter, 2. Build the sites.matrix, 3. Apply cascade items with a sites.matrix filter and finally rebuild the sites.matrix if the cascade changed it.
• For content, the sites.matrix configuration will create new URLs for all matching {languages,versions,roles}. This applies to both pages and bundled resources.
• For content, the sites.fallbacks configuration will borrow references (will not create new URLs) from the matching {languages,versions,roles} to fill in any gaps. To select the fallback we prefer closer matches, and matches above in each dimension's sorted will win on ties. This means that if you have the Scandinavian languages defined in order no,sv,da and configure that some piece of content should act as a fallback for da, then any sv match will win because it's closer.
• For layouts, sites.matrix configuration will be used to determine which template to use to render a piece of content.
• For layouts, sites.fallbacks configuration is currently not relevant.
• sites.matrix and sites.fallbacks defined in front matter have higher precedence than file mount definitions, but note that we will skip file mounts that have a sites.matrix with one or more Glob patterns that do not match any active {languages,versions,roles}.
• sites.matrix is also available as a new filter in segments.

sites:
   matrix:
      languages: ["**"]
      versions: ["**"]
      roles: ["**"]
   fallbacks:
      languages: ["**"]
      versions: ["**"]
      roles: ["**"]

The Glob expressions above uses "." as separator.

Note that this also applies to page metadata set in content adapters.

Sort orders:

• languages: By weight if set, then by name.
• versions: By weight if set, then semver descending.
• roles: By weight if set, then by name.

Content Adapters

Before Hugo v0.152.0 the site matrix had only one dimension, language, and we executed a given _content.gotmpl file with the Site that represented the file's language (configured either in the file name, the mount config or fall back to defaultContentLanguage). You could then invoke .EnableAllLanguages in _content.gotmpl to execute the same template for all Sites/languages.

In v0.152.0 we have 3 dimensions (language, version, role) and a Site is represented by a vector of these 3, e.g. ('en', 'v2.1.0', 'guest'). And since a _content.gotmpl can be configured for e.g. many languages, we, by default, only execute the _content.gotmpl once with the first matching Site. You can override this behaviour by invoking .EnableAllDimensions. But note that you don't need to do that if the goal is just to e.g. create content across languages, since it's now possible to set sites.{languages,versions,roles} as Glob patterns in both the file mount config or in page metadata/front matter.

Glob negation prefix

Many Glob filters in Hugo's configuration now supports the negation prefix "! " (an exlamation mark followed by a single space). This means that the entire Glob expression gets negated. This is supported in:

• All sites.matrix and sites.fallbacks configuration described above, e.g. languages: ["! {sv,no,nn,da}", "**"] which means match all languages except the Scandinavian languages (note that the order of the Glob patterns matters).
• In file mount file filtering, e.g. files: ["! **.{html,txt}", "**"], which means include all files except files with html or txt extension.
• segment filtering.

Notes

• Before Hugo v0.152.0 we rendered the project in the order of defaultContentLanguage first and then in the order defined by the language (weight then name). With a bigger build matrix (language, version, role), we decided to simplify this having one sort order. Note that it's very common to have the defaultContentLanguage listed as the first.
• The above also changes the order of .Site.Sites to be the same as .Site.Languages.
• We no longer log about potential duplicate content paths. The problem was already illustrated and addressed in Potentially false duplicate path warning #13993, but becomes impossible to reason about with a more complex sites matrix.
• File mount's includefiles and excludefiles are deprectated and replaced by the more powerful files filter option, supporting the new Glob negation prefix.
• The lang option on (https://gohugo.io/configuration/module/#mounts)[mounts] is deprecated and replaced by the more powerful sites.matrix option.
• The lang option on segments is deprecated and replaced with a more powerfule sites.matrix filter. Also note that all the filters now can take either a string or a string slice of Glob patterns (which now also can be negated, see above) which gets ORed (we use the first match) together,