Antora 如何构建 url
Antora 使用来自资源id、站点URL 和站点剧本中的 URL 设置的信息为可发布的资源页面、附件和图像构建 URL 。
站点 URL
用户定义的，可选的。
站点 URL 标识您站点发布的位置。站点 URL 是通过给 playbook 中的 site.url 键、 --url 命令行选项 或 URL 环境变量 赋值可以接受的值来定义的。有两种类型的合法站点URL：绝对 URL 和根相对 URL 。
Antora 设计用于生成可以离线查看和从本地文件系统访问的站点。因此，Antora 不需要站点 URL 来构建站点。但是，当 Antora 没有检测到可接受的站点 URL 值时，它自动关闭某些发布功能。请参阅 取决于站点 URL 的功能 ，了解受影响功能的完整列表。
绝对站点URL
绝对站点 URL 以 https:// 开头，其后是站点域或子域。
如果要将站点发布到子文件夹，则站点域后跟子路径。
子路径，也称为路径段或路径名，表示从 Antora 管理的站点所在的域名的根开始的位置。也就是说，如果您的站点发布到域的子文件夹，那么站点的绝对 URL 应该包含此路径。请参见 配置绝对网站URL 和 网站URL何时应该包含子路径 ?以获取有关使用带子路径的绝对站点 URL 的更多信息。
相对于根站点URL
相对根站点 URL 以正斜杠( / )开头，如果有多个字符，则为子路径。
有关更多信息，请参见 配置根相关站点URL 。
站点路径名称
计算所得。
站点路径名表示一个内部属性 site.path ，当发布功能需要相对于站点根的 URL 时，Antora 使用该属性。Antora 根据站点 URL 计算站点路径名。站点路径名通常为空，除非绝对站点 URL 包含子路径或站点 URL 是相对根站点 URL 。如果 site.url 是包含子路径的绝对站点 URL ，Antora 会提取子路径并将其用作站点路径名。例如，使用 Figure 2 中的绝对站点 URL ，Antora 会提取子路径 /docs ，并将其分配给 site.path 。当赋给 site.url 的值是相对根站点 URL 时，Antora 提取整个值并将其作为站点路径名使用。Antora 将资源 URL 追加到站点路径名中以创建基于域名的 URL ，当某些功能（例如重定向）需要计算 URL 相对于站点域或站点根时。
正确的URL，正确的位置
Antora 生成和管理您站点中的所有 URL 。Antora 生成可发布资源的资源 URL 作为相对于站点路径名的绝对路径。然后，根据 URL 的上下文和URL使用的功能，将资源 URL 转换为相对于当前页面的 URL 、站点URL(site-pathname/resource-URL)或绝对URL(absolute-site-URL/resource-URL)。
资源URL
计算所得。
Antora 计算站点中每个可发布资源的资源 URL 。可发布资源是属于页面、图像和附件族的源文件。资源 URL 被计算为相对于站点路径名的绝对路径，以使其在应用程序中规范化。
资源 URL 以正斜杠(/)开头，并包含 Antora 从资源 ID 和 playbook 中的 URL 设置派生的段。这些段通常表示组件名称、版本、模块和资源文件名。
某些 playbook 键可以修改、添加或删除资源 URL 的部分。如果资源不是页面或者属于 ROOT 组件、未版本化组件版本或 ROOT 模块，则某些资源 URL 段将被添加或者去除。有关每个段和 Antora 从哪里提取其值的信息，请参阅 资源URL段。
Antora 将资源的计算资源 URL 分配给内部属性 pub.url ，其中 pub 是与发布相关的属性组的属性。
相对化的URL
计算所得。
Antora 将对资源的引用转换为相对 URL 。Antora 将此转换称为 relativize(相对化)。
relativize(相对化) 的发生取决于资源，可以是页面、图像、附件或 UI 资源。对于 Asciidoc 中的 xref 和图像，Antora 在 Asciidoctor 的扩展 HTML 转换器中内部地调用 relativize 。对于导航条目、面包屑、分页链接和页面版本选择器，UI 使用 relativize 助手将资源 URL 转换为相对于当前页面的相对 URL 。对于 UI 资源，UI 使用 uiRootPath 变量创建到资源的相对 URL。
Antora 创建相对 URL 链接资源有两个原因。首先，它将 URL 的长度尽可能缩短，以控制生成的 HTML 的大小。更重要的是，它确保 URL 在环境之间是可移植的。这是一个 Antora 站点可以直接从文件系统中查看的关键原因。相对引用不依赖于 Web 服务器来解析 URL 。相反，它们从当前页面开始，沿着文件系统向上向下走到目标资源，这在任何地方都有效。因此，它简化了发布流程，因为网站不会被绑定到特定的域或站点根目录上。
相对于域名URL
计算所得。
当为页面别名、组件版本起始页和最新版本段 redirect:to 和 replace 策略创建重写规则时，Antora 计算域相对 URL 。如果将非空值分配给站点路径名，Antora 将在资源 URL 前面添加站点路径名。当站点路径名为空时，资源 URL 已经等同于域相对 URL。例如，使用图4中的资源 URL 和站点路径名 /docs ，Antora 计算出图5中显示的域相对 URL 。
如果未设置 site.url 键，则 Antora 不计算域相对 URL ，并且需要它们的发布功能在运行时自动停用。
绝对URL
计算所得。
绝对 URL 是可发布资源的完整 URL 。为了计算绝对 URL , Antora 从一个绝对站点 URL 开始，并附加一个资源 URL 。例如，使用图2中的站点 URL 和图4中的资源 URL , Antora 计算出如图6所示的绝对 URL 。
图6是如何在浏览器地址栏或站点地图中显示页面 URL 的示例。在生成站点地图和计算每个页面头部元标签的规范 URL 时，Antora 会计算绝对 URL 。如果 site.url 键没有分配一个绝对的站点 URL ，需要绝对URLs的发布功能将在运行时自动停用。
资源URL段
下面几节描述资源 URL 的每个段，以及 Antora 从哪里提取每个段的值。发布页面的资源 url 段通常按照图7所示的顺序组织。
图像和附件的资源 url 分别包含一个额外的族段、图像或附件。族段跟随模块段，如图8所示。
组件段
URL 的组件段是发布的资源所属组件的名称。当资源属于特殊命名的 ROOT 组件时，该组件段将从 URL 中删除。在 antora.yml 文件中，组件名称由 name 键指定。
Antora 计算并分配给资源的 pub.url 属性的资源 URL 始终以此段开始。
版本段
URL 的版本段是已发布资源所属组件版本的实际版本或符号版本。实际版本是分配给组件版本 antora.yml 文件中的 version 键或在 playbook 中指定的内容源的 version 键的值。所有组件版本都有实际版本，尽管该版本可能被定义为未版本化。当组件版本未被版本化时，版本段从其资源的 URL 中删除。
符号版本是一个可选的配置设置，仅适用于资源属于组件的最新版本或最新预发布版本的情况下版本段。符号版本在 URL 中替换实际版本。可以使用 playbook 中的 latest_version_segment 键或 latest_prerelease_version_segment 键定义符号版本。符号版本不适用于未版本化的组件版本；版本段始终从其资源的已发布 URL 中删除。
族段
族段仅适用于图像和附件的资源 URL 。图像和附件的 URL 包括一个前缀为下划线（ _ ）的族段。对于图像，此段是 _images 。对于附件，此段是 _attachments 。页面的 URL 不包含家族段。