重定向设施关键字

根据您指定的重定向设施,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重定向设施的重定向文件不同,规则不以!结尾。

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

nginx

Antora生成一个名为rewrite.confnginx重写配置文件,并将其放置在生成站点的.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

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

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

静态(meta refresh)

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

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

  1. 目标页面的规范URL。

  2. 分配值为refreshhttp-equiv meta属性。

  3. 分配值为0和访问者将被重定向到的相对目标页面的URL的content meta属性。 0表示访问者将在0秒内重定向到目标页面。

  4. 重定向通知,告知访问者源页面不再存在,并提供到目标页面的链接。

示例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>