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 end up in the UI bundle, they are not copied into the site’s output directory. In other words, they are not static files. Rather, 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 UI output directory (e.g., _) under the site output directory, preserving the relative path of the file in the UI bundle. When using the default UI, this list includes the css, font (generated), img, and js folders. Any files or folders that begin with a dot (i.e., hidden) are ignored unless configured otherwise.

Antora’s default UI already has several static folders. Let’s set up another folder and add some top-level static files as well.

First, create a folder under src named static for the purpose of demonstration:

Let’s now add a file to this new folder and three static files (one hidden) directly to the src folder. Here’s a file tree that shows the location of these new files:

Let’s now consider how the 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 and folders not shown here):

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

Notice the absence of the .DS_Store file, which is hidden. The font folder is introduced by the UI build.

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, the static files are placed into the UI output directory (e.g., _) in the published site by default. In this directory, we see the css, font, img and js folders, which are static folders provided by the default UI. We also see the static 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 are not static files.

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 static 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 static folder by adding the wildcard match the static_files key in the ui.yml file.

Using this configuration, the static folder will end up at the site root, adjacent to the favicon files, instead of inside the UI output directory. Notice that the static 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.