Breaking change
Prior to v0.155.0, alias paths beginning with a slash (/) were treated as server-relative. In v0.155.0 and later, they are now site-relative. This change only affects multilingual single-host projects that used alias paths beginning with a slash (/) to cross language boundaries.
For example, if you have a file content/foo.en.md with the following front matter:
aliases:
- /de/foo-in-german/
In v0.155.0 and later, this will resolve to /en/de/foo-in-german/ instead of /de/foo-in-german/.
The reason for the change
The short version is that the previous implementation was broken in several ways. It was also difficult to reason about in relation to the multidimensional content model introduced in v0.153.0. In this model, a site is no longer defined just by language, but by role and version as well.
To resolve this, we have changed how Hugo interprets alias paths. There are three types of relative URL paths in the context of a Hugo project:
| Type | Example | Description |
|---|---|---|
| page-relative | foo, ./foo, ../foo |
Relative to the current page |
| site-relative | /foo |
Relative to the current site root (role, version, language) |
| server-relative | /guest/v1.2.3/de/foo |
Relative to the web server host root |
Prior to v0.155.0, alias paths beginning with a slash (/) were treated as server-relative. In v0.155.0 and later, they are now site-relative. This change ensures that aliases for all output formats work correctly across different roles, versions, and languages.
Handling missing translations
If you were previously using aliases as a workaround to handle missing translations, there is a much better way to do this now using a sites matrix.
For example, to set the English version of a page to provide the content for all other missing language translations, add this to your front matter:
title: p1
sites:
matrix:
languages: ['**']
You can also define a sites matrix in your site configuration or cascade it down to descendant pages.
Updated documentation
We have overhauled the documentation to help you navigate these changes:
- Front matter: Aliases (minor updates)
- URL management: Aliases (complete rewrite)
- Page methods: Aliases (complete rewrite)