Usage

Run Javadoc with the org.asciidoctor.Asciidoclet doclet class. Some examples for common build systems are shown below. See Doclet Options for supported options.

Maven

Asciidoclet may be used via a maven-javadoc-plugin doclet:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <configuration>
        <source>1.7</source>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>${asciidoclet.version}</version>
        </docletArtifact>
        <overview>src/main/java/overview.adoc</overview>
        <additionalparam>
          --base-dir ${project.basedir}
          --attribute "name=${project.name}"
          --attribute "version=${project.version}"
          --attribute "title-link=https://example.com[${project.name} ${project.version}]"
        </additionalparam>
    </configuration>
</plugin>

Gradle

Asciidoclet may be used via a doclet in the Javadoc task:

configurations {
    asciidoclet
}

dependencies {
    asciidoclet 'org.asciidoctor:asciidoclet:1.+'
}

javadoc {
    options.docletpath = configurations.asciidoclet.files.asType(List)
    options.doclet = 'org.asciidoctor.Asciidoclet'
    options.overview = "src/main/java/overview.adoc"
    options.addStringOption "-base-dir", "${projectDir}" (1)
    options.addStringOption "-attribute", (2)
            "name=${project.name}," +
            "version=${project.version}," +
            "title-link=https://example.com[${project.name} ${project.version}]")
}

1	Option names passed to Gradle’s `javadoc` task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options.
2	Gradle’s `javadoc` task does not allow multiple occurrences of the same option. Multiple attributes can be specified in a single string, separated by commas.

Ant

Asciidoclet may be used via a doclet element in Ant’s javadoc task:

<javadoc destdir="target/javadoc"
         sourcepath="src"
         overview="src/overview.adoc">
  <doclet name="org.asciidoctor.Asciidoclet" pathref="asciidoclet.classpath"> (1)
    <param name="--base-dir" value="${basedir}"/>
    <param name="--attribute" value="name=${ant.project.name}"/>
    <param name="--attribute" value="version=${version}"/>
    <param name="--attribute" value="title-link=https://example.com[${ant.project.name} ${version}]"/>
  </doclet>
</javadoc>

1	Assumes a path reference has been defined for Asciidoclet and its dependencies, e.g. using Ivy or similar.

Currently, there is an intermittent benign warning message that is emitted during a run of Asciidoclet stating the following:

WARN: tilt autoloading 'tilt/haml' in a non thread-safe way; explicit require 'tilt/haml' suggested.

Unfortunately, until the underlying library removes this warning message, it will be logged during the build.