Antora 101: How to Create Redirects

Whenever you create online documentation, eventually, the structure needs to change; such as a name change, content restructure, or old content is removed. When these times come, it's important to create redirects to avoid breaking user expectations. In this post, I'm going to step you through how to do so with Antora.

Published on: May 30, 2019
Technical Writing

Want to learn more about Docker?

Are you tired of hearing how "simple" it is to deploy apps with Docker Compose, because your experience is more one of frustration? Have you read countless blog posts and forum threads that promised to teach you how to deploy apps with Docker Compose, only for one or more essential steps to be missing, outdated, or broken?

Check it out

Speaking from experience, creating redirects in Antora is quite trivial, as it only involves two steps:

  1. Use page attributes to create redirects in source files.
  2. Use the --redirect-facility option when building your documentation.

1. Use Page Attributes to Create Redirects In Source Files

Antora supports creating redirects for all content available in a generated site. It does so by using the page-aliases page-level attribute. This AsciiDoc attribute contains a comma-separated list of page references that redirect to the current page. Page references follow Antora’s Xref format.

They can link to pages:

  • In the current module
  • In another module
  • In a different component

Examples

Redirect Within The Same Module

Let's say that you have a page in the current module, named upgrade/service/apache.adoc, and it was moved to a new directory, upgrade/server, for whatever reason.

To redirect requests from the original location to the new location, at the top of upgrade/server/apache.adoc, add a page-aliases attribute with a link to the original location, as in the following example:

= Page Title
:page-aliases: upgrade/service/apache.adoc

Redirect to a Different Module

Now let’s say that you want to redirect upgrade/service/apache.adoc in the current module to the same location in a new module, called webservers. To do that, you prefix the path with the module name, separated by a colon, as in the following example:

= Page Title
:page-aliases: webservers:upgrade/service/apache.adoc

Redirect to a Different Module in a Different Component

Finally, let’s say that you want to redirect upgrade/service/apache.adoc in the current module to the same location in the webservers module, but in a different component, called sysadmin. To do that, you prefix the path with the module name, separated by a colon, and prefix the module with the component, separated by a colon, as in the following example:

= Page Title
:page-aliases: sysadmin:webservers:upgrade/service/apache.adoc

For a more in-depth discussion on Antora’s Xref syntax, please refer to the relevant Antora documentation.

2. Use the --redirect-facility Option When Building Your Documentation

Now that at least one of the pages of source content uses the page-aliases attribute, you need to tell Antora to generate redirects when it builds your documentation. To do this, you need to use the --redirect-facility option, as in the example below.

antora --redirect-facility nginx playbook.yml

This option supports four options; these are: static, netlify, nginx, and disabled.

static

static is the default. When used, Antora generates static bounce pages for each page that is to redirected from. Each page will contain:

  • A link to the new, canonical reference
  • A meta refresh tag to redirect to the new canonical reference
  • A notice, letting the reader know that the old page no longer exists along with the location of the new page.

Here is an example of the generated static configuration.

<!DOCTYPE html>
<meta charset="utf-8">
<link rel="canonical" href="http://localhost:5000/upgrade/server/apache.html">
<script>location="marketplace_apps.html"</script>
<meta http-equiv="refresh" content="0; url=../server/apache.html">
<meta name="robots" content="noindex">
<title>Redirect Notice</title>
<h1>Redirect Notice</h1>
<p>
  The page you requested has been relocated to
  <a href="../server/.html">http://localhost:5000/server/apache.html</a>.
</p>

netlify

When netlify is used, Antora generates a Netlify _redirects file, called _redirects, in the Playbook's output directory, which contains the generated rewrite configuration. Here is an example of the generated Netlify configuration.

/upgrade/service/apache.html /upgrade/server/apache.html 301

The first item is the path to match. The second item is path to redirect to, when a match is encountered. The third value is the HTTP code to redirect with.

Once the _redirects file is generated, no further changes are required in your build server. When present, Netlify will make use of the file and start handling the required redirects. Honestly, I couldn't imagine a simpler setup.

nginx

When nginx is used, Antora generates an NGINX rewrite configuration in a file called rewrite.conf, in a new directory called .etc/nginx, which is itself created inside the Playbook's output directory. Here is an example of the generated NGINX configuration.

location = /upgrade/service/apache.html {
  return 301 /upgrade/server/apache.html;
}

The top line specifies the path to match The line inside the curly braces tells NGINX the HTTP status code to send and where to redirect to, if the path is matched in a request.

Note: After Antora generates the file, don't forget to update your build server configuration to ensure that NGINX makes use of the generated rewrite.conf.

disabled

When disabled is used, no redirects are generated.

Things to Watch Out For

Be careful not to create circular redirects when using this attribute. I encountered this recently, and it resulted in Antora failing to build.

Secondly, you cannot create redirects to pages that already exist (naturally). If you attempt to do so, you will see the following error when you run antora:

Error: Page alias cannot reference an existing page

In Conclusion

And that's how to create redirects in Antora, when the structure of your technical documentation changes. Like almost everything in Antora, it only requires a text change and a re-run of Antora. I'd go into greater depth, but I don't see anything else worth saying.

If you've been wondering how to create redirects in Antora, this short tutorial will set you on the right path. If you're not yet using Antora, I'd love to hear how your technical documentation platform implements redirects. Please share your input in the comments.

Further Reading

If you're keen to learn more about Antora, check out the Antora docs. And if you're just getting started using Antora, make sure to get involved in the online community.