用网页别名设置URL重定向

您可以使用 Antora 的内置页面别名属性创建从旧页面到新页面的重定向。当您删除页面、重命名页面文件或将页面移动到不同的模块或组件时，此页面属性非常有用。使用 page-alias 属性，页面可以声明一个或多个其他页面的标识。然后，Antora 将这些页面的 url 重定向到定义别名的页面。

页面别名和批量URL重定向

页面别名用于处理页面重命名或移动，特别是在组件版本中。它们不是通用的 URL 路由器。尽管它们可用于跨组件或组件版本创建重定向，但您需要小心使用此特性，否则它可能会变得非常嘈杂，从而令人困惑。

如果删除了大量的页面，例如删除或重命名组件或组件版本，并且希望保留现有的 url ，则不应该尝试使用页面别名来执行此操作。页面别名不是为提供批量 URL 重定向而设计的。相反，我们强烈建议您在删除或重命名组件或组件版本时使用 web 服务器或主机提供的路由器。您可以在发布期间使用单独的步骤或使用 Antora 扩展来完成此操作。

page-aliases属性

page-aliases 属性通过属性条目设置在目标页面的页眉中。目标页面是指将源页面重定向到的页面。源页面是指被删除、重命名或移动的页面，您要将其重定向（即所要求的页面）。在目标页面中，将源页面的资源ID——即在其被删除、重命名或移动之前的资源ID——分配给 page-aliases 属性。在属性中，可以用逗号分隔的列表为其分配多个资源ID。

Example 1. Example 1. Header of target page

= Title of Target Page
:page-aliases: source-page-filename.adoc, version@component:module:source-page-filename.adoc

您可以使用行延续符(行尾的空格后跟反斜杠)将该列表分割为多行。

Example 2. Example 2. Page aliases split across multiple lines

= Title of Target Page
:page-aliases: source-page-filename.adoc, \
version@component:module:source-page-filename.adoc

Antora 会计算源页面资源 ID 的 URL ，并生成重定向信息，以便源页面 URL 重定向到目标页面 URL 。对于分配给 page-aliases 属性的资源ID中未指定的版本或组件等坐标，将从目标页面的坐标进行插值。重定向信息的生成输出格式由您选择的重定向工具确定。

分配给 page-aliases 属性的资源ID可以在交叉引用（ xref ）中使用。因此，如果您删除、重命名或移动某个页面，则无需在源文件中更新任何对它的引用。

页面别名限制

page-aliases 属性只能应用于页面，而无法应用于局部、示例、图像和附件。虽然分配给 page-aliases 属性的资源ID在交叉引用中可以使用，但参考界面中的页面版本选择器不会将源页面的先前版本与目标页面相连接，两者之间没有关联。

为重命名的页面创建重定向

如果您将源页面的文件名从 old-name.adoc 更改为 new-name.adoc ，则需要在其页眉中将文件的先前资源ID分配给 page-aliases 属性。

Example 3. Example 3. new-name.adoc

= Title of Target Page
:page-aliases: old-name.adoc

这将导致 https//base-url.com/component/version/module/old-name.html 的重定向到 https//base-url.com/component/version/module/new-name.html 。未在 old-name.adoc 资源ID中指定的版本、组件和模块坐标将从目标页面的坐标插值而来。或者，如果您在 playbook 中将 html-extension-style 键值指定为 indexify ，则 https://base-url.com/component/version/module/old-name/ 将重定向到 https://base-url.com/component/version/module/new-name/ 。

为移动的页面创建重定向

当页面从同一组件中的一个模块移动到另一个模块时，别名资源ID需要包含源页面以前的模块坐标。在示例4中，页面 source-1.adoc 已从 module-1 移动到 module-z 。 module-1 和 module-z 都是 component-1 的 5.0 版本中的模块。

Example 4. Example 4. source-1.adoc

= Title of Target Page
:page-aliases: module-1:source-1.adoc (1)

1	在将页面移动到另一个模块时，除了指定文件坐标外，还指定前一个模块坐标。

现在，Antora 会将 URL https://base-url.com/component-1/5.0/module-1/source-1.html 重定向到 URL https://base-url.com/component-1/5.0/module-z/source-1.html 。

当页面从一个组件移动到另一个组件时，请将源页面的完全限定先前资源ID分配给 page-aliases 属性。在示例5中，页面 source-w.adoc 已从 component-8 module-u 的版本 1.4 移动到 component-delta ROOT 版本 3.0 中。

Example 5. Example 5. source-w.adoc

= Title of Target Page
:page-aliases: 1.4@component-8:module-u:source-w.adoc

这将导致URL https://base-url.com/component-8/1.4/module-u/source-w.html 的重定向到URL https://base-url.com/component-delta/3.0/source-w.html 。

为已删除的页面创建重定向

有时你只需要删除一个页面。在将已删除页面的 URL 重定向到另一个页面之前，请考虑以下问题：

是否有一个潜在的目标页面可以帮助以前使用过删除页面上信息的访问者?例如，被删除的页面描述了功能A，但功能A已被弃用;功能A的用户现在应该迁移到功能B。
被删除的页面是高流量页面吗?如果有，是否有一个相关的页面，肯定会帮助人们寻找被删除的页面

您不应该创建重定向到与已删除页面没有太多共同之处的目标页面，因为这通常会使访问者感到沮丧。

如果将已删除页面的URL重定向到另一个页面是合适的，请将已删除页面的ID分配给 page-aliases 属性，并确保指定必要的坐标。

Example 6. Example 6. Target page

= Title of Target Page
:page-aliases: source-page-filename.adoc

TIP: 将删除的页面重定向到网站主页或项目的起始页，会造成糟糕的用户体验(也是糟糕的SEO实践)。这一政策使访问者感到困惑，因为他们可能没有意识到他们正在寻找的页面已经不存在了。如果没有一个高度相关的目标页面来重定向被删除的页面，那么最好将访问者定向到自定义的 404 页面。