url key for the site, defined under the site key in the playbook, is recommended.
If this key is not set, certain features of the site that relate to publishing will be disabled.
site: title: Site Title url: https://docs.example.com
url key defines the base URL of the published site.
The value may be an absolute URL (e.g., https://docs.example.com) with an optional path segment (aka pathname) (e.g., https://example.com/docs) or a root-relative path (e.g., /docs).
The value should not include a trailing forward slash unless the value itself is a forward slash.
An absolute URL value must start with a URL scheme directly followed by a colon and two forward slashes (e.g.,
Common schemes include https and file.
Absolute URLs may include a path segment (aka pathname) (e.g., https://example.com/docs).
site: title: Docs for Example Site url: https://example.com/docs
The site URL appears in the generated site wherever an absolute URL or root-relative path is required. When only a root-relative path is required, Antora extracts the pathname (e.g., /docs) from the absolute URL.
A root-relative URL value must start with a forward slash (e.g., /docs).
If you want to set
url to a root-relative URL, but want the pathname to be empty, set the value to a bare forward slash (i.e., /).
site: title: Docs Hosted Somewhere url: /docs
You might use a root-relative path instead of an absolute URL if the same content must be published to or accessible via multiple domains (aka hostnames). By using a root-relative value, you’re still able to take advantage of most of the benefits of assigning a site URL without coupling your site to a specific domain. However, any feature that depends on absolute URLs, such as the sitemap and canonical URL, must be implicitly disabled.
An Antora site is designed to be viewable offline and from a local filesystem. For this reason, the site URL is not required to build the site.
However, there are certain features related to publishing that require a URL, and in some cases an absolute URL. When the site URL is not set, these features are automatically and silently disabled.
When the site URL is set to any allowable value, the following features are enabled:
site-urlattribute is set on every AsciiDoc document.
site.urlproperty is set in the UI model (the value of the
site.urlkey in the playbook).
site.pathproperty is set in the UI model (the path segment extracted from the value of the
site.urlkey in the playbook; if the site URL does not have a path segment or the path segment is /, this value is empty)
The 404 page is generated.
The robots.txt file is generated if
site.robotsis also defined in the playbook.
Redirects include the path segment of the site URL (which is otherwise assumed to empty). This does not affect the static redirect facility, which uses relative URLs.
The link in the top-left corner of the navbar points to the site URL instead of a relative path (behavior specific to the default UI).
When the site URL is set to an absolute URL, the following additional features are enabled:
The sitemap files are generated.
page.canonicalUrlis set in the UI model, which gets used by the default UI to create the canonical link tag in the head.
If the site URL is not set, all the aforementioned features are disabled.
The path segment of the site URL represents the location from the root of the domain where the site managed by Antora is located. In other words, the site URL takes the visitor to the URL where the redirect for the site start page is located. If your site is published to a subfolder of your domain (e.g., https://example.com/path/to/docs), then the site URL should include this path (e.g., /path/to/docs) as well.
|The path segment of a URL is sometimes referred to as the pathname.|
Antora uses the path from the site URL to construct absolute and root-relative URLs to pages in your site. This includes URLs in the sitemap (absolute URLs) as well as rewrite rules (root-relative URLs).
Let’s consider an example of how the path segment is used when creating a server redirect rule. Assume the following conditions are true:
The site is published to the docs subfolder of the example.com domain.
The page new-page.adoc in the ROOT module of the versionless component-a component defines the page alias old-page.adoc (meaning old-page.adoc was renamed to new-page.adoc).
The redirect facility is set as
You’ve set the site
urlkey to https://example.com (the incorrect value) in your playbook.
When you run Antora, it will generate the following redirect rule:
/component-a/old-page.html /component-a/new-page.html 301!
Notice that the root-relative URLs in the redirect rule do not include the leading
That means if you visit https://example.com/docs/component-a/old-page.html, you will not be redirected to the new page, because the rule won’t match.
Let’s fix that.
Edit your playbook and set the site
url key to https://example.com/docs.
Now when you run Antora, it will generate the following redirect rule:
/docs/component-a/old-page.html /docs/component-a/new-page.html 301!
This time, the leading
/docs/ segment is present in the root-relative URLs.
Now when you visit https://example.com/docs/component-a/old-page.html, you will be redirected to the new page.