UI Configuration

On this page, you’ll learn:

  • How to specify the UI bundle you want to apply to your site.

  • How to set the default layout for pages.

  • How to select a specific UI theme from a bundle containing multiple UIs.

  • How to configure the output location for UI files.

The keys documented on this page are organized under the ui category in the playbook schema. These keys define the location of the UI and control how it should be processed.

UI bundle

The URL key (url) under the bundle subcategory defines the location Antora should look to find a UI archive in ZIP format (i.e., UI bundle). The key accepts a URL or a filesystem path.

Fetch and load a remote UI bundle

When the value of url is an actual URL, Antora downloads and caches the ZIP archive on the first run. On subsequent runs, Antora loads the bundle from the cache, if available. This saves Antora from having to download the bundle each time you generate your site.

Remote UI bundle
ui:
  bundle:
    url: https://repo.example.org/path/to/ui-bundle-1.0.0.zip

The value used in this example is the URL to Antora’s default UI.

The bundle is cached based on the signature of the URL. As long as the URL remains the same, and the snapshot key is not set to true, Antora continues to use the cached file. If you want to force Antora to download a snapshot UI bundle again, pass the --fetch option to the CLI. Another option is to remove the cached file.

Use a remote UI bundle snapshot

If the URL of the UI bundle does not change, but the archive it points to does change, you need to mark the bundle as a snapshot. This hint tells Antora to download the UI bundle again when the --fetch option is passed to the CLI. Otherwise, Antora assumes the URL is permanent and does not download it again as long as it exists in the cache.

Remote UI bundle marked as a snapshot
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

If you’re using the default UI bundle, you should mark it as a snapshot.

Load a UI bundle from the filesystem

If the UI bundle is available locally, it can be referenced using an absolute or relative filesystem path.

Relative UI bundle path
ui:
  bundle:
    url: ./../docs-ui/build/ui-bundle.zip

A relative path is automatically expanded to an absolute path using the following rules:

  • If the first path segment is ~, the path is resolved relative to the user’s home directory.

  • If the first path segment is ., the path is resolved relative to the location of the playbook file.

  • If the first path segment is ~+, or does not begin with an aforementioned prefix, the path is resolved relative to the current working directory.

Here’s the path to the same UI bundle, but using an absolute path instead.

Absolute UI bundle path
ui:
  bundle:
    url: /home/user/projects/docs-ui/build/ui-bundle.zip

Specify a UI start path

The start_path under the bundle subcategory is the relative path inside the bundle from where Antora should start reading files. This key is useful when you are using a bundle that packages multiple UIs, which might be the case if the UI provides multiple themes (e.g., light, dark, etc.).

Select UI from start_path
ui:
  bundle:
    url: /home/user/projects/docs-ui/build/ui-bundle-with-themes.zip
    start_path: dark

In this example, Antora will ignore all of the files in the UI bundle that fall outside the dark directory.

Apply a default page layout

A default page layout can be applied to all pages that don’t have a layout explicitly assigned in the page header (using the page-layout attribute). If not specified, this key defaults to the value default.

The default_layout accepts a value that’s the stem of a layout file (i.e., the name of the file without the file extension). The layout file is expected to be located under the layouts directory in the UI bundle.

For example, if you want to use the layout file article.hbs by default, set default_layout to article.

Default layout value
ui:
  bundle:
    url: ./../docs-ui/build/ui-bundle.zip
  default_layout: article

Default UI output directory

The UI files are published to a directory labeled with a single _ (underscore) located relative to the site’s output directory. For instance, when the site is published to the default destination directory (build/site), and no UI output_dir is specified, the UI files are written to build/site/_.

Use an alternate output directory

The output directory key (output_dir) allows you to specify an alternate directory where Antora should publish the UI files. The path is relative to the root of the published site.

Relative UI output path
ui:
  bundle:
    url: /home/user/projects/docs-ui/build/ui-bundle-with-themes.zip
    start_path: dark
  output_dir: _/dark

In this example, the site will be written to the default destination directory, therefore, the UI files will be published build/site/_/dark.

Antora will automatically reconfigure all references to UI files, regardless of what value you use. This is thanks in part to the use of the {{uiRootPath}} placeholder in the UI templates.

In the next example, the site’s output directory (dir) has been specified in addition to the UI output directory.

Custom site and UI output directories
ui:
  bundle:
    url: /home/user/projects/docs-ui/build/ui-bundle-with-themes.zip
    start_path: dark
  output_dir: _/dark
output:
  dir: ./public

The UI files will be published to public/_/dark.

In general, we recommend that you stick with the default output directory unless you have a good reason to change it.