Collector Use Cases

This page presents realistic use cases that can be accomplished using Collector. Each section introduces a different use case and presents the configuration and commands you can use as a starting point.

Import example code

You can use Collector to import files that are stored outside the content source root so they can be included in pages in the site.

Let’s assume that the branch of our content repository has the following structure:

pom.xml
docs/
  antora.yml
  modules/
    ROOT/
      pages/
        index.adoc
src/
  test/
    java/
      org/
        example/
          HelloWorld.java

To include the file HelloWorld.java into the page index.adoc, you’re instinct may be to use a relative path reference.

include::../../../../src/test/java/org/example/HelloWorld.java[]

However, Antora does not permit references to files that are stored outside of a content source root (as these files are outside of Antora’s virtual file system). Instead, we can use Collector to import those files into Antora’s content catalog so they can be referenced.

Here’s the configuration to add to antora.yml to set this up:

ext:
  collector:
    scan:
      dir: src/test/java
      into: modules/ROOT/examples

This configuration imports all the files under src/test/java into the modules/ROOT/examples virtual path in the component version bucket. (You can use the files key to filter the files that are matched). The result is that these files will be classified into the example family of the ROOT module.

Now you can include the HelloWorld.java file as follows:

include::example$org/example/HelloWorld.java[]

Collector has effectively copied the files from src/test/java into docs/modules/ROOT/examples at runtime without having to physically copy them.

Generate API docs as attachments

You may want to embed API docs into your Antora-generated site. The challenge is that since API docs are generated from the code, you don’t want to have to commit these files to repository. Collector can offer to generate the files from the code that’s in the same branch as the content while Antora is running and import them as attachments. This works even when the content repository is remote since Collector has the ability to checkout each git reference into a worktree if necessary.

Let’s assume that the branch of our content source repository has the following structure:

pom.xml
docs/
  antora.yml
  modules/
    ROOT/
      pages/
        index.adoc
src/
  main/
    java/
      com/
        acme/
          Application.java

We’ll also assume that we can build the API docs (in this case Javadoc) using the command mvn javadoc:javadoc.

Here’s the configuration to add to antora.yml to set this up:

ext:
  collector:
    run: mvn javadoc:javadoc
    scan:
      clean: true (1)
      dir: target/apidocs
      into: modules/api/attachments

1	Instructs Collector to clean the scan directory before running the command.

This Collector instance first runs the mvn javadoc:javadoc command (making the assumption that the mvn command is available on the current user’s PATH). It that scans for and imports all the files under the generated target/apidocs directory into the modules/api/attachments virtual path in the component version bucket. The result is that these files will be classified into the attachment family of the api module.

We can now link the reader to the API docs using the following xref:

Consult the xref:api:attachment$index.html[API].

This workflow can be done for all sorts of API docs.