mirror of
https://github.com/boostorg/unordered-ui-bundle.git
synced 2026-01-19 04:42:15 +00:00
clarify how Antora identifies static files in the UI bundle and where it copies them
This commit is contained in:
Robert Bennett
committed by
Dan Allen
Dan Allen
parent
4e64faffd3
commit
394e10deb2
@@ -1,53 +1,138 @@
|
||||
= Add Static Files
|
||||
|
||||
A static UI file is any file provided by the UI that is added directly to your site.
|
||||
A static UI file is any file provided by the UI that's copied 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 xref:antora:playbook:ui-supplemental-files.adoc[supplemental UI], which is defined in your Antora playbook.
|
||||
This document explains how to add static files using a UI bundle instead.
|
||||
One way to add additional static files is by using the xref:antora:playbook:ui-supplemental-files.adoc[supplemental UI], which is defined in your Antora playbook.
|
||||
This document explains how to add static files from the UI bundle instead.
|
||||
A key benefit of putting static files in the UI bundle is that they can be shared across multiple projects instead of having to add them per project using the supplemental UI.
|
||||
|
||||
== Set up the static files folder
|
||||
== How Antora identifies static UI files
|
||||
|
||||
You'll first need a place to store the static files in the UI project.
|
||||
Let's create a folder under [.path]_src_ named [.path]_static_ for this purpose.
|
||||
Antora recognizes a number of non-publishable files and folders at the top level of a UI bundle.
|
||||
This list consists of the folders [.path]_helpers_, [.path]_layouts_, and [.path]_partials_ and the optional [.path]_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., [.path]_++_++_) 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 [.path]_css_, [.path]_font_ (generated), [.path]_img_, and [.path]_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 [.path]_src_ named [.path]_static_ for the purpose of demonstration:
|
||||
|
||||
$ mkdir src/static
|
||||
|
||||
You can add static files, such as a favicon image (e.g., [.path]_favicon.ico_), to this folder.
|
||||
The UI build will add files in this folder to the root of the UI bundle, dropping the [.path]_static_ folder prefix from the path.
|
||||
Let's now add a file to this new folder and three static files (one hidden) directly to the [.path]_src_ folder.
|
||||
Here's a file tree that shows the location of these new files:
|
||||
|
||||
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 [.path]_++_/favicon.ico++_.
|
||||
....
|
||||
src/
|
||||
static/
|
||||
notice.txt
|
||||
.DS_Store
|
||||
favicon.ico
|
||||
favicon.png
|
||||
....
|
||||
|
||||
.Contents of site
|
||||
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):
|
||||
|
||||
.UI project
|
||||
....
|
||||
src/
|
||||
css/
|
||||
...
|
||||
img/
|
||||
back.svg
|
||||
...
|
||||
js/
|
||||
...
|
||||
static/
|
||||
notice.txt
|
||||
.DS_Store
|
||||
favicon.ico
|
||||
favicon.png
|
||||
....
|
||||
|
||||
The UI build will assemble the non-hidden files into the UI bundle as follows:
|
||||
|
||||
.Contents of UI bundle
|
||||
....
|
||||
css/
|
||||
site.css
|
||||
font/
|
||||
roboto-latin-400-italic.woff
|
||||
...
|
||||
img/
|
||||
back.svg
|
||||
...
|
||||
js/
|
||||
site.js
|
||||
static/
|
||||
notice.txt
|
||||
favicon.ico
|
||||
favicon.png
|
||||
....
|
||||
|
||||
Notice the absence of the [.path]_.DS_Store_ file, which is hidden.
|
||||
The [.path]_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:
|
||||
|
||||
.Contents of site output directory
|
||||
....
|
||||
_/
|
||||
favicon.ico
|
||||
css/
|
||||
site.css
|
||||
font/
|
||||
roboto-latin-400-italic.woff
|
||||
...
|
||||
img/
|
||||
back.svg
|
||||
...
|
||||
js/
|
||||
site.js
|
||||
static/
|
||||
about.txt
|
||||
favicon.ico
|
||||
favicon.png
|
||||
component-a/
|
||||
...
|
||||
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.
|
||||
As stated earlier, the static files are placed into the UI output directory (e.g., [.path]_++_++_) in the published site by default.
|
||||
In this directory, we see the [.path]_css_, [.path]_font_, [.path]_img_ and [.path]_js_ folders, which are static folders provided by the default UI.
|
||||
We also see the [.path]_static_ folder and the favicon files we added to the UI project in the first step.
|
||||
We do not see the [.path]_helpers_, [.path]_partials_, and [.path]_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.
|
||||
|
||||
== 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 [.path]_ui.yml_, the UI descriptor, in the UI bundle to configure the behavior of the UI.
|
||||
If you want to promote certain static files to the root of your site, you need to identify them.
|
||||
You identify them using the [.path]_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.
|
||||
|
||||
Start by creating the file [.path]_src/ui.yml_ in your UI project.
|
||||
The UI build copies this file, if present, to 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).
|
||||
|
||||
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.
|
||||
To configure static files to promote, start by creating the file [.path]_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.
|
||||
|
||||
Here's how to configure the UI descriptor to promote the favicon image file to the site root.
|
||||
Next, add the `static_files` key to this file and add an entry for the [.path]_favicon.ico_ file.
|
||||
This entry will configure the UI to promote the favicon to the site root.
|
||||
|
||||
.src/ui.yml
|
||||
[,yaml]
|
||||
@@ -56,7 +141,7 @@ static_files:
|
||||
- favicon.ico
|
||||
----
|
||||
|
||||
If you have multiple favicon files with different file extensions, you can match all of them using a glob.
|
||||
If you have multiple favicon files with different suffixes or file extensions, you can match all of them using a wildcard (aka glob).
|
||||
|
||||
.src/ui.yml
|
||||
[,yaml]
|
||||
@@ -65,20 +150,56 @@ 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.
|
||||
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 [.path]_ui.yml_ would be the following:
|
||||
|
||||
.Contents of site
|
||||
.Contents of site output directory
|
||||
....
|
||||
_/
|
||||
css/
|
||||
site.css
|
||||
...
|
||||
font/
|
||||
roboto-latin-400-italic.woff
|
||||
...
|
||||
img/
|
||||
back.svg
|
||||
...
|
||||
js/
|
||||
site.js
|
||||
static/
|
||||
about.txt
|
||||
component-a/
|
||||
favicon.ico
|
||||
favicon.png
|
||||
...
|
||||
sitemap.xml
|
||||
...
|
||||
....
|
||||
|
||||
Let's now look at how to put the static files to use.
|
||||
Notice that the promoted favicon files are now at the site root rather than inside the UI output directory.
|
||||
However, the [.path]_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 [.path]_static_ folder by adding the wildcard match the `static_files` key in the [.path]_ui.yml_ file.
|
||||
|
||||
.src/ui.yml
|
||||
....
|
||||
static_files:
|
||||
- favicon*
|
||||
- static/*
|
||||
....
|
||||
|
||||
Using this configuration, the [.path]_static_ folder will end up at the site root, adjacent to the favicon files, instead of inside the UI output directory.
|
||||
Notice that the [.path]_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.
|
||||
|
||||
== Use the static files
|
||||
|
||||
@@ -87,12 +208,12 @@ In the case of a favicon image, it must be referenced in the `<head>` of the HTM
|
||||
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 [.path]_src/partials/head-icons.hbs_ partial to reference the favicon image at the root of the site.
|
||||
Let's update the [.path]_src/partials/head-icons.hbs_ partial to reference a promoted favicon image at the root of the site.
|
||||
|
||||
.src/partials/head-icons.hbs
|
||||
[,yaml]
|
||||
[,yaml,indent=4]
|
||||
----
|
||||
<link rel="icon" href="{{{siteRootPath}}}/favicon.ico" type="image/x-icon">
|
||||
<link rel="icon" href="{{{siteRootPath}}}/favicon.ico" type="image/x-icon">
|
||||
----
|
||||
|
||||
Rebuild the UI with `gulp bundle`.
|
||||
|
||||
Reference in New Issue
Block a user