On this page, you’ll learn:
How to configure the output directory.
How to configure multiple destinations and providers.
How to specify a custom provider.
When you only need to output the site to a single directory, you can use the output dir key. This key is meant to provide a shorthand to the more formal destinations key.
The output dir key specifies the directory where the generated site will be published. The key accepts a relative or absolute filesystem path. When the value is a relative path, the path is resolved relative to the playbook file.
The dir key overrides the path key of the first
The default output directory is build/site.
If no destinations are specified in the playbook, all site files will be written to this directory.
To disable this default, either specify at least one destination under the destinations key or set the destinations key to an empty array (
In the relative
dir example, the site will be published to a folder named launch relative to the playbook file.
output: dir: launch
In the absolute
dir example, the site will be published to home/dev/docs-site/beta regardless of where the playbook is located.
output: dir: /home/user/docs-site/beta
When you need to publish to multiple destinations, you’ll use the destinations key. The destinations key accepts a list of destination specifications. Each destination specification must include the provider key, which indicates which provider should be used to publish the site and which type of publication it will be.
Antora offers two built-in providers.
- Filesystem (
Publishes the output files to a directory.
- Archive (
Publishes the output files to a ZIP archive file.
You can also create custom providers for SSH, S3, etc.
fs provider publishes the site to a directory.
It’s the formal equivalent to specifying the dir key on output.
output: destinations: - provider: fs
In this example, the site is published to build/site.
archive provider publishes a site to a ZIP file.
output: destinations: - provider: archive
In this example, the site is generated as a ZIP file and published to build/site.zip.
The path key on a destination allows you to specify an output location per provider. The key accepts a relative or absolute filesystem path. When the value is a relative path, the path is resolved relative to the playbook file. The provider will create any interim directories as needed.
If you set the dir key in a playbook or via the CLI, its value will override the
In the relative path example, we’re running Antora on a playbook located in a directory named docs-site.
output: destinations: - provider: archive path: blue.zip
Once generation is complete, the site will be published to docs-site/blue.zip.
In the absolute path example, we can run Antora on a playbook located anywhere on our computer.
output: destinations: - provider: archive path: /home/user/projects/launch/blue.zip
Once generation is complete, the site will be published to /home/user/projects/launch/blue.zip.
In this example, we’re running Antora on a playbook file in the directory named tmp 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 published using the
fs provider to the directory tmp/releases/red.
This directory will be removed prior to publishing since we’ve turned the clean key on.
The site is also published as an archive to /home/user/projects/docs-site/blue.zip by the
If the provider key does not contain a recognized built-in provider, Antora will attempt to require it as a Node module. This allows you to supply a custom provider.
If the value begins with a dot (
.), Antora will require the path relative to the playbook file.
Otherwise, Antora will require the value as a Node module installed in the playbook project.
async function publish (destConfig, files, playbook)
The destConfig argument is an object containing key/value pairs that correspond to the properties of the destination specification. The files argument is a ReadableStream of virtual files. The playbook argument is the object containing key/value pairs from the playbook as a whole.
|The custom provider is an alpha API and subject to change.|