重定向设施关键字

根据您指定的重定向设施，Antora设置了起始页面、符号最新版本和页面别名的自动路由。

默认情况下，Antora为每个URL别名生成一个静态HTML文件，将访问者重定向到目标页面。Antora还可以生成特定于Web服务器的配置文件，利用Web服务器的重定向/重写功能来处理路由。

如果站点未定义任何重定向，Antora将不会生成任何重定向文件（例如_redirects）。

Antora从站点和组件版本的起始页面、最新版本别名以及使用page-aliases属性定义的页面别名派生这些URL路由。对于页面别名，目标页面是源页面重定向的页面。目标页面也是定义页面别名的地方。源页面是正在被重定向的别名页面（即，所声称的页面）。

redirect_facility关键字及其值

playbook关键字redirect_facility是可选的。它可以在playbook中或通过CLI进行配置，并接受以下内置值之一：

禁用（disabled）

不生成任何重定向文件。如果站点未定义任何重定向，则此值将生效。

gitlab

为GitLab Pages生成名为_redirects的重定向文件，并将其放置在发布站点的根目录。

httpd

为Apache httpd生成名为.htaccess的重定向文件，并将其放置在发布站点的根目录。

netlify

为Netlify生成名为_redirects的重定向文件，并将其放置在发布站点的根目录。

nginx

为nginx生成名为rewrite.conf的重定向文件，并将其放置在发布站点的.etc/nginx/rewrite.conf位置。

默认情况下，nginx不会知道在此位置查找文件。您需要将其移动到nginx可以找到的位置，或者配置nginx在此位置使用它。

static

（默认）在源页面的URL处生成一个带有http-equiv元素设置为refresh的静态HTML文件。该文件提供重定向通知，并将源页面URL路由到目标页面URL。

Antora会自动将值static分配给redirect_facility关键字，除非您明确配置它。

从playbook配置重定向设施

redirect_facility关键字在playbook中的urls关键字下配置。

示例1. antora-playbook.yml

urls:
  redirect_facility: netlify

从CLI配置重定向设施

redirect_facility关键字也可以从CLI中进行配置。

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

CLI选项会覆盖playbook中指定的值。

选择重定向设施配置

您站点的URL重定向应如何配置取决于您用来提供站点的Web服务器或服务。

如果您使用默认的重定向设施，Antora将生成使用HTML的meta refresh功能来将访问者路由到目标页面（即跳转页面）的HTML页面。当您检查站点的输出时，您会发现以.html结尾的页面，其中包含一个<meta http-equiv="refresh">标签在一个最小的HTML结构内。如果您已指定站点的起始页面，这将包括在已发布站点的根目录下的index.html页面。

如果您使用其他任何重定向设施，Antora将不会生成这些跳转页面。（换句话说，不要期望在已发布站点的根目录下找到index.html页面）。相反，Antora依赖于Web服务器来应用它生成的重定向规则。有关这些规则及其编写位置的详细信息，请参见下面的各节。

起始页面和页面别名的重定向规则使用301 HTTP状态代码进行定义，这意味着重定向被视为永久的。最新版本别名的重定向规则使用302 HTTP状态代码进行定义，这意味着重定向被视为临时的。

Web服务器特定的重定向/重写规则中的位置与在站点中访问页面的URL匹配，因此取决于urls.html-extension-style键的值。默认情况下，位置将以.html结尾。如果将HTML URL扩展样式更改为indexify，则位置将以/结尾。

Netlify

在由Netlify提供服务的站点上配置重定向规则是在名为_redirects的纯文本文件中进行的。当分配的重定向设施值为netlify时，Antora将生成_redirects文件并将其放置在生成站点的根目录下。

示例2. 由Antora生成的用于Netlify的_redirects文件

/index.html /component/version/index.html 301!
/ /component/version/index.html 301!
/component/version/module/old-name.html /component/version/module/new-name.html 301!

上面的示例输出显示了两种情况的重定向规则。第一个情况由前两条规则处理，将用户从根域路由到站点起始页面的URL，使用301 HTTP状态代码。第二个情况由最后一条规则处理，将用户从重命名页面的URL路由到其新URL，使用301 HTTP状态代码。

GitLab

在由GitLab Pages提供服务的站点上配置重定向规则是在名为_redirects的纯文本文件中进行的。该文件的格式是Netlify文件的修改版本。当分配的重定向设施值为gitlab时，Antora将生成_redirects文件并将其放置在生成站点的根目录下。

示例3. 由Antora生成的用于GitLab Pages的_redirects文件

/index.html /component/version/index.html 301
/ /component/version/index.html 301
/component/version/module/old-name.html /component/version/module/new-name.html 301 (1)

1	与`netlify`重定向设施的重定向文件不同，规则不以`!`结尾。

nginx

Antora生成一个名为rewrite.conf的nginx重写配置文件，并将其放置在生成站点的.etc/nginx/rewrite.conf中。

示例4. 由Antora生成的nginx重写配置文件

location = /index.html { return 301 /component/version/index.html; }
location = /component/version/module/old-name.html { return 301 /component/version/module/new-name.html; }

上面的示例输出显示了两种情况的重定向规则。第一个情况由第一条规则处理，将用户从根域路由到站点起始页面的URL，使用301 HTTP状态代码。第二个情况由最后一条规则处理，将用户从重命名页面的URL路由到其新URL，使用301 HTTP状态代码。

使用nginx重定向设施时，Antora假定nginx配置方式类似于示例5中显示的配置。路径/srv/www指的是生成站点的位置。

示例5. 由Antora生成的加载重写配置的nginx配置

server {
  listen       80;
  server_name  _;
  root         /srv/www;

  location = /.etc/nginx/rewrite.conf {
    deny    all;
    return  404;
  }

  include /srv/www/.etc/nginx/rewrite.conf;

  location / {
      index  index.html;
      # 如果使用--html-url-extension-style=drop，请取消下一行的注释
      #try_files $uri $uri.html $uri/index.html = 404;
  }

  error_page  404  /404.html;
}

如果您的站点可以从不同的主机名或端口访问，或者是从不同的根目录提供服务，请调整配置。

httpd

Antora生成一个包含重定向规则的.htaccess文件，并将其放置在生成站点的根目录下。

示例6. 由Antora生成的.htaccess文件

Redirect 301 /index.html /component/version/index.html
Redirect 301 /component/version/module/old-name.html /component/version/module/new-name.html

使用httpd重定向设施时，Antora假定Apache httpd已配置为加载托管站点根目录下的.htaccess文件。

静态（meta refresh）

static重定向值对于部署在不接受或提供URL重定向配置文件的服务（如GitLab Pages和GitHub Pages）上的站点非常有用。当您在本地计算机上构建站点以测试起始页面和页面别名时，此设置也很有帮助。

Antora为每个别名源页面生成一个静态meta refresh页面，将访问者重定向到相应的目标页面。每个刷新页面包含：

目标页面的规范URL。
分配值为refresh的http-equiv meta属性。
分配值为0和访问者将被重定向到的相对目标页面的URL的content meta属性。 0表示访问者将在0秒内重定向到目标页面。
重定向通知，告知访问者源页面不再存在，并提供到目标页面的链接。

示例7. 用于将old-name.html重定向到new-name.html的静态meta refresh页面

<!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>您请求的页面已重定位到<a href="new-name.html">https://base-url.com/component/version/module/new-name.html</a>。</p>