HTML Extension Styles

html_extension_style key

The html_extension_style key is optional. It’s configured under the urls key in a playbook.

Example 1. antora-playbook.yml

urls:
  html_extension_style: indexify

It accepts the following built-in values:

default: Published page URLs are displayed with the .html extension, i.e., https://base-url.com/component/version/module/my-file.html. Antora automatically applies this style when html_extension_style isn’t set in the playbook or via the CLI.
drop: The .html extension is dropped from the end of the published page URLs, i.e., https://base-url.com/component/version/module/my-file.
indexify: The .html extension is dropped and a forward slash (/) is appended to the end of the published page URLs, i.e., https://base-url.com/component/version/module/my-file/.

Using the default style

Antora will automatically assign the value default to the html_extension_style key at runtime if it isn’t set in the playbook or in the CLI using the --html-url-extension-style option. The default style appends the .html extension to the end of every published page’s URL. For example, the resulting URL for the page my-file.adoc would be displayed in a browser with .html appended to the end, i.e., https://base-url.com/component/version/module/my-file.html.

Apply the indexify style

Let’s assign indexify to the html_extension_style key.

Example 2. antora-playbook.yml

site:
  title: Site Title
  url: https://example.org
urls:
  html-extension-style: indexify

When indexify is applied, the site’s published URLs don’t end with the extension .html. Instead, a forward slash (/) is appended directly to the end of the page stem. This results in the URL for the page my-file.adoc to be displayed in a browser as https://example.com/component/version/module/my-file/.

To locally preview all the features of a site, such as redirects and the 404 page, when html_extension_style is assigned indexify, you’ll need to run a local server.

Apply the drop style

Let’s assign drop to the html_extension_style key.

Example 3. antora-playbook.yml

site:
  title: Site Title
  url: https://example.org
urls:
  html-extension-style: drop

When drop is applied, the site’s published URLs don’t end with the extension .html. This results in the URL for the page my-file.adoc to be displayed in a browser as https://example.com/component/version/module/my-file.

To locally preview all the features of a site, such as redirects and the 404 page, when the style is drop, you’ll need to run a local server.