站点URL
URL键
站点的url键，在playbook中的站点键下定义，是可选的，但建议设置。如果未设置此键，则自动停用需要站点URL的某些站点功能。有关详细信息，请参见何时应设置站点URL？
site:
title: 站点标题
url: https://docs.example.comurl键定义了站点发布后可以访问的位置。url键的值可以是绝对URL（https://docs.example.com，https://example.com/docs）或根相对URL（/products）。在url值中不要包含尾部斜杠，除非该值是单个斜杠（/）。
站点URL出现在生成的站点中，无论何时需要绝对URL或根相对URL。请参阅Antora如何构建URL以了解更多信息。
配置绝对站点URL
绝对URL值以URL方案直接跟着冒号和两个斜杠（https://）以及一个域名（docs.example.org）开头。在URL末尾不要放置尾部斜杠。
site:
title: 示例站点文档
url: https://docs.example.com绝对站点URL可以包括子路径（例如，https://example.com/docs，https://example.com/path/to/subfolder）。子路径，也称为路径段或路径名，表示Antora管理的站点发布在域的根目录的位置。如果您的站点发布到域的子文件夹，则绝对站点URL必须包含此路径。子路径具有与根相对URL相同的语法。
site:
title: 示例站点文档
url: https://example.com/docs有关将站点发布到域子文件夹的更多信息，请参见何时应在站点URL中包含子路径？
配置根相对站点URL
根相对URL是相对于域的URL，但无需指定域本身。根相对URL必须以斜杠开头（/products）。
site:
title: 某处托管的文档
url: /products如果必须将相同的站点发布到多个域或通过多个域访问相同的站点，则可以使用根相对URL代替绝对URL。通过使用根相对URL，您可以利用分配站点URL的许多优势。但是，当分配给url的值不是绝对时，Antora会停用任何依赖于绝对站点URL的功能。
site:
title: 文档
url: /何时应设置站点URL？
Antora站点设计为可以离线查看并从本地文件系统访问。因此，构建站点时不需要站点URL。
然而，有些与发布相关的功能需要站点URL，甚至需要绝对URL。如果未设置站点URL，则这些功能将自动停用而不会通知。本节将识别这些功能以及它们需要哪种类型的站点URL。
依赖站点URL的功能
当站点URL设置为任何允许的值时，将启用以下功能：
-
在每个AsciiDoc文档上设置
site-url属性。 -
在UI模型中设置
site.url属性（使用playbook中site.url键的值）。 -
在UI模型中设置
site.path属性（从playbook中site.url键派生）。 -
生成404页面。
-
如果playbook中也定义了
site.robots，则生成robots.txt文件。 -
重定向包括站点路径名（
site.path），如果不为空。这不影响使用相对URL的静态重定向功能。 -
导航栏左上角的链接指向站点URL而不是相对路径（特定于默认UI的行为）。
当站点URL设置为绝对URL时，将启用以下附加功能：
-
生成站点地图文件。
-
在UI模型中设置
page.canonicalUrl，供参考UI使用以在头部创建规范链接标签。
如果未设置站点URL，则所有上述功能将被停用。
何时应在站点URL中包含子路径？
站点URL的子路径表示由Antora管理的站点位于域的根目录的位置。换句话说，站点URL将访问者带到站点起始页面重定向的URL。如果您的站点发布到域的子文件夹中，则站点URL应包含此路径（例如，/path/to/subfolder）。
在必要时，Antora使用站点URL构建到站点页面的绝对和域相对URL，如果指定了子路径，则始终包括该子路径。这包括站点地图中的URL（绝对URL）以及重写规则（域相对URL）。
让我们看一个示例，说明在创建服务器重定向规则时如何使用子路径。假设以下条件为真：
-
站点发布到example.com域的docs子文件夹中。
-
版本无关的component-a组件的ROOT模块中的页面new-page.adoc定义了old-page.adoc的页面别名（意味着old-page.adoc已重命名为new-page.adoc）。
-
将重定向功能设置为
nginx。 -
在playbook中将站点
url键设置为https://example.com（错误的值）。
运行Antora时，将生成以下重定向规则：
/component-a/old-page.html /component-a/new-page.html 301!
请注意，重定向规则中的域相对URL不包括前导/docs段。这意味着如果您访问https://example.com/docs/component-a/old-page.html，您将不会被重定向到新页面，因为规则不匹配。让我们修复这个问题。
编辑您的playbook，并将url键设置为https://example.com/docs。现在运行Antora，它将生成正确的重定向规则：
/docs/component-a/old-page.html /docs/component-a/new-page.html 301!
请注意，域相对URL中包含前导/docs段。现在，当您访问https://example.com/docs/component-a/old-page.html时，您将被重定向到新页面。
规范URL
Antora提供了对规范URL的内置支持。 规范URL 是首选页面的绝对URL；即您希望搜索引擎索引的页面。
如果将绝对URL分配给站点URL，Antora会计算并将规范URL分配给UI模型中任何适用页面的page.canonicalUrl属性。 适用页面是指组件中至少有一个非预发布版本的可发布页面。 如果站点URL未设置为绝对URL，或页面不在具有至少一个非预发布版本的组件中，则Antora不会填充规范URL。
规范URL是页面的最新非预发布版本的绝对URL。 规范URL是通过将站点URL（包括子路径）前置到该页面的（根相对）URL来计算的。
规范URL仅指向当前页面，如果当前页面是最新的非预发布版本。 否则，规范URL将指向当前页面的最新非预发布版本。
| 如果页面已被删除，则页面的最新版本可能不在组件的最新版本中。 |
规范URL链接标签
为了使搜索爬虫捕捉到规范URL，UI模板必须在页面中包含它。 规范URL应声明为页面<head>标签内<link rel="canonical">标签的href属性的值。 Antora的默认UI会为您执行此操作。 以下是Antora默认UI中生成此<link>标签的模板逻辑：
{{#with page.canonicalUrl}}
<link rel="canonical" href="{{{this}}}">
{{/with}}以下是规范URL在生成的页面中的显示方式：
<link ref="canonical" href="https://docs.example.org/component-name/2.0/page-name.html">假设规范URL所指的页面存在于组件的所有版本中，则所有页面版本将包含相同的<link>标签。 如果页面位于预发布版本中，则它将指回最新（非预发布）版本中的页面。
| 决定是否在页面模板中包含规范URL取决于自定义UI的创建者。 Antora仅通过UI页面模型提供信息。 Antora的默认UI在页面模板中包含所需的标签。 |