Set Up URL Redirects with page-aliases

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. A source page’s page ID—​its page ID before it was deleted, renamed, or moved—​is assigned to the page-aliases attribute in a target page. Multiple page IDs can be assigned to the attribute in a comma-separated list.

Antora calculates the URL for a source page’s page 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 page 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 page 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.

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

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 page 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/ .

When a page is moved from one module to another module in the same component, the aliased page ID needs to contain the source page’s former module coordinate. In Example 3, 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.

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 page ID to page-aliases. In Example 4, the page source-w.adoc has moved from version 1.4 of component-8, module-u to version 3.0 of component-delta, ROOT.

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.

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

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.