Set Up URL Redirects with Page Aliases

You can create a redirect using the page-aliases attribute. This document attribute is useful when you delete a page, rename a page’s file, or move a page to a different module or component.

Bulk URL Redirects
The page-aliases attribute should not be used to create bulk redirects. We strongly recommended that you use the router provided by your web server or service when a module, component, or version is deleted, renamed, or moved.

The page-aliases attribute

The page-aliases attribute is set in the header of a target page. 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.

Example 1. Header of target page
= Title of Target Page
:page-aliases: page ID, page ID

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 are missing from a source page’s page ID are interpolated from the target page’s coordinates. The generated output format of the redirect information is determined by your chosen redirect facility.

Page Alias Limitations

  • A page ID assigned to a page-aliases attribute can’t be used in an xref. Therefore, if you delete, rename, or move a page, you need to update any references to it in your source to the page ID of the target page. The ability to use aliased page IDs in xrefs is scheduled for a future Antora release.

  • Page aliases can only be applied to pages. Partials, examples, images, and attachments can’t be aliased.

Create a redirect for a renamed page

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

Example 2. 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 missing page ID coordinates (version, component, module) for the source page old-name.adoc are interpolated from the target page’s coordinates.

Create a redirect for a moved page

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.

Example 3. Alias for source-1.adoc when it’s moved from module-1 to module-z
:page-aliases: module-1:source-1.adoc

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.

Example 4. Alias for source-w.adoc when it’s moved to the ROOT module of version 3.0 of component-delta
: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.