Set Up URL Redirects with page-aliases

You can create a redirect from an old page to a new page using Antora’s built-in page-aliases attribute. This page attribute is useful when you delete a page, rename a page’s file, or move a page to a different module or component. Using the page-aliases attribute, a page can claim the identity of one or more other pages. Antora will then redirect the URLs for those pages to the page in which the aliases are defined.

Page aliases and bulk URL redirects

Page aliases are designed to address page renames or moves, particularly within a component version. They are not a general-purpose URL router. Although they can be used to create redirects across components or component versions, you need to use this feature with care or else it can become quite noisy and thus confusing.

If you remove a large number of pages, such as if you remove or rename a component or component version, and you want to preserve the existing URLs, you should not attempt to do so using page aliases. Page aliases were not designed to provide bulk URL redirects. Instead, we strongly recommended that you use the router provided by your web server or host when you remove or rename a component or component version. You can do so either using a separate step during publishing or by using an Antora extension.

page-aliases attribute

The page-aliases attribute is set in the page header of a target page using an attribute entry. The target page refers to the page you’re redirecting a source page to. The source page refers to the deleted, renamed, or moved page that you’re redirecting from (i.e., the page to claim). A source page’s resource ID—​its resource ID before it was deleted, renamed, or moved—​is assigned to the page-aliases attribute in a target page. Multiple resource IDs can be assigned to the attribute in a comma-separated list.

Example 1. Header of target page
= Title of Target Page
:page-aliases: source-page-filename.adoc, version@component:module:source-page-filename.adoc

You can split this list across multiple lines using a line continuation (a space followed by a backslash at the end of the line):

Example 2. Page aliases split across multiple lines
= Title of Target Page
:page-aliases: source-page-filename.adoc, \
version@component:module:source-page-filename.adoc

Antora calculates the URL for a source page’s resource ID and generates redirect information so that the source page URL redirects to the target page URL. Any coordinates, such as version or component, that aren’t specified in a resource ID assigned to page-aliases are interpolated from the target page’s coordinates. The generated output format of the redirect information is determined by your chosen redirect facility.

A resource ID assigned to a page-aliases attribute can be used in an xref. Therefore, if you delete, rename, or move a page, you don’t need to update any references to it in your source files.

Page alias restrictions

The page-aliases attribute can only be applied to pages. Partials, examples, images, and attachments can’t be aliased. While a resource ID assigned to page-aliases works in xrefs, the page version selector in the reference UI does not connect previous versions of the source page to the target page.

Create a redirect for a renamed page

If you change a source page’s filename from old-name.adoc to new-name.adoc, assign the file’s former resource ID to page-aliases in its header.

Example 3. new-name.adoc
= Title of Target Page
:page-aliases: old-name.adoc

This will result in https://base-url.com/component/version/module/old-name.html being redirected to https://base-url.com/component/version/module/new-name.html. The version, component, and module coordinates that weren’t specified in the old-name.adoc resource ID are interpolated from the target page’s coordinates. Alternatively, if you assigned indexify to the html-extension-style key in your playbook, https://base-url.com/component/version/module/old-name/ will redirect to https://base-url.com/component/version/module/new-name/ .

Create a redirect for a moved page

When a page is moved from one module to another module in the same component, the aliased resource ID needs to contain the source page’s former module coordinate. In Example 4, the page source-1.adoc has moved from module-1 to module-z. Both module-1 and module-z are modules in version 5.0 of component-1.

Example 4. source-1.adoc
= Title of Target Page
:page-aliases: module-1:source-1.adoc (1)
1 Specify the former module coordinate in addition to the file coordinate when moving a page to another module.

Now, Antora will redirect the URL https://base-url.com/component-1/5.0/module-1/source-1.html to the URL https://base-url.com/component-1/5.0/module-z/source-1.html.

When a page is moved from one component to another component, assign the source page’s fully qualified former resource ID to page-aliases. In Example 5, the page source-w.adoc has moved from version 1.4 of component-8, module-u to version 3.0 of component-delta, ROOT.

Example 5. source-w.adoc
= Title of Target Page
:page-aliases: 1.4@component-8:module-u:source-w.adoc

This will result in the URL https://base-url.com/component-8/1.4/module-u/source-w.html being redirected to https://base-url.com/component-delta/3.0/source-w.html.

Create a redirect for a deleted page

Sometimes you just need to delete a page. Before redirecting the deleted page’s URL to another page, consider the following:

  • Is there a potential target page that would help the visitors who previously used the information on the deleted page? For instance, the deleted page described feature A, but feature A has been deprecated; users of feature A should now migrate to feature B.

  • Is the deleted page a high traffic page? If so, is there a relevant page that would definitely assist the people looking for the deleted page?

You shouldn’t create a redirect to a target page that doesn’t have much in common with the deleted page, as this often frustrates visitors.

If it’s appropriate to redirect the deleted page’s URL to another page, assign the deleted page’s ID to the page-aliases attribute, making sure to specify the necessary coordinates.

Example 6. Target page
= Title of Target Page
:page-aliases: source-page-filename.adoc
It creates a bad user experience (and is a bad SEO practice), to redirect deleted pages to the site’s home page or a project’s start page. This policy confuses visitors because they may not realize the page they’re looking for no longer exists. In cases where there isn’t a highly relevant target page to redirect the deleted page to, it’s better to direct visitors to a custom 404 page.