Redirect Facility Key

Antora can generate static HTML refresh pages as well as Ngnix and Netlify redirect configuration files. These redirects are derived from a source page’s page ID that’s assigned to a page-aliases attribute in a target page’s header. The source page refers to the page you’re redirecting from. The target page refers to the page you’re redirecting to.

redirect_facility key and its values

The playbook key redirect_facility is optional. It can be configured in the playbook or via the CLI and accepts one of the following built-in values:

disabled

Redirects aren’t generated.

netlify

A Netlify format redirect file is generated and placed at the root of the generated site at _redirects.

nginx

An Nginx format redirect file is generated and placed at the root of the generated site at .etc/nginx/rewrite.conf.

static

(default) A static HTML file with the http-equiv meta element set to refresh is generated at the source page’s URL. The file provides a redirect notice and routes the source page URL to the target page URL.

Antora automatically assigns the value static to the redirect_facility key unless you explicitly configure it.

Configure the redirect facility from the playbook

The redirect_facility key is configured in the playbook under the urls key.

Example 1. antora-playbook.yml
urls:
  redirect_facility: netlify

Configure the redirect facility from the CLI

The redirect_facility key can also be configured from the CLI.

$ antora --redirect-facility netlify antora-playbook.yml

Choosing a redirect facility configuration

How your site’s URL redirects should be configured depends on the web server or service you use to serve your site.

Generated redirect configuration for Netlify

Redirect rules for sites served by Netlify are configured in a plain text file named _redirects. When the assigned redirect facility value is netlify, Antora generates _redirects and places it at the root of the generated site. Each redirect rule is automatically calculated by Antora from the page-aliases attributes, and then the 301 HTTP status code is applied to each rule. This means that each redirect is considered permanent.

Antora generated _redirects file
/component/version/module/old-name.html /component/version/module/new-name.html 301!

The example output above shows a redirect rule that routes the URL for a renamed page to it’s target page URL and the applied 301 HTTP status code.

Generated redirect configuration for Nginx

Antora generates an Nginx rewrite configuration file named rewrite.conf and places it in the generated site at .etc/nginx/rewrite.conf.

Antora generated rewrite.conf
location = /component/version/module/old-name.html { return 301 /component/version/module/old-name.html; }

The example output above shows a redirect rule with a 301 HTTP status code that permanently routes the URL for a renamed page to it’s target page URL.

Generated static HTML refresh pages

The static redirect value is useful for sites deployed on services, such as GitLab Pages and GitHub Pages, that don’t accept or provide access to URL redirection configuration files. This setting is also helpful when you build a site on your local machine to test your page-aliases.

Antora generates a static HTML refresh page for each aliased source page that redirects a visitor to the corresponding target page. Each refresh page contains:

  1. The canonical URL of the target page.

  2. The http-equiv meta attribute assigned the value refresh.

  3. The content meta attribute assigned the value 0 and the URL of the relative target page that the visitor will be redirected to. The 0 indicates that the visitor will be redirected to the target page in 0 seconds.

  4. A redirect notice, letting the visitor know that the source page no longer exists and providing a link to the target page.

Example 2. Generated static refresh page for old-name.html that redirects to new-name.html
<!DOCTYPE html>
<meta charset="utf-8">
<link rel="canonical" href="https://base-url.com/component/version/module/new-name.html">
<script>location="new-name.html"</script>
<meta http-equiv="refresh" content="0; url=new-name.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="new-name.html">https://base-url.com/component/version/module/new-name.html</a>.</p>