The Antora Zip Contents Extension augments the content aggregation capabilities of Antora. Using this extension you can import the contents of a remote or local zip file into the content aggregate.
|
Warning
|
This is ALPHA software! That means the extension is experimental and likely to change at any time without notice. You’re welcome to test it and give feedback, but take caution when relying on it in a production site. |
The Antora Zip Contents Collector extension enables you to import the contents of zip files into the content aggregate or content catalog to supplement files from the static, conventional content roots Antora has already loaded. Zip files can be loaded from a remote location or from the local disk.
Typically this extension is used to load supplemental content that is generated and published when a project is built, but isn’t directly committed into the git repository.
In order to use this extension, you must be using Node.js 20 and Antora 3.1.0. The following instructions assume you’ve already set up an Antora playbook file (i.e., antora-playbook.yml) to build your site.
To learn about using extensions with Antora, see the Antora extension documentation.
Use the following command to install the extension into your playbook project:
$ npm i @springio/antora-zip-contents-collector-extensionOpen your Antora playbook file and register the extension as an entry in the antora.extensions key.
If this key doesn’t yet exist in your playbook, first create it.
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'The collector operates on list of included zip files that are specified under the ext.zip-contents-collector key.
Includes listed under this key are combined with playbook configuration in order to build the full URL of this zip file.
For example, the following configuration will tells the collector to include extra and more:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include: [extra, more]The full URLs are defined by including locations in the extension configuration in the playbook file.
The URL must include a ${name} placeholder which will be expanded to the include name.
For example, the following configuration expands the includes we defined above to the urls https://example.com/extra.zip and https://example.com/more.zip
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
locations:
- url: https://example.com/${name}.zipThe contents of the zip are included per content root (aka origin), declared in the component descriptor. If the zip file contains (antora.yml) the root of the archive, that file is parsed and the data is overlaid onto the existing metadata of the current component version bucket in the content aggregate.
|
Note
|
Defining the URLs in the playbook file is more flexible than putting URLs directly in the antora.yml.
It allows you to change where zip files are hosted after the fact and allows local playbooks to consume zip files from different locations.
|
If you want to include zip contents in a specific destination you can use the module and path properties.
For example, we can update our include list of [extra, more] to an expanded form and provide additional destination properties:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include:
- name: extra
module: ROOT
path: pages
- name: more
module: my-module-a
path: examples/codeThe example above will include the contents of extra.zip under ROOT/pages and more.zip under my-module-a/examples/code.
Typically projects will have a different zip file for each version of the software that they release. For example, the zip file might contain API documentation that changes between v1.1 and v1.2 of a project.
In order to support version specific files, you can use ${version} anywhere in your URL.
The ${version} value is obtained by reading a specific file relative to the branch of the git repository being used for the origin.
Use version_file to specify the name of the file to load.
Currently version information can only be loaded from a gradle.properties file or a pom.xml files.
The following shows a version specific URL based of the value in a gradle.properties file:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
version_file: gradle.properties
locations:
- url: https://repo.example.com/com/example/myproject/my-project-docs/${version}/my-project-docs-${version}-${name}.zipSome projects use different artifact repositories for different version types.
If you need to specify a different URL based on the version type, you can use add a for_version_type key with one of the following values:
-
snapshot- Applies only when${version}ends in-SNAPSHOT -
milestone- Applies only when${version}ends in-M<N>(where<N>is a number) -
rc- Applies only when${version}ends in-RC[<N>](where<N>is a number) -
release- Applies only when${version}does not match any of the above
You may also specify a list if multiple version types are accepted.
The following shows how to configure a different repository for release artifacts:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
version_file: gradle.properties
locations:
- url: https://repo.example.com/preview/com/example/myproject/my-project-docs/${version}/my-project-docs-${version}-${name}.zip
for_version_type: [snapshot, milestone, rc]
- url: https://repo.example.com/release/com/example/myproject/my-project-docs/${version}/my-project-docs-${version}-${name}.zip
for_version_type: releaseIn addition to the name property you may also use a classifier property to help you build URLs.
Classifiers are common when publishing artifacts to a Maven repository.
You can declare classifier values in your antora.yml file then refer to them in your playbook URLs using ${classifier}.
Here’s a typical example:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include:
- name: my-project
- classifier: docs
- name: my-project
- classifier: apiantora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
version_file: gradle.properties
locations:
- url: https://repo.example.com/com/example/myproject/${name}/${version}/${name}-${version}-${classifier}.zipAdditional HTTP headers can be sent when downloading zip files by using http_headers configuration.
Configuration can be applied per location: or globally under extension configuration.
You can use ${env.<NAME>} to refer to environment variables that hold secret values.
The following will add an "Authorization" header to all remote requests:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
version_file: gradle.properties
http_headers:
- "Authorization: Bearer ${env.MY_SECRET_TOKEN}"
locations:
- url: https://repo.example.com/com/example/myproject/my-project-docs/${version}/my-project-docs-${version}-${name}.zipYou can also configure basic auth by using username and password configuration:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
version_file: gradle.properties
username: me
password: ${env.MY_SECRET_PASSWORD}"
locations:
- url: https://repo.example.com/com/example/myproject/my-project-docs/${version}/my-project-docs-${version}-${name}.zipIn addition to loading zip files from a remote location, you can also load local files or directories. This can be useful when running a build that uses a local Antora playbook.
Any url not starting with http: or https: is considered to be local and will be loaded from the source worktree.
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
locations:
- url: build/generated/my-project-docs-${name}.zip|
Note
|
Local locations can only be loaded from content sources the are also local. You cannot add content for a local zip file if you content source is a remote git repository. |
You can define more than one location in your antora playbook file if you to resolve zip files from multiple places. Locations are considered in the order that they are defined. The first location that successfully resolves the zip file will be used.
For example, the following configuration will try to download from a local location and fallback to downloading from example.com.
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
locations:
- url: build/generated/my-project-docs-${name}.zip
- url: https://repo.example.com/${name}.zipBy default zip content is added during the contentAggregated event, which occurs after the content has been aggregated and before the content is classified.
This allows the zip file to container .adoc files which will be merged into the aggregated and later converted to HTML.
It also allows additional antora.yml content to be merged.
If you have a zip that already contains HTML files or other assets that should be directly served, you can configure them to be added them during the contentClassified event.
A typical example would be adding API documentation (such as javadoc) where the HTML is generated by a different tool.
To specify that include should be merged during the contentClassified event you can set the destination to content_catalog:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include:
- name: api
destination: content_catalog|
Note
|
You must ensure that your antora.yml files has a valid version value after all aggregate zip contents has been merged.
|
In addition to the destination, you can also specify the module and path properties to merge content to a specific location:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include:
- name: api
destination: content_catalog
module: my-module
path: api/javaBy default, content will be added using a 'bare' page layout which is supported regardless of the UI bundle you use.
To specify a different page layout, you can use the layout attribute:
name: my-project
version: true
# ...
ext:
zip_contents_collector:
include:
- name: api
destination: content_catalog
layout: customIt’s sometimes useful to be able to specify included content from your Antora Playbook file rather than the antora.yml file.
Typically this is used in a local playbook file that’s part of a modular build.
To define includes in the playbook file you can use the always_include configuration key.
The syntax is the same as the include config specified in your antora.yml file.
For example:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
always_include:
- name: api
destination: content_catalog
module: my-module
path: api/javaBranches that refer to snapshot versions of zip files will encounter 404 errors if artifacts have not been published. This is commonly encountered when a version is bumped as the git commit needs to occur before CI can run and publish zip files.
In order to deal with this situation, the Antora Zip Contents Collector extension can drop content for snapshot versions if the content cannot be found.
To enable this feature, set on_missing_snapshot_zip to drop_content:
antora:
extensions:
- require: '@springio/antora-zip-contents-collector-extension'
on_missing_snapshot_zip: drop_contentContent will only be dropped when all of the following conditions are satisfied:
-
The content is being build from a branch and not a tag
-
The version number ends with
-SNAPSHOT -
The feature has been configured by setting
on_missing_snapshot_ziptodrop_content