Add Static Files

Antora recognizes a number of non-publishable files and folders at the top level of a UI bundle. This list consists of the folders helpers, layouts, and partials and the optional ui.yml file. Although these files and folders are present in the UI bundle, they are not copied into the site’s output directory. In other words, they are not static files. Instead, they’re used to compose the HTML pages that are published or for configuration.

Any files or folders from the UI bundle that Antora does not recognize are classified as static. Static files and folders are automatically copied from the UI bundle to the site’s output directory underneath the UI output directory (e.g., _), preserving the relative path of the file from the UI bundle. Any files or folders that begin with a dot (i.e., hidden) are ignored unless explicitly listed as static files.

Antora’s default UI already has several intrinsic static folders. This list includes the css, font (generated), img, and js folders.

Although not used in the default UI, the UI build also recognizes another static folder named src/static. If the UI build finds any files inside this folder, including any files that are nested, it copies them directly to the root of the UI bundle, preserving any subfolders.

Let’s take advantage of this feature to add several new static files to the UI bundle. First, create a folder under src named static:

Let’s now add several files, including one that is hidden, to the src/static folder. Here’s a file tree that shows the location of these new files:

Let’s now consider how static files flow from the UI project to the published site. We’ll start with where these files reside within the UI project (non-static files not shown here):

The UI build will assemble the files into the UI bundle as follows:

When using this UI bundle in an Antora build, the contents of the output directory of your site will look like this:

As stated earlier, static files are copied to the UI output directory (e.g., _) in the published site by default. In this directory, we see the css, font, img and js folders, all static folders provided by the default UI. We also see the about folder and the favicon files we added to the UI project in the first step. We do not see the helpers, partials, and layouts folders since they’re not static files. We also don’t see the .DS_Store file since it’s a hidden file.

If the UI output directory is where you want static files to end up, there’s nothing else you have to do. If you want all or some of the static files to be moved to the site root, you need to add additional configuration to promote them.

If you want to promote certain static files to the root of your site, you need to identify them. You identify them using the ui.yml file. This file, called the UI descriptor, is used to configure the behavior of the UI. The UI descriptor must be located at the root of the UI bundle.

The UI descriptor has one required key, static_files, which is the one we’re interested in. The static_files key identifies files that should be promoted from the UI output directory to the site root (i.e., the site output directory). The files you want to promote must be specified as an array, where each entry is either an exact relative path or a glob of relative paths in the UI bundle. The exact path or path glob must match files, not folders. Unlike implicit static files, promoted static files can begin with a dot (and are thus not ignored).

To configure static files to promote, start by creating the file src/ui.yml in your UI project. If this file exists, the UI build will copy the file from there to the root of the UI bundle.

Next, add the static_files key to this file and add an entry for the favicon.ico file. This entry will configure the UI to promote the favicon to the site root.

If you have multiple favicon files with different suffixes or file extensions, you can match all of them using a wildcard (aka glob).

With this configuration in place, Antora will read the favicon images from the UI bundle and copy them to the root of the site. Static files that are not identified are still copied to UI output directory. The result of the above ui.yml would be the following:

Notice that the promoted favicon files are now at the site root rather than inside the UI output directory. However, the about folder is still inside the UI output directory. Let’s promote that one as well.

You can identify all files in a folder using the wildcard * in the last path segment, such as folder/*. You can identify all files in a folder at any depth using the wildcard ** in the last path segment, such as folder/**. Matching a folder has no effect (e.g., folder). Wildcards never match hidden files. Hidden files must always be written using an exact path match.

Let’s also promote all files in the about folder by adding the wildcard match the static_files key in the ui.yml file.

Using this configuration, the about folder will end up at the site root, adjacent to the favicon files, instead of inside the UI output directory. Notice that the about folder is copied too, not just its contents.

Now that the static files are where you want them, let’s look at how to reference them from the HTML pages.

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 a promoted favicon image at the root of the site.

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