Antora Maven Content Source Extension

This extension allows Antora to retrieve content from maven coordinates in addition to git repositories. If parts of the documentation are generated or post-processed it's usually more convenient to package and publish the docs to a maven repository instead of making the build commit generated files into a git repo. Also, it's probably more common for Java hackers to refer to published artifacts than to git repos.

This extension recommends maven artifacts to be versioned according to SemVer

The extension has been tested with Antora 3.0.1 up to 3.1.9.

Usage

Publish an artifact (zip, jar and tgz supported) to a maven repository. Make sure the archive content adheres to the antora folder structure (somewhere, since start paths are supported, too).

Make sure it's available for antora (i.e. installed globally or along the playbook):

npm i @kiwigrid/antora-maven-content

Then add the extension to the playbook:

antora:
  extensions:
    - require: "@kiwigrid/antora-maven-content"
      mavenSettings: true                  # defaults to false, true resolves to '$HOME/.m2/settings.xml' or '$M2_HOME/conf/settings.xml', a string is taken as is
      repositories: # optional
        - baseUrl: https://www.example.com # required for a repo
          fetchOptions: # optional
            headers:
              "Authorization": "Basic <base64 encoded user:password>"
      sources:
        - groupId: "com.example"      # required
          artifactId: "antora-module" # required
          version: "1.x.x"            # defaults to '*'
          versionScheme: "SemVer"     # defaults to 'SemVer' 
          limit: 4                    # defaults to 1
          limitBy: minor              # defaults to 'major', one of 'major', 'minor', 'patch', 'any'
          includeSnapshots: true      # defaults to false, true has no effect if includePrerelease is false as SNAPSHOTS are SemVer pre releases
          includePrerelease: true     # defaults to true
          classifier: ""              # defaults to 'docs'
          extension: "tgz"            # defaults to 'zip'
          startPath: ~                # defaults to null
          startPaths: "docs/*"        # defaults to null
          edit_url: "https://git.example.com/repos/myRepo/browse/{path}" # defaults to false
# ...

With above example configuration the extension is going to download all available versions for com.example:antora-module and picks the 3 highest versions which:

• match the SemVer Range 1.x.x

• do not equal an already picked version when reduced to the minor version

• for example:

  | Available Versions | Decision | |--------------------|--------------------------------------------| | 2.0.0 | ✖ does not match 1.x.x | | 1.2.1 | ✅ | | 1.2.0 | ✖ equals 1.2.1 when reduced to minor (1.2) | | 1.1.0 | ✅ | | 1.0.2 | ✅ | | 1.0.1 | ✖ equals 1.0.2 when reduced to minor (1.0) | | 1.0.0 | ✖ equals 1.0.2 when reduced to minor (1.0) | | 0.9.2 | ✖ does not match 1.x.x | | 0.9.1 | ✖ does not match 1.x.x | | 0.9.0 | ✖ does not match 1.x.x |

So the configuration basically picks the most recent patch versions of the four highest minor releases of major version 1. For each picked version a corresponding playbook content source entry is created which:

• points to a local transient cached on-demand git repository the artifact has been extracted to
• is configured with the same start path(s)
• is configured with an edit url

Note the Antora component version is totally unrelated to the maven artifact version and will be read by Antora from the component descriptor file antora.yml contained in the artifact archive.

Supported Versioning Schemes

| Scheme | Structure | version format | notes | |------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | SemVer | <major>.<minor>.<patch>+<metadata>-<prerelease> | any valid SemVer Range | recommended | | OSGI | <major>.<minor>.<micro>.<qualifier> | any valid OSGI range | micro is exposed as patch, there is no order between qualifiers | | Lexicographically | any | any valid regular expression | minor and patch are always 0, the complete version is the major part |

Maven settings.xml

If mavenSettings is given a maven settings.xml is parsed for repositories and authentication data. The value of the option can be true to use $HOME/.m2/settings.xml or $M2_HOME/conf/settings.xml or a string pointing to a settings file. Only repositories of profiles which are active by default are extracted, mirrors are properly resolved.

Contributions

Are welcome!