How Antora Builds URLs

An absolute site URL begins with https:// and is followed by the site domain or subdomain.

If you’re publishing your site to a subfolder, the site domain is followed by a subpath.

The subpath, also known as a path segment or pathname, represents the location from the root of the domain where the site managed by Antora is located. That is, if your site is published to a subfolder of your domain, then the absolute site URL should include this path. See Configure an absolute site URL and When should the site URL include a subpath? for more information about using an absolute site URL with a subpath.

A root-relative site URL begins with a forward slash (/) and, if more than one character, is the subpath.

See Configure a root-relative site URL for more information.

Computed.

The site pathname represents an internal property, site.path, that Antora uses when a publishing feature requires URLs that are relative to the root of your site. Antora computes the site pathname based on the site URL. The site pathname value is typically empty except when an absolute site URL contains a subpath or the site URL is a root-relative site URL. If site.url is an absolute site URL that contains a subpath, Antora extracts the subpath and uses it as the site pathname. For example, using the absolute site URL in Figure 2, Antora extracts the subpath, /docs, and assigns it to site.path. When the value assigned to site.url is a root-relative site URL, Antora extracts the entire value and uses it as the site pathname. Antora appends the resource URLs to the site pathname to create a domain-relative URLs when a feature, such as redirects, requires the computed URLs be relative to the site domain or site root.

Computed.

Antora computes a resource URL for each publishable resource in a site. A publishable resource is a source file that belongs to the pages, images, and attachments families. Resource URLs are computed as absolute paths relative to the site pathname so they are normalized across the application.

A resource URL begins with a forward slash (/) and contains segments that Antora derives from the ID of a resource and the URL settings in the playbook. These segments often represent the component name, version, module, and resource file name.

Certain playbook keys can modify, add, or remove portions of a resource URL. Some resource URL segments are added or absent if a resource isn’t a page or it belongs to a ROOT component, an unversioned component version, or a ROOT module. See Resource URL segments for information about each segment and from where Antora extracts their values.

Antora assigns the computed resource URL of a resource to the internal property, pub.url, where pub is the property group for properties that pertain to publishing.

Computed.

Antora converts the references to resources into relative URLs. Antora refers to this translation as relativize.

Where the relativize translation occurs depends on the resource, which can be a page, image, attachment, or UI resource. For xrefs and images in AsciiDoc, Antora calls relativize internally in the extended HTML converter for Asciidoctor. For navigation entries, breadcrumbs, pagination links, and the page version selector, the UI uses the relativize helper to convert a resource URL into a relative URL from the current page. For UI resources, the UI uses the uiRootPath variable to create a relative URL to the resource.

There are two reasons Antora creates relative URLs to link to resources. First, it keeps the length of the URL as short as possible to curb the size of the generated HTML. More importantly, it ensures that the URL is portable between environments. It’s a key reason why an Antora site works when viewed directly from the filesystem. The relative references don’t rely on a web server to resolve the URL. Instead, they start from the current page and walk up and down the filesystem to the target resource, which works everywhere. For the same reason, it simplifies publishing because the site is not bound to a given domain or site root.

Computed.

Antora computes domain-relative URLs when creating rewrite rules for page aliases, component version start pages, and the latest version segment redirect:to and replace strategies. If a non-empty value is assigned to the site pathname, Antora prepends the site pathname to the resource URL. When the site pathname is empty, a resource URL is already equivalent to the domain-relative URL. For example, using the resource URL in Figure 4, and the site pathname /docs, Antora computes the domain-relative URL shown in Figure 5.

If the site.url key isn’t set, Antora doesn’t compute domain-relative URLs and the publishing features that require them are automatically deactivated at runtime.

Computed.

An absolute URL is the full URL for a publishable resource. To compute an absolute URL, Antora starts with an absolute site URL and appends a resource URL. For example, using the site URL in Figure 2 and resource URL in Figure 4, Antora computes the absolute URL shown in Figure 6.

Figure 6 is an example of how a page’s URL is displayed in the browser address bar or in the sitemap. Antora computes absolute URLs when generating sitemaps and computing the canonical URL for the meta tag in the head of each page. If the site.url key isn’t assigned an absolute site URL, the publishing features that require absolute URLs are automatically deactivated at runtime.

The component segment of the URL is the name of the component the published resource belongs to. When the resource belongs to the specially named ROOT component, the component segment is dropped from the URL. A component name is specified by the name key in an antora.yml file.

The resource URL that Antora computes and assigns to the pub.url property of a resource always starts with this segment.

The version segment of a URL is the actual version or symbolic version of the component version the published resource belongs to. The actual version is the value assigned to the version key in a component version’s antora.yml file or to the version key for a content source that’s specified in the playbook. All component versions have an actual version, though that version may be defined as unversioned. When a component version is unversioned, the version segment is dropped from the URLs of its resources.

The symbolic version is an optional configuration setting that only applies to the version segment if the resource belongs to the latest version or latest prerelease version of a component. The symbolic version replaces the actual version in the URL. A symbolic version is defined using the latest_version_segment key or latest_prerelease_version_segment key in the playbook. The symbolic version doesn’t apply to component versions that are unversioned; the version segment is always dropped from their resources’ published URLs.

Antora derives the module segment from the module directory name where a resource’s source file is stored. When the resource belongs to the specially named ROOT module, the module segment is dropped from the URL. See Module Segment in Page URLs for examples and more information.

The family segment only applies to the resource URLs of images and attachments. Image and attachment URLs include a family segment that’s prepended with an underscore (_). For images, this segment is _images. For attachments, this segment is _attachments. The URLs for pages do not contain a family segment.

The relative path segment is derived from the family-relative path of the resource’s source file. For pages, the .adoc extension is dropped and replaced with .html or the specified HTML extension style. The URLs for other resources maintain the original file extension, such as .svg or .pdf.

The .html extension and html_extension_style key only applies to the URLs of pages. By default, Antora appends the .html extension to page URLs. The html_extension_style playbook key or --html-url-extension-style option modifies this behavior. The extension can be dropped (drop) or dropped and replaced with a forward slash (indexify).

The URLs of non-page resources use the file extension of their source files, regardless of the value assigned to html_extension_style.