站点URL

url键

网站的 url 键(在剧本中的站点键下定义)是可选的，但推荐使用。如果未设置此键，则需要站点 URL 的站点的某些功能将自动停用。请参见何时设置站点URL ?获取详细信息。

Example 1. Example 1. antora-playbook.yml

site:
  title: Site Title
  url: https://docs.example.com

url 键定义了发布后可以访问站点的位置。url 键的值可以是绝对 URL（https://docs.example.com，https://example.com/docs ）或根相对 URL（/products）。除非值是单个正斜杠（/），否则不要在 url 值中包含尾部正斜杠。

只要设置了绝对 URL 或根相对 URL ，该站点 URL 就会出现在生成的站点中。参见 Antora 如何构建 url 以了解更多信息。

或者，url 键可以使用 --url 选项或 url 环境变量从 CLI 中赋值。

配置一个绝对站点URL

绝对 URL 值以 URL 方案直接跟着冒号和两个正斜杠（ https:// ）和一个域名（ docs.example.org ）开头。不要在 URL 末尾加上尾部正斜杠。

Example 2. Example 2. antora-playbook.yml

site:
  title: Docs for Example Site
  url: https://docs.example.com

绝对站点 URL 可以包含一个子路径（例如，https://example.com/docs，https://example.com/path/to/subfolder ）。子路径，也称为路径段或路径名，表示 Antora 管理的站点发布的根域的位置。如果您的站点发布到您的域的子文件夹中，则绝对站点 URL 必须包括此路径。子路径具有与根相对 URL 相同的语法。

Example 3. Example 3. antora-playbook.yml

site:
  title: Docs for Example Site
  url: https://example.com/docs

当绝对站点 URL 具有子路径时，Antora 会提取该子路径并将其分配给站点路径（/docs，/path/to/subfolder），以便在需要域名相对 URL 的任何地方使用。

请参阅网站URL何时应该包含子路径 ?有关将网站发布到域子文件夹的详细信息。

配置一个相对根站点URL

根相对 URL 是相对于域的 URL ，但不需要指定域本身。根相对 URL 必须以正斜杠开头（ /products ）。

Example 4. Example 4. antora-playbook.yml

site:
  title: Docs Hosted Somewhere
  url: /products

如果必须通过多个域发布或访问相同的站点，则可能使用根相对 URL 代替绝对 URL 。通过使用根相对 URL ，您可以利用分配站点 URL 的许多好处。但是，当分配给 url 的值不是绝对的时，Antora 会停用任何依赖于绝对站点 URL 的功能。

Antora 将根相对 URL 直接分配给站点路径名，用于计算域相对 URL 。如果您希望将 url 设置为根相对 url ，但希望站点路径名为空，请将值设置为单个正斜杠。

Example 5. Example 5. antora-playbook.yml

site:
  title: The Docs
  url: /

站点URL应该什么时候设置

Antora 站点被设计成可以从本地文件系统脱机查看。因此，构建站点时不需要站点 URL 。

然而，与发布相关的某些功能需要站点 URL ，有些甚至是绝对 URL 。当站点 URL 未设置时，这些功能将自动停用，无需通知。本节确定这些特性以及它们需要的站点 URL 类型。

依赖站点URL的功能

当站点 URL 设置为任何允许的值时，将启用以下功能：

site-url 属性设置在每个 AsciiDoc 文档上。
site.url 属性在 UI 模型中设置(使用 playbook 中的 site.url 键的值)。
站点路径名属性，site.path ，在 UI 模型中设置(源自剧本中的 site.url 键)。
生成404页面。
如果在 playbook 中定义 site.robots 则生成 robots.txt 文件。
重定向包括站点路径名( site.path )，如果非空的话。这不会影响使用相对 url 的静态重定向功能。
导航条左上角的链接指向站点 URL ，而不是相对路径(特定于默认 UI 的行为)。

当站点 URL 设置为绝对 URL 时，将启用以下附加功能：

生成 sitemap 文件
在 UI 模型中设置 page.CaronicalUrl ，该模型由引用 UI 使用来创建头部的规范链接标签。

如果没有设置网站 URL ，上述所有功能都将被禁用。

什么时候站点URL应该包含子路径

站点 URL 的子路径表示 Antora 管理的站点位于域的根目录的位置。换句话说，站点 URL 会将访问者带到站点起始页重定向所在的 URL 。如果您的站点发布到您的域的子文件夹中，则站点 URL 应包括此路径（例如，/path/to/subfolder ）。

当需要时，Antora 使用站点 URL 来构造指向站点中页面的绝对 URL 和域相对 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 时，它会生成以下重定向规则：

Example 6. Example 6. A redirect entry that does not includes a subpath

/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 时，它将生成正确的重定向规则：

Example 7. Example 7. A redirect entry that includes a subpath

/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 中是很重要的。如果不想将站点与特定的域耦合，请分配一个根相对站点 URL 。无论哪种方式，如果要将站点发布到您的域的子文件夹中，则应将子路径包括在您分配给站点 url 键的值中。

标准URL

Antora 提供了对规范 url 的内置支持。规范 URL 是页面的首选版本的绝对 URL ;您希望搜索引擎索引的页面。

如果您将绝对 URL 分配给站点 URL , Antora 将计算并将规范 URL 分配给页面。在 UI 模型中为任何适用的页面添加 canonicalUrl 属性。适用的页面是组件中至少有一个非预发布版本的任何可发布页面。如果站点 URL 没有设置为绝对 URL ，或者页面不在至少有一个非预发布版本的组件中，则 Antora 不会填充规范 URL 。

规范 URL 是页面的最新、非预发布版本的绝对 URL 。规范 URL 是通过将站点 URL (包括子路径)附加到该页的(根相对的) URL 来计算的。

只有当当前页面是最新的非预发布版本时，规范 URL 才指向当前页面。否则，规范 URL 将指向当前页面的最新的非预发布版本。

CAUTION: 如果该页面已被删除，则该页面的最新版本可能不在组件的最新版本中。

规范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> 标记。如果页面在预发布版本中，则将返回到最新（非预发布）版本中的页面。

TIP: 是否在页面模板中包含规范 URL 由自定义 UI 的创建者决定。Antora 仅仅通过 UI 页面模型提供信息。Antora 的默认 UI 在页面模板中包含所需的标记。

规范URL是如何工作的

规范 URL 的目的是帮助搜索引擎对同一页面的不同版本进行关联，并建议首选哪个版本进行索引。当搜索引擎遇到一个页面，它的规范 URL 与当前 URL 不同，搜索引擎不应该索引该页面，而应该索引规范 URL 所指向的页面。通过定义规范 URL，应该确保旧版本的页面不会出现在搜索结果中。

有一个注意事项是，如果页面存在于旧版本的组件中，但不在最新版本中，规范 URL 将指向较旧版本中的一个页面，并因此被索引。如果不想发生这种情况，请确保最新版本的组件中的另一个页面使用页面别名来声明该页面。这样，Antora 将配置规范 URL，以指向声明该页面的页面，从而避免旧页面被索引。

使用 URL 检查工具查看 Google 对页面检测到的规范 URL 和页面是否被索引。有关规范 URL 及其被搜索引擎（如 Google）如何解释它们的更多信息，请参见合并重复 URL 和规范 URL。