Filesystem Provider
In order to publish a site to multiple destinations, including one or more filesystem destinations, your playbook must set the output
, destinations
and provider
keys.
fs provider
The provider
value fs
publishes the site to a directory on a filesystem. It’s the formal equivalent to specifying the output directory using the dir
key.
output:
destinations: (1)
- provider: fs (2)
1 | The provider key must be configured under the destinations key. |
2 | Under destinations , type a hyphen (- ) and a blank space, then the key name provider , followed by a colon (: ). After the colon, enter a blank space, and then the built-in value name fs . |
Unless the path
key or dir key is specified, the default path for the fs
provider is build/site.
path key
The optional path
key designates the target location where the output files are to be written. The fs
provider treats this value as a target directory.
The path
key accepts a relative or absolute filesystem path. The provider will create any interim directories as needed. A relative path is expanded to an absolute path using the following rules:
-
If the first path segment is a tilde (
~
), the remaining path is resolved relative to the user’s home directory. -
If the first path segment is a dot (
.
), the remaining path is resolved relative to the location of the playbook file. -
If the first path segment is a tilde directly followed by a plus sign (
~+
), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.
If path
isn’t specified, it gets populated with the default value, build/site, or, in the case of the first fs
provider, the value of dir
. When the dir key is specified, its value is assigned to (or overrides) the first fs
provider path
. When the output directory is specified from the CLI using the --to-dir option, it also overrides the first fs
provider path
(as well as dir
) in a playbook.
Specify a relative path
In Example 2, the site will be published to a folder named launch relative to the playbook file.
output:
destinations:
- provider: fs
path: ./launch
Specify an absolute path
In Example 3, the site will be published to home/dev/site/beta, regardless of where the playbook is located.
output:
destinations:
- provider: fs
path: /home/dev/site/beta
clean key
The clean
key is optional and is deactivated (assigned the value false
) by default. It can be applied as part of an fs
provider configuration instead of directly under the output key.
output:
destinations:
- provider: fs
path: /home/dev/site/beta
clean: true (1)
1 | clean is activated with the value true and deactivated with false . |
When clean
is assigned the value true
, it removes the destination path
recursively before generating the site. This key only applies to the fs
provider.
Use this key with great care. For example, if you set path to your home directory and clean to true , you’ll delete ALL of the folders and files in home. |
Publish to multiple destinations
In Example 5, Antora is running on a playbook file in the tmp directory and publishing the site to two locations, one relative and one absolute.
output:
destinations:
- provider: fs
path: ./releases/red
clean: true
- provider: archive
path: /home/user/projects/docs-site/blue.zip
The site files published using the fs
are written to the directory tmp/releases/red. This directory will be removed prior to publishing since the clean
key is assigned true
. The site is also published as an archive to /home/user/projects/docs-site/blue.zip by the archive
provider.