HTML Extension Styles

Antora allows you to customize the file extension used in the URL of HTML pages. By default, the URL will end with .html, mirroring the name of the the published file. If you want to “prettify” the URL by hiding the extension for SEO or other reasons, you can configure Antora to do so. You either have the option to drop the extension outright or to replace the extension with forward slash (a technique known as indexify). When using either of these options, Antora will also drop the last URL segment if the source page is named index.adoc. This page explains how to control this setting.

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.