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 a more formal equivalent to specifying the output directory using the dir key.

Example 1. antora-playbook.yml

output:
  dir: ./public (1)
  destinations: (2)
  - provider: fs (3)

1	The value used as the `path` key for the primary fs destination; defaults to ./build/site.
2	The `provider` key must be configured under the `destinations` key.
3	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`.

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 the path key is not specified on the fs destination, the default value will be used. The first occurrence inherits the value from the ancestor dir key. Otherwise, the default path for the fs provider is used, which is ./build/site. When the output directory is specified from the CLI using the --to-dir option, it works the same way.

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.

Relationship to output dir

The dir key under the output category key provides a convenient way to specify an fs destination. However, it’s relationship to the destinations array can be tricky to understand.

For the first destination whose provider is set to fs and whose path key is not specified, the dir key controls the value of that destination’s path key.

Example 5. antora-playbook.yml

output:
  dir: ./public
  destinations:
  - provider: fs

This allows the path for this destination to be controlled from the CLI using the --to-dir option.

If destinations is empty, or if all fs destinations specify a path key, then the dir key is effectively ignored.

Example 6. antora-playbook.yml

output:
  dir: ./ignored
  destinations:
  - provider: fs
    path: ./build/site-copy

The way to think of it is that the output dir fills in the missing path key for the first occurrence of an fs destination that does not specify a path.

If you want to output to both ./build/site and ./build/site-copy, you need a slot for the output dir.

Example 7. antora-playbook.yml

output:
  dir: ./build/site
  destinations:
  - provider: fs
  - provider: fs
    path: ./build/site-copy

Publish to multiple destinations

In Example 8, Antora is running on a playbook file in the tmp directory and publishing the site to two locations, one relative and one absolute.

Example 8. 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.