I've Been Using The AsciiDoc Intellij Plugin For a Month. Here's My Review.
I’ve been reviewing the AsciiDoc plugin for IntelliJ over the last four weeks. In this post, I share everything that I learned.
Speaking from experience, creating redirects in Antora is quite trivial, as it only involves two steps:
- Use page attributes to create redirects in source files.
- Use the
--redirect-facilityoption 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.
Join the discussion
comments powered by Disqus