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 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.
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/. This is the preferred style if you don’t want the .html extension to appear in URLs.
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. This style requires support from the web server and should only be used if you’re comfortable applying the necessary web server configuration.

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. In order for the site to work properly when using this style, you must view the site through a web server. You also need to configure the web server to look for a file with the .html extension.

Not all web servers have the ability to support extensionless HTML URLs.

If you’re using nginx, you need to add the following directive to the location / stanza in the configuration for your host:

location / {
  # ...
  try_files $uri $uri.html $uri/index.html = 404;
}

This directive tells nginx to first look for the requested file, then look for the same file with the .html extension added, then look for a file named index.html in a directory that matches the requested file. These attempts match the layout of the published files.