Antora如何构建URL

绝对站点URL以https://开头，后跟站点域或子域。

如果您将站点发布到子文件夹，则站点域后面跟着子路径。

子路径，也称为路径段或路径名，表示Antora管理的站点位于域的根目录的位置。也就是说，如果您的站点发布到域的子文件夹，则绝对站点URL应包含此路径。有关使用带有子路径的绝对站点URL的更多信息，请参阅配置绝对站点URL和站点URL何时应包含子路径？。

根相对站点URL以斜杠（/）开头，如果超过一个字符，则是子路径。

有关更多信息，请参阅配置根相对站点URL。

计算。

站点路径名表示Antora在发布功能需要相对于站点根目录的URL时使用的内部属性site.path。Antora根据站点URL计算站点路径名。站点路径名的值通常为空，除非绝对站点URL包含子路径或站点URL是根相对站点URL。如果site.url是包含子路径的绝对站点URL，Antora会提取子路径并将其用作站点路径名。例如，在图2中使用绝对站点URL，Antora提取子路径/docs并将其分配给site.path。当分配给site.url的值是根相对站点URL时，Antora提取整个值并将其用作站点路径名。当功能（例如重定向）要求计算的URL相对于站点域或站点根时，Antora将资源URL附加到站点路径名以创建域相对URL。

计算。

Antora为站点中的每个可发布资源计算资源URL。可发布资源是属于页面、图片和附件系列的源文件。资源URL被计算为相对于站点路径名的绝对路径，以便在整个应用程序中进行标准化。

资源URL以斜杠（/）开头，并包含Antora从资源的ID和playbook中的URL设置派生的段。这些段通常代表组件名称、版本、模块和资源文件名。

某些playbook键可以修改、添加或删除资源URL的部分。如果资源不是页面或属于ROOT组件、未版本化的组件版本或ROOT模块，则会添加或删除一些资源URL段。有关每个段以及Antora从何处提取其值的信息，请参阅资源URL段。

Antora将资源的计算资源URL分配给内部属性pub.url，其中pub是与发布相关的属性组。

计算。

Antora将对资源的引用转换为相对URL。Antora将此转换称为相对化。

相对化转换发生的位置取决于资源，可以是页面、图片、附件或UI资源。对于AsciiDoc中的交叉引用和图片，Antora在Asciidoctor的扩展HTML转换器中内部调用相对化。对于导航条目、面包屑、分页链接和页面版本选择器，UI使用相对化助手将资源URL转换为相对于当前页面的URL。对于UI资源，UI使用uiRootPath变量创建到资源的相对URL。

Antora创建相对URL以链接到资源有两个原因。首先，它尽可能保持URL的长度短，以限制生成的HTML的大小。更重要的是，它确保URL在不同环境之间是可移植的。这是Antora站点在直接从文件系统查看时正常工作的关键原因。相对引用不依赖于Web服务器来解析URL。相反，它们从当前页面开始，沿着文件系统向上下移动到目标资源，这在任何地方都有效。出于同样的原因，它简化了发布，因为站点不受特定域或站点根目录的限制。

计算。

Antora在为页面别名、组件版本起始页面和最新版本段redirect:to和replace策略创建重写规则时计算域相对URL。如果为站点路径名分配了非空值，Antora会将站点路径名前置到资源URL。当站点路径名为空时，资源URL已经等同于域相对URL。例如，使用图 4中的资源URL和站点路径名/docs，Antora计算出图 5中显示的域相对URL。

如果未设置site.url键，Antora不会计算域相对URL，并且在运行时会自动停用需要它们的发布功能。

计算。

绝对URL是可发布资源的完整URL。为了计算绝对URL，Antora从绝对站点URL开始，并附加资源URL。例如，使用图 2中的站点URL和图 4中的资源URL，Antora计算出图 6中显示的绝对URL。

图 6是页面URL在浏览器地址栏或站点地图中显示的示例。Antora在生成站点地图和计算每个页面头部的meta标签的canonical URL时计算绝对URL。如果未为site.url键分配绝对站点URL，则需要绝对URL的发布功能会在运行时自动停用。

URL的组件段是已发布资源所属的组件的名称。当资源属于特别命名的ROOT组件时，组件段将从URL中删除。组件名称由antora.yml文件中的name key指定。

Antora计算并分配给资源的pub.url属性的资源URL始终以此段开头。

URL的版本段是已发布资源所属的组件版本的实际版本或符号版本。实际版本是分配给组件版本的antora.yml文件中的version key或在playbook中指定的内容源的version键的值。所有组件版本都有一个实际版本，尽管该版本可能被定义为无版本。当组件版本为无版本时，版本段将从其资源的URL中删除。

符号版本是一个可选的配置设置，仅适用于资源属于组件的最新版本或最新预发布版本的版本段。符号版本将替换URL中的实际版本。使用playbook中的latest_version_segment键或latest_prerelease_version_segment键定义符号版本。符号版本不适用于无版本的组件版本；其资源的已发布URL始终删除版本段。

Antora从存储资源源文件的模块目录名称派生模块段。当资源属于特别命名的ROOT模块时，模块段将从URL中删除。有关示例和更多信息，请参阅页面URL中的模块段。

family段仅适用于图像和附件的资源URL。图像和附件的URL包括一个以下划线（_）开头的family段。对于图像，此段为_images。对于附件，此段为_attachments。页面的URL不包含family段。

相对路径段是从资源源文件的family-relative路径派生的。对于页面，.adoc扩展名将被删除，并替换为.html或指定的HTML扩展样式。其他资源的URL保留原始文件扩展名，如.svg或.pdf。

.html扩展名和html_extension_style键仅适用于页面的URL。默认情况下，Antora将.html扩展名附加到页面URL。playbook中的html_extension_style键或--html-url-extension-style选项可以修改此行为。扩展名可以被删除（drop）或删除并替换为斜杠（indexify）。

非页面资源的URL使用其源文件的文件扩展名，而不管html_extension_style的值。