Redirect Management
Relevant source files
The following files were used as context for generating this wiki page:Redirect management within the Docker Docs project is a build-time process handled by the Hugo static site generator. It ensures that old, deprecated, or alternative URLs correctly point to the current, canonical content. This system is crucial for maintaining SEO, preventing broken links from external sources, and providing short "vanity" URLs for use within the Docker product itself.
The system consolidates redirect rules from two primary sources—page-specific front matter and a global configuration file—into a single JSON file during the site build. This artifact is then used in the production environment to handle HTTP 301 redirects.
Architecture Overview
The redirect generation process aggregates rules from distributed and centralized sources into a single output file.
The following diagram illustrates the data flow for redirect generation during the Hugo build process.
This diagram shows how Hugo collects aliases from individual Markdown files and pageless redirects from data/redirects.yml, processes them using the index.redirects.json layout, and outputs a final redirects.json file.
Sources: layouts/index.redirects.json, data/redirects.yml, content/contribute/file-conventions.md:16-18
Redirect Mechanisms
There are two primary methods for defining redirects in the repository.
| Method | Source File(s) | Use Case | Implementation |
|---|---|---|---|
Front Matter aliases | content/**/*.md | Redirecting old paths for a page that has been moved or renamed. | A YAML list of paths is added to the aliases key in the page's front matter. |
| Pageless Redirects | data/redirects.yml | Creating "vanity" URLs (e.g., /go/...) or redirecting paths that no longer have a corresponding content page. | A mapping of target URLs to a list of source aliases. |
Sources: content/contribute/file-conventions.md:16-18, data/redirects.yml:1-10
Front Matter Aliases
This is the most common method for handling content that has been moved. By adding an aliases key to a page's front matter, you can specify a list of old URLs that should redirect to the current page. At build time, Hugo creates an HTML stub for each alias that contains a 302 redirect to the new page.
Sources: content/contribute/file-conventions.md:16-18
An example from the contribution guide:
---
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
title: Install Docker Engine on Ubuntu
aliases:
- /ee/docker-ee/ubuntu/
- /engine/installation/linux/docker-ce/ubuntu/
- /engine/installation/linux/docker-ee/ubuntu/
- /engine/installation/linux/ubuntu/
- /engine/installation/linux/ubuntulinux/
- /engine/installation/ubuntulinux/
- /install/linux/docker-ce/ubuntu/
- /install/linux/docker-ee/ubuntu/
- /install/linux/ubuntu/
- /installation/ubuntulinux/
toc_max: 4
---
In this example, all ten paths listed under aliases will redirect to the page with the title "Install Docker Engine on Ubuntu".
Sources: content/contribute/file-conventions.md:43-58
Pageless Redirects (redirects.yml)
The data/redirects.yml file is used for creating redirects that don't correspond to a specific content page. This is particularly useful for:
- Vanity URLs: Short, memorable URLs like
/go/buildx/that can be used in CLI help text or other external communications. - Consolidated Redirects: Redirecting many old API version paths to a single "deprecated" section.
The file structure is a map where the key is the target path and the value is a list of source paths that should redirect to it.
# Use the `/go/` URL prefix to provide "vanity" URLs linking to the
# documentation. These URLs can be used in (for example) the `docker` CLI to
# provide a short, permanent link to refer to a topic in the documentation.
# For example, the docker CLI can output https://docs.docker.com/go/some-topic
# in its help output, which can be redirected to elsewhere in the documentation.
"/security/access-tokens/":
- /go/access-tokens/
"/build/architecture/#install-buildx":
# Instructions on installing Buildx. Redirect used in Docker CLI.
- /go/buildx/
Here, /go/access-tokens/ redirects to /security/access-tokens/, and /go/buildx/ redirects to /build/architecture/#install-buildx.
Sources: data/redirects.yml:1-10, 60-62
Build Process and Output
The generation of the final redirect artifact is managed by Hugo's build system, configured via hugo.yaml and executed by a specific layout template.
hugo.yaml Configuration
The hugo.yaml file defines a custom output format named redirects. This tells Hugo to look for a specific template to generate a file with the base name redirects in application/json format.
# Additional output formats (e.g. custom JSON files)
outputFormats:
# File containing all redirects, see: layouts/index.redirects.json
redirects:
baseName: redirects
isPlainText: true
mediaType: "application/json"
notAlternative: true
# Enable custom output formats
# (only generate the custom output files once)
outputs:
home:
- html
- redirects
- metadata
- robots
- llms
This configuration ensures that when the homepage is built, a redirects.json file is also generated.
Sources: hugo.yaml:45-63
Template Logic (layouts/index.redirects.json)
This Go template is responsible for creating the redirects.json file. It performs two main actions:
- It iterates through all pages (
site.AllPages) and collects any paths defined in thealiasesfront matter. - It iterates through the
site.Data.redirectsmap (loaded fromdata/redirects.yml).
It combines both sources into a single JSON object where each key is a source path and its value is the target path.
{{- /*
This template generates the redirects.json file used to generate 301
redirects in production. It takes all the redirects defined in
data/redirects.yml, as well as all the aliases defined in front matter, and
outputs a simple key-value JSON file:
...
*/
-}}
{{- $redirects := newScratch }}
{{- range $i, $e := site.AllPages -}}
{{- if .Params.aliases -}}
{{- $target := .RelPermalink -}}
{{- range .Params.aliases -}}
{{ $redirects.SetInMap "paths" . $target }}
{{- end -}}
{{- end -}}
{{- end -}}
{{- range $target, $aliases := site.Data.redirects -}}
{{- range $aliases }}
{{- $redirects.SetInMap "paths" . $target -}}
{{- end -}}
{{- end -}}
{{- $opts := dict "noHTMLEscape" true }}
{{- $redirects.Get "paths" | jsonify $opts }}
Sources: layouts/index.redirects.json:1-30
The following sequence diagram visualizes the logic within the template.
This diagram shows the template iterating through pages and data files to populate a scratchpad, which is then converted into the final JSON output.
Sources: layouts/index.redirects.json:16-28
Final Output (redirects.json)
The build process culminates in the creation of a redirects.json file in the root of the public output directory. This file contains a simple key-value mapping of all redirects.
Example structure:
{
"/ee/docker-ee/ubuntu/": "/engine/install/ubuntu/",
"/go/buildx/": "/build/architecture/#install-buildx",
...
}
This file is intended to be consumed by the production hosting environment to configure 301 (permanent) redirects.
Sources: layouts/index.redirects.json:3-14
Contribution and Verification
When contributing to the documentation, it is important to manage redirects correctly. The contribution checklist includes a specific point to verify that any added redirects are working as expected.
Checked that any redirects you may have added, work
For information on how to add redirects, see Source file conventions.
Sources: content/contribute/checklist.md:43-45
Summary
The redirect management system in docker-docs is a powerful, repository-native feature of its Hugo-based architecture. By leveraging front matter aliases for page-specific cases and a central data/redirects.yml for global and vanity URLs, the project maintains a clean and effective way to handle URL changes. The entire system is automated through the build process, producing a single redirects.json artifact that declaratively defines all redirect logic for the production environment.