Add Static Files

A static UI file is any file provided by the UI that is added directly to your site. A common example of a static file is a favicon image. One way to add static files is by using the supplemental UI, which is defined in your Antora playbook. This document explains how to add static files using a UI bundle instead.

Set up the static files folder

You’ll first need a place to store the static files in the UI project. Let’s create a folder under src named static for this purpose.

$ mkdir src/static

You can add static files, such as a favicon image (e.g., favicon.ico), to this folder. The UI build will add files in this folder to the root of the UI bundle, dropping the static folder prefix from the path.

Antora automatically passes through static files in the bundle to the UI output folder (_ by default), ignoring any hidden files (i.e., files that begin with a dot). A static file is any file that’s not designated as a layout, partial, or helper. That means our favicon image file will end up at the path _/favicon.ico.

Contents of site

_/
  favicon.ico
  css/
    site.css
  ...
sitemap.xml
...

If that’s where you want the file to go, there’s nothing else you have to do. Otherwise, you have the option of promoting select static files to the site root.

Promote static files

If you want to promote certain static files out of the UI output folder, you need to identify them. Antora looks for a file named ui.yml, the UI descriptor, in the UI bundle to configure the behavior of the UI.

Start by creating the file src/ui.yml in your UI project. The UI build copies this file, if present, to the root of the UI bundle.

This file does not have any required keys. The key we’re interested in is static_files. This key identifies files by relative path in the UI bundle that should be promoted from the UI output folder to the site root. The files must be specified as an array, where each entry is either a relative paths or a path glob. Unlike other static files, promoted static files can begin with a dot.

Here’s how to configure the UI descriptor to promote the favicon image file to the site root.

src/ui.yml

static_files:
- favicon.ico

If you have multiple favicon files with different file extensions, you can match all of them using a glob.

src/ui.yml

static_files:
- favicon*

With this configuration in place, Antora will read the favicon image from the UI bundle and copy it to the root of the site.

Contents of site

_/
  css/
    site.css
  ...
favicon.ico
sitemap.xml
...

Let’s now look at how to put the static files to use.

Use the static files

Often when you add static files to your site, you need to reference them somewhere. In the case of a favicon image, it must be referenced in the <head> of the HTML page. If you are referencing a promoted static file, you’ll use the prefix {{{siteRootPath}}}. Otherwise, you’ll use the prefix {{{uiRootPath}}}.

Let’s update the src/partials/head-icons.hbs partial to reference the favicon image at the root of the site.

src/partials/head-icons.hbs

    <link rel="icon" href="{{{siteRootPath}}}/favicon.ico" type="image/x-icon">

Rebuild the UI with gulp bundle. You should now see that your site has a favicon image that’s provided by the UI bundle.