How Antora Builds URLs
Antora builds the URLs for publishable resources—pages, attachments, and images—using information from resource IDs, the site URL, and URL settings in the site’s playbook.
A site URL identifies the location where your site is published. A site URL is defined by assigning an allowable value to the site.url key in the playbook, --url command line option, or URL environment variable. There are two types of allowable site URLs: absolute and root-relative.
Antora is designed to generate sites that are viewable offline and from a local filesystem. For this reason, Antora doesn’t require a site URL to build a site. However, when Antora doesn’t detect an allowable site URL value, it automatically deactivates certain publishing features. See Features that depend on the site URL for a complete list of affected features.
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.
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.
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
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.
Antora generates and manages all URLs in your site. Antora builds the resource URLs for publishable resources as absolute paths relative to the site pathname. Then, the resource URLs are converted to URLs relative to the current page, the site URL (site-pathname/resource-URL), or absolute URLs (absolute-site-URL/resource-URL) depending on the context and feature in which the URL is used.
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 is the property group for properties that pertain to publishing.
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.
Antora computes domain-relative URLs when creating rewrite rules for page aliases, component version start pages, and the latest version segment
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.
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.
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.
site.url key isn’t assigned an absolute site URL, the publishing features that require absolute URLs are automatically deactivated at runtime.
The following sections describe each segment of a resource URL and from where Antora extracts the value of each segment. The segments of resource URLs for published pages are typically organized into the sequence shown in Figure 7.
The resource URLs for images and attachments contain an additional family segment,
The family segment follows the module segment as shown in Figure 8.
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.
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
For attachments, this segment is
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 (
The URLs of non-page resources use the file extension of their source files, regardless of the value assigned to