Aliases

The Aliases method on a Page object returns the values defined in the aliases front matter field as server-relative URLs, resolved according to the current content dimension.

The Aliases method is useful for generating a _redirects file, which contains a source URL, a target URL, and an HTTP status code for each alias. You can use a _redirects file with hosting services such as Cloudflare, GitLab Pages, and Netlify.

Redirects

By default, Hugo handles aliases by creating individual HTML files for each alias path. These files contain a meta http-equiv="refresh" tag to redirect the visitor via the browser.

While functional, generating a single _redirects file allows your hosting provider to handle redirects at the server level. This is more efficient than client-side redirection and improves performance by eliminating the need to load a middle-man HTML page.

Example

The following example demonstrates how to configure your site and create a template to automate the generation of a _redirects file.

Content structure

The content structure for this multilingual example looks like this:

content/
├── examples/
│   ├── a.de.md   aliases = ['a-old']
│   ├── a.en.md   aliases = ['a-old', 'a-older']
│   ├── b.de.md   aliases = ['b-old']
│   └── b.en.md   aliases = ['b-old', 'b-older']
└── _index.md

In the example above, the aliases are page-relative. To specify a site-relative path, preface the entry with a slash (/). Both forms are resolved to server-relative paths.

Page-relative paths can also include directory traversal:

Project configuration

To implement this, you must update your site configuration to:

1. Disable the generation of default HTML redirect files by setting disableAliases to true.
2. Define a media type named text/redirects to handle the file format.
3. Define a custom output format named redirects to set the filename to _redirects and place it at the root of the published site.
4. Configure the home page outputs to include the redirects format in addition to html.

baseURL: https://example.org/
defaultContentLanguage: en
defaultContentLanguageInSubdir: true
disableAliases: true
languages:
  de:
    languageCode: de-DE
    languageDirection: ltr
    languageName: Deutsch
    title: My Site in German
    weight: 2
  en:
    languageCode: en-US
    languageDirection: ltr
    languageName: English
    title: My Site in English
    weight: 1
mediaTypes:
  text/redirects:
    delimiter: ''
outputFormats:
  redirects:
    baseName: _redirects
    isPlainText: true
    mediaType: text/redirects
    root: true
outputs:
  home:
  - html
  - redirects

baseURL = 'https://example.org/'
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
disableAliases = true
[languages]
  [languages.de]
    languageCode = 'de-DE'
    languageDirection = 'ltr'
    languageName = 'Deutsch'
    title = 'My Site in German'
    weight = 2
  [languages.en]
    languageCode = 'en-US'
    languageDirection = 'ltr'
    languageName = 'English'
    title = 'My Site in English'
    weight = 1
[mediaTypes]
  [mediaTypes.'text/redirects']
    delimiter = ''
[outputFormats]
  [outputFormats.redirects]
    baseName = '_redirects'
    isPlainText = true
    mediaType = 'text/redirects'
    root = true
[outputs]
  home = ['html', 'redirects']

{
   "baseURL": "https://example.org/",
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": true,
   "disableAliases": true,
   "languages": {
      "de": {
         "languageCode": "de-DE",
         "languageDirection": "ltr",
         "languageName": "Deutsch",
         "title": "My Site in German",
         "weight": 2
      },
      "en": {
         "languageCode": "en-US",
         "languageDirection": "ltr",
         "languageName": "English",
         "title": "My Site in English",
         "weight": 1
      }
   },
   "mediaTypes": {
      "text/redirects": {
         "delimiter": ""
      }
   },
   "outputFormats": {
      "redirects": {
         "baseName": "_redirects",
         "isPlainText": true,
         "mediaType": "text/redirects",
         "root": true
      }
   },
   "outputs": {
      "home": [
         "html",
         "redirects"
      ]
   }
}

Template implementation

Next, create a home page template specifically for the redirects output format. The following template iterates through every page in every language and extracts its aliases.

To ensure the resulting _redirects file is valid, the template uses the strings.FindRE function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file.

{{- if site.IsDefault -}}
  {{- range hugo.Sites -}}
    {{- range $p := .Pages -}}
      {{- range .Aliases -}}
        {{- if findRE `\s` . -}}
          {{- errorf "One of the front matter aliases in %q contains whitespace" $p.String -}}
        {{- end -}}
        {{- printf "%s %s 301\n" . $p.RelPermalink -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

Generated output

Once Hugo processes the template, it produces a clean list of redirect rules. Each line follows the required format: the source URL, the destination URL, and the HTTP status code.

The resulting _redirects file looks like this:

/de/examples/a-old /de/examples/a/ 301
/de/examples/b-old /de/examples/b/ 301
/en/examples/b-old /en/examples/b/ 301
/en/examples/b-older /en/examples/b/ 301
/en/examples/a-old /en/examples/a/ 301
/en/examples/a-older /en/examples/a/ 301