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.

Example 1. antora-playbook.yml 
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.

Example 2. Assign a relative path 
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.

Example 3. Assign an absolute path 
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.

Example 4. antora-playbook.yml 
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.

Example 5. Specify multiple providers 
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.