Multidimensional content model
Overview
A project often needs the same content in several forms. It may publish each page in more than one language, keep the documentation for older releases online, and show some pages only to members. Hugo’s multidimensional content model handles all three cases with one set of concepts, so that you can publish many sites from a single project without copying files.
A dimension is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, version, and role. Each combination of one language, one version, and one role is a site. For example, a logical page may exist in 6 languages, 4 versions, and 2 roles.
| Dimension | Purpose | Configuration | Default value |
|---|---|---|---|
| Language | Localization | languages | en |
| Version | Release or lifecycle stage | versions | v1.0.0 |
| Role | Audience | roles | guest |
Every project has all three dimensions. If you do not define any values for a dimension, the dimension has one value, shown in the table above. For example, a project that defines no languages, versions, or roles generates one site: English, version v1.0.0, role guest.
Sites
Hugo generates one site for each combination of language, version, and role. For example, this configuration defines two languages and two versions, and generates four sites:
defaultContentLanguage: en
defaultContentLanguageInSubdir: true
defaultContentVersion: v2.0.0
defaultContentVersionInSubdir: true
languages:
de:
weight: 2
en:
weight: 1
versions:
v1.0.0: {}
v2.0.0: {}
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
defaultContentVersion = 'v2.0.0'
defaultContentVersionInSubdir = true
[languages]
[languages.de]
weight = 2
[languages.en]
weight = 1
[versions]
[versions.'v1.0.0']
[versions.'v2.0.0']
{
"defaultContentLanguage": "en",
"defaultContentLanguageInSubdir": true,
"defaultContentVersion": "v2.0.0",
"defaultContentVersionInSubdir": true,
"languages": {
"de": {
"weight": 2
},
"en": {
"weight": 1
}
},
"versions": {
"v1.0.0": {},
"v2.0.0": {}
}
}
Each site has its own root within the public directory:
public/
├── v1.0.0/
│ ├── de/
│ └── en/
├── v2.0.0/
│ ├── de/
│ └── en/
└── index.html <-- redirects to the default siteThe site root begins with the role, followed by the version and the language, such as /guest/v2.0.0/en/. Hugo omits the prefix for the default value of a dimension unless you set the corresponding defaultContent*InSubdir setting to true. In a multihost project, each language has its own host, so the language comes first, such as /en/guest/v2.0.0/.
The default site is the site with the default language, default version, and default role. Set the default value of each dimension with the defaultContentLanguage, defaultContentVersion, and defaultContentRole settings. When the default site is published to a subdirectory, Hugo creates a redirect from the root of the public directory to the default site.
Hugo sorts the sites by dimension, and builds them in that order:
The returned collection follows a hierarchical sort where each subsequent dimension acts as a tie-breaker for the one above it.
- Language is sorted by weight in ascending order, falling back to lexicographical order if weights are tied or undefined.
- Version is then sorted by weight in ascending order, with Hugo defaulting to a descending semantic sort for any ties.
- Role is finally sorted by weight in ascending order, using lexicographical order as the final fallback.
Assign content to sites
By default, Hugo publishes each content file to the site with the default value of each dimension. In the example above, a content file with no other configuration is published to the English v2.0.0 site only.
You can assign a content file to other sites in these ways:
- File name identifier
- Include a language, version, or role identifier in the file name, such as
about.de.mdorabout._version_v1.0.0_.md. See file names. - Front matter
- Set the
sitesfield in front matter. - Cascade
- Set the
sitesfield within acascadein front matter or in your project configuration. Use the cascadetargetto apply the value to a subset of pages. - Mount
- Set the
sitessetting on acontentmount. Every file within the mount inherits the value.
Each of these sets the value of one or more dimensions. When more than one sets the value of the same dimension, Hugo uses the first one in this list:
- Front matter
- Cascade
- File name identifier
- Mount
- The default value
Hugo resolves each dimension separately. For example, a file can take its language from its mount, its role from a cascade, and its version from its own front matter.
This front matter publishes a page to every language in two versions:
---
sites:
matrix:
languages: '**'
versions:
- v1.0.0
- v2.0.0
title: About
---+++
title = 'About'
[sites]
[sites.matrix]
languages = '**'
versions = ['v1.0.0', 'v2.0.0']
+++{
"sites": {
"matrix": {
"languages": "**",
"versions": [
"v1.0.0",
"v2.0.0"
]
}
},
"title": "About"
}
The sites field contains up to two maps, matrix and complements, described in sites matrix and sites complements. Each map accepts the languages, versions, and roles keys, and the value of each key is a dimension matcher.
The sites field selects from the languages, versions, and roles defined in your project configuration. It does not define new values.
Dimension matchers
A dimension matcher is a string, or a slice of strings, that selects one or more values of a dimension using glob patterns, negated glob patterns, and comparison operators. Each key of a sites matrix or sites complements is a dimension matcher.
A dimension matcher can contain glob patterns, negated glob patterns, and comparisons.
Glob patterns
A glob pattern matches the language key, version name, or role name. When matching version names, the delimiter is a dot (.). For example, v1.*.* matches v1.2.3, and v1.** matches v1.2.3 and v1.2. Use ** to match every value.
A value matches when it matches any of the glob patterns. For example, ['v1.*.*', 'v3.*.*'] matches every v1 and v3 release.
Negation
Begin a glob pattern with an exclamation mark (!) followed by a space to exclude the values that match the pattern. For example, ['v2.*.*', '! v2.1.*'] matches every v2 release except the v2.1 releases.
A dimension matcher that contains only negated patterns matches every value that is not excluded. For example, '! v1.*.*' matches every version except the v1 releases.
Comparisons
New in v0.155.0Begin an entry with a comparison operator and a space to compare each value to the given value.
| Operator | Matches values that are |
|---|---|
== | equal to the given value |
!= | not equal to the given value |
> | after the given value |
>= | equal to or after the given value |
< | before the given value |
<= | equal to or before the given value |
Comparisons follow the sort order of the dimension, not alphabetical order. For versions, “after” means newer, so >= v2.0.0 matches v2.0.0 and every newer version. If you change the order by setting the weight of a version, comparisons follow the new order.
Combine comparisons to select a range. For example, this front matter publishes a page to every version from v2.0.0 through v2.1.0:
---
sites:
matrix:
versions:
- '>= v2.0.0'
- <= v2.1.0
title: Example
---+++
title = 'Example'
[sites]
[sites.matrix]
versions = ['>= v2.0.0', '<= v2.1.0']
+++{
"sites": {
"matrix": {
"versions": [
"\u003e= v2.0.0",
"\u003c= v2.1.0"
]
}
},
"title": "Example"
}
To find the given value, Hugo looks for a defined value with the same name. For versions, Hugo then looks for a defined version with the same version number. For example, >= v2.0.0 works if you have defined a version named v2. Glob patterns match the version name as written, so v2.*.* does not match a version named v2.
You can use comparisons with any dimension, but they are most useful with versions, which have a natural order.
Evaluation
A value matches the dimension matcher if both of these are true:
- It matches at least one of the glob patterns, or the dimension matcher has no glob patterns.
- It satisfies every negated pattern and comparison.
List the glob patterns first, followed by the negated patterns and comparisons. Hugo ignores a glob pattern that comes after a negated pattern or comparison.
The order of the entries changes the result. For example, ['v2.*.*', '! v2.1.*'] matches every v2 release except the v2.1 releases, but ['! v2.1.*', 'v2.*.*'] matches every version except the v2.1 releases.
If a dimension matcher matches no values, Hugo ignores it. In front matter or a cascade, Hugo uses the next source in the precedence list instead. On a mount, Hugo skips the mount. Hugo does not report an error in either case. For example, < v3.0.0 matches no values if you have not defined a version named v3.0.0, v3.0, or v3.
Do not confuse a dimension matcher with the version setting of a module import, which takes a Go module version query. The version setting selects which release of a module to download. The versions key within sites selects which sites to publish content to.
Sites matrix and sites complements
The sites field contains two maps: matrix and complements. Both use dimension matchers to select sites, but they do different things.
| Sites matrix | Sites complements | |
|---|---|---|
| Effect | Publishes the content to each selected site | Adds the content to the page collections of each selected site |
| Pages created | One for each selected site | None |
| Page URL | Within the root of each selected site | Within the root of the page’s own site |
A sites matrix is a map that selects sites by language, version, and role, where the value of each key is a dimension matcher. In front matter, a cascade, or a content mount, it selects the sites to publish the content to, creating a separate page for each site. In a layouts mount, it selects the sites that use the templates. In a segment or page matcher, it selects the sites to match.
See also: sites complements.
A sites complements is a map that selects sites by language, version, and role, where the value of each key is a dimension matcher. Defined in front matter, a cascade, or a content mount, it adds the content to the page collections of the selected sites without creating new pages. Each page keeps the URL of its own site.
See also: sites matrix.
For example, use a sites complements to promote members-only content on a public site. In this configuration, the guest site lists the members-only articles, but each link leads to the member site, where you can require authentication outside of Hugo.
defaultContentRole: guest
defaultContentRoleInSubdir: true
module:
mounts:
- sites:
matrix:
roles: guest
source: content/guest
target: content
- sites:
complements:
roles: guest
matrix:
roles: member
source: content/member
target: content
roles:
guest:
weight: 1
member:
weight: 2
defaultContentRole = 'guest'
defaultContentRoleInSubdir = true
[module]
[[module.mounts]]
source = 'content/guest'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
roles = 'guest'
[[module.mounts]]
source = 'content/member'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.complements]
roles = 'guest'
[module.mounts.sites.matrix]
roles = 'member'
[roles]
[roles.guest]
weight = 1
[roles.member]
weight = 2
{
"defaultContentRole": "guest",
"defaultContentRoleInSubdir": true,
"module": {
"mounts": [
{
"sites": {
"matrix": {
"roles": "guest"
}
},
"source": "content/guest",
"target": "content"
},
{
"sites": {
"complements": {
"roles": "guest"
},
"matrix": {
"roles": "member"
}
},
"source": "content/member",
"target": "content"
}
]
},
"roles": {
"guest": {
"weight": 1
},
"member": {
"weight": 2
}
}
}
Consider this content structure:
content/
├── guest/
│ ├── articles/
│ │ ├── _index.md <-- sites.matrix.roles = '**'
│ │ └── free.md
│ └── _index.md <-- sites.matrix.roles = '**'
└── member/
└── articles/
└── premium.mdThe home page and the articles section page set sites.matrix.roles to ** in front matter, so that both exist in each site. In each site, the RegularPages method on the articles section page returns these pages:
| Site | Page title | Page URL |
|---|---|---|
| guest | Free article | /guest/articles/free/ |
| guest | Premium article | /member/articles/premium/ |
| member | Premium article | /member/articles/premium/ |
The premium article appears in the page collections of the guest site, but Hugo publishes it to the member site only. To identify complemented pages in a template, compare the role of the page’s site with the role of the current site:
{{ range .RegularPages }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ if ne .Site.Role.Name site.Role.Name }}(members only){{ end }}
{{ end }}Fill in missing content
When a page does not exist for a site, you can fill the gap with the same page from another site. The usual approach is the same for versions and languages: mount the content to more sites than the one it was written for. When two or more mounts provide a page with the same logical path to the same site, Hugo uses the page from the first mount, so list the most specific mount first.
The cases differ in what visitors see. A later version receives the correct content, because the page did not change. A language receives a stand-in, because the text is in another language.
Versions
Most pages do not change from one version to the next. Instead of copying every page into each version, store the new and changed pages for each version in a separate directory, and mount the directories so that each version uses the newest copy of each page.
defaultContentVersion: v3
defaultContentVersionInSubdir: true
module:
mounts:
- sites:
matrix:
versions: '>= v3'
source: content/v3
target: content
- sites:
matrix:
versions: '>= v2'
source: content/v2
target: content
- sites:
matrix:
versions: '>= v1'
source: content/v1
target: content
versions:
v1: {}
v2: {}
v3: {}
defaultContentVersion = 'v3'
defaultContentVersionInSubdir = true
[module]
[[module.mounts]]
source = 'content/v3'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
versions = '>= v3'
[[module.mounts]]
source = 'content/v2'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
versions = '>= v2'
[[module.mounts]]
source = 'content/v1'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
versions = '>= v1'
[versions]
[versions.v1]
[versions.v2]
[versions.v3]
{
"defaultContentVersion": "v3",
"defaultContentVersionInSubdir": true,
"module": {
"mounts": [
{
"sites": {
"matrix": {
"versions": "\u003e= v3"
}
},
"source": "content/v3",
"target": "content"
},
{
"sites": {
"matrix": {
"versions": "\u003e= v2"
}
},
"source": "content/v2",
"target": "content"
},
{
"sites": {
"matrix": {
"versions": "\u003e= v1"
}
},
"source": "content/v1",
"target": "content"
}
]
},
"versions": {
"v1": {},
"v2": {},
"v3": {}
}
}
List the mounts from the newest version to the oldest. Consider this content structure:
content/
├── v1/
│ └── docs/
│ ├── _index.md
│ ├── configure.md
│ ├── install.md
│ └── legacy.md <-- sites.matrix.versions = '< v3'
├── v2/
│ └── docs/
│ ├── configure.md
│ └── deploy.md
└── v3/
└── docs/
└── install.mdThis table shows the source of each page in each version:
| Page | v1 | v2 | v3 |
|---|---|---|---|
/docs/configure | content/v1 | content/v2 | content/v2 |
/docs/deploy | content/v2 | content/v2 | |
/docs/install | content/v1 | content/v1 | content/v3 |
/docs/legacy | content/v1 | content/v1 |
To remove a page from later versions, set sites.matrix.versions in the front matter of the original file, as shown for legacy.md. Front matter takes precedence over the mount.
Do not remove a page by adding a file with the same path to a later version’s directory. For example, if you add a content/v3/docs/legacy.md file that sets sites.matrix.versions to < v3, its mount comes first, so Hugo uses it for v1 and v2 as well, replacing the original page with an empty one.
If you tag each release in a Git repository, you can import the repository as a module once for each release, and set sites.matrix.versions on the mount of each import. This replaces the separate directory for each version.
Translations
The approach depends on how you organize your translations. If you plan to fill in missing translations, translate by directory.
With either approach, Hugo identifies each page by its logical path, and the translations of a page are the files that share that path. Give each translation the same path, such as content/de/posts/my-post.md and content/en/posts/my-post.md, or content/posts/my-post.de.md and content/posts/my-post.en.md.
If two translations of a page have different logical paths, Hugo treats them as two different pages, and each one fills the gap left by the other, even if they share the same translationKey. For example, the German site then contains both the German page and the English page.
To translate the URL of a page, set the slug in front matter instead of changing the file name.
When you set the slug on a section, taxonomy, or term page, Hugo also applies it to the URLs of the pages beneath it. For example, this front matter changes the URL of the German products section and every page beneath it:
---
slug: produkte
title: Produkte
---+++
slug = 'produkte'
title = 'Produkte'
+++{
"slug": "produkte",
"title": "Produkte"
}
The resulting URLs are:
content/de/products/_index.md → /de/produkte/
content/de/products/tv.md → /de/produkte/tv/
content/en/products/_index.md → /en/products/
content/en/products/tv.md → /en/products/tv/If you translate by directory, mount the directory for the default language to every language, after the mounts for the other languages:
module:
mounts:
- sites:
matrix:
languages: de
source: content/de
target: content
- sites:
matrix:
languages: '**'
source: content/en
target: content
[module]
[[module.mounts]]
source = 'content/de'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
languages = 'de'
[[module.mounts]]
source = 'content/en'
target = 'content'
[module.mounts.sites]
[module.mounts.sites.matrix]
languages = '**'
{
"module": {
"mounts": [
{
"sites": {
"matrix": {
"languages": "de"
}
},
"source": "content/de",
"target": "content"
},
{
"sites": {
"matrix": {
"languages": "**"
}
},
"source": "content/en",
"target": "content"
}
]
}
}
When both directories contain the same file, the German site uses the file from content/de because its mount comes first. When only content/en contains the file, Hugo publishes the file to the German site as a German page. Visitors never leave the German site, but the Language method on that page returns German even though the text is English.
If you translate by file name, use a cascade to apply a sites complements to the English pages:
cascade:
- sites:
complements:
languages: de
target:
sites:
matrix:
languages: en
[[cascade]]
[cascade.sites]
[cascade.sites.complements]
languages = 'de'
[cascade.target]
[cascade.target.sites]
[cascade.target.sites.matrix]
languages = 'en'
{
"cascade": [
{
"sites": {
"complements": {
"languages": "de"
}
},
"target": {
"sites": {
"matrix": {
"languages": "en"
}
}
}
}
]
}
This does not create German pages. Instead, the page collections of the German site include each English page that has no German translation, and the links to those pages lead to the English site. The result is the same as calling the lang.Merge function on every page collection.
With this approach, visitors may leave the German site when they follow a link. A language selector built with the Rotate method lists only the languages in which a page exists, so the selector on an English page with no German translation does not list German.
Page resources
Hugo assigns each page resource to sites from its file name and its mount. A page resource does not inherit the sites field from the front matter of its page.
Include an identifier in the file name of a page resource to assign it to a language, version, or role, such as diagram.de.png or diagram._version_v1_.png. When a page has no resource with a given name for its language, Hugo uses the resource with the same name from another language. Hugo never uses a resource from another version or role.
Templates
Use these methods and functions to get information about sites and dimensions:
site.Language,site.Version, andsite.Role- Return the language, version, and role of the current site. The
site.Dimensionmethod returns the same objects, given the name of a dimension. hugo.Sites- Returns every site, sorted by dimension. Use the
Defaultmethod on the result to get the default site. site.IsDefault- Reports whether the current site is the default site. Use it to run code once per build instead of once per site.
Rotate- Returns the variants of the current page along the given dimension, keeping the other two dimensions constant.
For example, use the Rotate method to render a version selector. The selector lists only the versions that include the current page.
<ul>
{{ range .Rotate "version" }}
<li><a href="{{ .RelPermalink }}">{{ .Site.Version.Name }}</a></li>
{{ end }}
</ul>To use a different template for a specific language, version, or role, include an identifier in the template’s file name, such as page._version_v1_.html. You can also set sites.matrix on a layouts mount to limit the templates in the mount to specific sites.
Related features
These features also use the multidimensional content model:
- Aliases
- Hugo resolves each alias relative to the root of the page’s site.
- Cascade
- The cascade
targetaccepts asites.matrixto limit cascaded values to specific sites. - Content adapters
- By default, Hugo executes a content adapter once, for the first site that it matches. Use the
EnableAllLanguagesorEnableAllDimensionsmethod, or set thesiteskey when adding each page, to create pages for other sites. - Segments
- A segment filter accepts a
sites.matrixto include or exclude specific sites.
