Add roles and versions as new dimensions (in addition to language)

[bep]

See #13776.

[willfaught]

@bep Just curious, can you give an example of when you'd use roles or versions? It isn't clear to me from your example.

[bep]

@willfaught this is a draft ... but

• versions' main use case is to publish multiple versions of some content (typically documentation)
• roles' main use case is for membership content ("subscribe to get premium content") -- this would need some boilerplate on top, but doing that top down (restricting some URL paths) is certainly simpler and cheaper than the bottom-up approach where "content is served from server if user is member).

[willfaught]

@bep Why would you publish the same text under multiple versions? To save you from duplicating the text if the text didn't change between versions?

How would roles work for privileged content/pages in a static site that's just serving files from a directory?

[bep]

Why would you publish the same text under multiple versions?

You don't have to do that. I have written a fair amount about how this is intended to work, which will improve and make the language support behave the same. That is, you can e.g. define that a piece of content should either be rendered/duplicated to a set of languages or act as a fallback for a set of languages.

As to roles, you would obviously need authentication and authorisation outside of Hugo, but the authorisation part will be simple/directory based.

[repsejnworb]

This looks promising for solving my usecase where I've made my own implementation for versioning arbitrary sections/paths.

If 'version' could be assigned to content via directories, and "populate" the parent dir based on selected version, this would nearly solve my usecase.

I.e:

/content/products/foo/
      ---> shared.md
      ---> /foo@v1.0/
           ---> versionSpecific.md
      ---> /foo@v1.2/
           ---> versionSpecific.md
           ---> versionSpecificNew.md
      

If the above would let me have /products/foo populated always with shared.md, and depending on version selected be populated with the files under the specific versions path, then I would be 90% there.

The only missing thing then would be the front matter of _index.md, which in my custom setup I sadly have to handle with outside tooling and search'n'replace (tried using mounts and copy in a shared/_index.md mixed with cascading params with targets, but due to a bug with this approach and the param shortcode it failed).

If, in the above example, front matter was merged - letting the versions _index.md take precedence, this would solve my usecase 100%
(Under the assumption that versions are just a string, as I'd need them per product, so f.x config would have versions: [foo-v1.0, foo-v1.2, bar-v1.0])

(Would be even doper if you could have different versions-arrays target different paths. All this combined with the new version-query support would allow very nice setups)

[bep]

(Would be even doper if you could have different versions-arrays target different paths. All this combined with the new version-query support would allow very nice setups)

@repsejnworb I'm not sure I understand your setup, but with this PR you can set versions via paths via front matter (directly or via cascade (either in config or in a branch node's front matter)), see #13776 for slightly more info. This was the main reason why taking this PR the last 10% became a little bit of a struggle.

[Copilot]

Pull Request Overview

This PR adds roles and versions as new dimensions to Hugo's build matrix, expanding beyond the existing language dimension. This enables building sites with multiple versions (e.g., v1.0.0, v2.0.0) and roles (e.g., guest, member), allowing content to be selectively rendered based on these dimensions.

Key Changes:

• Introduces a 3-dimensional sites matrix structure (language, version, role) replacing the previous language-only model
• Adds new configuration options for versions and roles with associated metadata
• Updates content filtering and rendering logic to support multi-dimensional site builds

Reviewed Changes

Copilot reviewed 136 out of 209 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
hugolib/sitesmatrix/dimensions.go	Defines core types for 3D vector operations and dimension constants
hugolib/sitesmatrix/dimensions_test.go	Test coverage for vector comparison and distance operations
hugolib/roles/roles.go	Implements role configuration and management system
hugolib/segments/segments.go	Updates segment filtering to support multi-dimensional sites
hugolib/site.go	Refactors Site struct to support version and role dimensions
hugolib/page__meta.go	Splits page metadata into source and per-dimension components

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.