Site URL

url key

The 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.

Example 1. antora-playbook.yml
site:
  title: Site Title
  url: https://docs.example.com

The 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.

Alternatively, the url key can be assigned from the CLI or using an environment variable.

Configure an absolute site URL

An absolute URL value must start with a URL scheme directly followed by a colon and two forward slashes (e.g., https://). Common schemes include https and file. Absolute URLs may include a path segment (aka pathname) (e.g., https://example.com/docs).

Example 2. antora-playbook.yml
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.

Configure a root-relative site 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., /).

Example 3. antora-playbook.yml
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.

When should the site URL be set?

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.

Features that depend on the site URL

When the site URL is set to any allowable value, the following features are enabled:

  • The site-url attribute is set on every AsciiDoc document.

  • The site.url property is set in the UI model (the value of the site.url key in the playbook).

  • The site.path property is set in the UI model (the path segment extracted from the value of the site.url key 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.robots is also defined in the playbook.

  • Redirects include the path segment of the site URL (which would otherwise be empty).

  • 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.

  • The page.canonicalUrl is 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.

When should the site URL include a path segment?

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 nginx.

  • You’ve set the site url key to https://example.com (the incorrect value) in your playbook.

When you run Antora, it will generate the following redirect rule:

Example 4. A redirect entry that does not includes a path segment
/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 /docs/ segment. 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:

Example 5. A redirect entry that does not includes a path segment
/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.

It’s important to include the path in the absolute site URL if your site is published to a subfolder of your domain. If you don’t want to tie your site to a specific domain, assign a root-relative site URL instead. Either way, the path segment should be present.