Internal documentation only

This page has been marked as a draft.

Redirects

There are two ways to create redirects in Hugo, the traditional way described in Create URL redirects, or using Hugo’s Url management. Traditional Apache redirects are more versatile and are required for working with links that point outside a particular project.

Currently, we do not use any Hugo url management features.

Apache redirects Copied

The webserver used to host each project site is Apache. We can create URL redirects by using the Apache RewriteRule module.

To add a new redirect:

1. Test your regex using regexer.
2. Open core-docs/config/project-name\apache-config.conf.
   • Note that redirects are made on a per project basis.
3. Add a new RewriteRule entry. For changes to PROD add this to the first virtualhost, for changes to DEV or local testing add this to the second virtualhost.
4. Save the file.
5. Test your redirects locally, then on devdocs.
6. Publish changes (remember to keep DEV and PROD virtualhosts in sync).

To test redirects locally, run:

PROJECT=proj-name docker-compose -f apache.yml up --build

RewriteRule syntax Copied

The difficult part of creating URL redirects is writing a valid RewriteRule entry. The syntax takes the following form:

RewriteRule pattern substituation [flags]

where the pattern is a regular expression (regex) that describes which input URLs to change, the substitution is the change to make to the URL and the flags provide options for the behaviour of RewriteRule.

You should consult the official documentation for detailed information. Some examples are provided on the Create URL redirects ICE page.

Hugo url management Copied

There are two important url management features, permalinks and aliases.

Permalinks allow you to have different output directories compared to the source file-tree in a project-docs repo. The output directories can include automatically generated variables such as publication dates.

Aliases allow you to add redirects within a project on a per-page basis. However, this also works by reorganising the output directories.

In a new topic you can list which older topic urls should redirect to this location.

aliases:
    - /posts/my-original-url/
    - /2010/01/01/even-earlier-url.html

This makes aliases convenient for simple cases but comes with the downside that redirects are not centralised and can only target single topics.