How to Create Redirects in Antora

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.

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

While not too well documented — yet! — Antora fully 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 pages that will redirect to the current page.

For example, let's say that you have an existing page, 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

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

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.

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.

P.S. If you need assistance on any of your PHP projects, I am available for hire for freelance work.


Matthew Setter. Ethical Hacker, Online Privacy Advocate, and a Software Engineer.

Matthew Setter

Software Engineer, Ethical Hacker, & Online Privacy Advocate.

Matthew Setter is a software engineer, ethical hacker, privacy advocate, & technical writer, who loves travelling. He is based in Nuremberg, Germany. When he's not doing all things tech, he's spending time with his family, and friends.