AsciidoctorJ: Java bindings for Asciidoctor

AsciidoctorJ is the official library for running Asciidoctor on the JVM. Using AsciidoctorJ, you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from Java and other JVM languages.

You can find the documentation for integrating Asciidoctor in your JVM based language of choice at the Asciidoctor Docs site.

Distribution

AsciidoctorJ is published to Maven Central. The artifact information can be found in the tables below.

Table 1. Artifact information for AsciidoctorJ in Maven Central

Group Id	Artifact Id	Version	Download
org.asciidoctor	asciidoctorj	2.5.7	pom jar javadoc (jar) sources (jar) distribution (zip tar)
org.asciidoctor	asciidoctorj-api	2.5.7	pom jar javadoc (jar) sources (jar)
org.asciidoctor	asciidoctorj-epub3	1.5.1
org.asciidoctor	asciidoctorj-pdf	1.6.2

🔥	The artifactId changed to asciidoctorj starting in 1.5.0.

Quick win: using the command line interface

If you download from a distribution link above (zip or tar), you can get started straight away from the command line.

First, expand the downloaded file. That puts everything in directory asciidoctorj-2.5.7. Within that directory are bin and lib directories. bin contains the executables — asciidoctorj for Linux and macOS, and asciidoctorj.bat for Windows. lib contains the supporting libraries.

Verify the application runs by specifying the appropriate executable with no parameters; it should display the various run options available (i.e., help).

Linux: asciidoctorj-2.5.7/bin/asciidoctorj
Windows: asciidoctorj-2.5.7\bin\asciidoctorj.bat

Next, say you want to convert an ASCIIDOC (.adoc) file — such as this README — to a pdf.

Linux: asciidoctorj-2.5.7/bin/asciidoctorj -b pdf README.adoc
Windows: asciidoctorj-2.5.7\bin\asciidoctorj.bat -b pdf README.adoc

Boom! That should convert the README to a PDF named README.pdf. To create a PDF with a different name — say, READTHIS.pdf — just add the -o switch:

Linux: asciidoctorj-2.5.7/bin/asciidoctorj -b pdf -o READTHIS.pdf README.adoc
Windows: asciidoctorj-2.5.7\bin\asciidoctorj.bat -b pdf -o READTHIS.pdf README.adoc

The rest of the document addresses the asciidoctorj API, for doing more complex conversions from within a JVM-based application.

Installation

To start using AsciidoctorJ, you need to add the required dependency to the dependency management system of your choice, Maven, Gradle or Apache Ivy. If you don’t use a Dependency Management system please check the dependency graph and add all jars in it to your classpath.

Declaring the dependency in a Maven build file (i.e., pom.xml)

<dependencies>
  <dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.5.7</version> <!--(1)-->
  </dependency>
</dependencies>

Declaring the dependency in a Gradle build file (e.g., build.gradle)

dependencies {
  compile 'org.asciidoctor:asciidoctorj:2.5.7'
}

Declaring the dependency in an SBT build file (e.g., build.sbt)

libraryDependencies += "org.asciidoctor" % "asciidoctorj" % "2.5.7" // (1)

1. Specifying the version of AsciidoctorJ implicitly selects the version of Asciidoctor

Declaring the dependency in a Leiningen build file (e.g., project.clj)

:dependencies [[org.asciidoctor/asciidoctorj "2.5.7"]]

💡	In addition to using AsciidoctorJ directly, you can invoke it as part of your build using the Maven or Gradle plugin. How to Install and Use the Asciidoctor Maven Plugin How to Install and Use the Asciidoctor Gradle Plugin

📎

The versions of Asciidoctor and AsciidoctorJ no longer align since version 1.6.0 of AsciidoctorJ. Please check the corresponding release notes to find out which version of Asciidoctor is packaged if you are embedding the library. If you use the distribution you can call asciidoctorj --version to get the version of Asciidoctor that is embedded in AsciidoctorJ.

Windows Installation

A Chocolatey package is available which installs the asciidoctorj-2.5.7-bin.zip Maven artifact along with a binary shim in %ChocolateyInstall%\bin which lets you run AsciidoctorJ from the command line.

C:\> choco install asciidoctorj
C:\> where asciidoctorj
C:\ProgramData\chocolatey\bin\asciidoctorj.exe
C:\> asciidoctorj -b pdf README.adoc

Using a pre-release version

Pre-release versions of AsciidoctorJ are published to oss.sonatype.org. The exact location of the repository will be announced. Final releases are released to both Maven Central.

Here’s how to use a pre-release version in Maven:

    <repositories>
        <repository>
            <id>staging</id>
            <url>https://oss.sonatype.org/content/repositories/orgasciidoctor-1234</url> <!--(1)-->
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
    </repositories>

1. The exact URL differs for every build

Using a snapshot version

Snapshot versions will be published to https://oss.jfrog.org. To use a snapshot version of the the AsciidoctorJ library add this repository to your project:

<repositories>
    <repository>
        <id>snapshots</id>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    </repository>
</repositories>

If you build your project using Gradle add the repository like this to your build:

repositories {
    maven {
        url 'https://oss.sonatype.org/content/repositories/snapshots/'
    }
}

Development

AsciidoctorJ is built using Gradle. The project is structured as a multi-module build.

Project layout

The root folder is the root project and there are several subproject folders, each prefixed with asciidoctorj-. Each subproject produces a primary artifact (e.g., jar or zip) and its supporting artifacts (e.g., javadoc, sources, etc).

The subprojects are as follows:

asciidoctorj-api

The common API for AsciidoctorJ. Other implementations for different platforms than JRuby may reuse and implement this API. Produces the asciidoctorj-api.jar

asciidoctorj

The main Java bindings for the Asciidoctor RubyGem (asciidoctor) running on JRuby. Also bundles optional RubyGems needed at runtime, such as coderay, tilt, haml and slim. Produces the asciidoctorj jar.

asciidoctorj-cli

asciidoctorj command Java components. Produces the asciidoctorj-cli.

asciidoctorj-distribution

Produces the distribution zip that provides the standalone asciidoctorj command including Java components, launch scripts and required libraries.

asciidoctorj-arquillian-extension

Bundles an Arquillian extension that allows to inject an Asciidoctor instance or other instances commonly used by Asciidoctor tests into a test case.

asciidoctorj-test-support

Contains some common test classes that are used by multiple other subprojects and the Arquillian extension.

The Gradle build is partitioned into the following files:

build.gradle
gradle.properties
settings.gradle
gradle/
  wrapper/
    ...
  eclipse.gradle
  providedConfiguration.gradle
  publish.gradle
  sign.gradle
asciidoctorj-arquillian-extension/
  build.gradle
asciidoctorj-api/
  build.gradle
asciidoctorj-cli/
  build.gradle
asciidoctorj-core/
  build.gradle
asciidoctorj-distribution/
  build.gradle
asciidoctorj-test-support/
  build.gradle

Build the project

You invoke Gradle on this project using the gradlew command (i.e., the Gradle Wrapper).

💡	We strongly recommend that you use Gradle via the Gradle daemon.

To clone the project, compile the source and build the artifacts (i.e., jars) locally, run:

$ git clone https://github.com/asciidoctor/asciidoctorj
  cd asciidoctorj
  ./gradlew assemble

You can find the built artifacts in the asciidoctorj-*/build/libs folders.

To execute tests when running the build, use:

$ ./gradlew build

To only execute the tests, run:

$ ./gradlew check

You can also run tests for a single module:

$ cd asciidoctorj-core
  ../gradlew check

To run a single test in the asciidoctorj-core subproject, use:

$ ../gradlew -Dsingle.test=NameOfTestClass test

To create the distribution, run:

$ ./gradlew distZip

You can find the distribution in the asciidoctorj-distribution/build/distributions folder.

Develop in an IDE

IntelliJ IDEA

To import the project into IntelliJ IDEA 14, simply import the project using the import wizard. For more information, see the Gradle page in the IntelliJ IDEA Web Help.

Eclipse

To open the project in Eclipse, first generate the Eclipse project files:

$ cd asciidoctorj-core
  ./gradlew eclipse

Then, import the project into Eclipse using File › Import › General › Existing Project into Workspace.

Continuous integration

Continuous integration for the AsciidoctorJ project is performed by GitHub Actions. You can find recent build results, including the build status of pull requests, on the asciidoctor/asciidoctorj page.

Release and publish the artifacts

To build and publish a release the following properties have to be set, for example in the file ~/.gradle/gradle.properties:

~/.gradle/gradle.properties

signing.keyId=...              # (1)
signing.password=...
signing.secretKeyRingFile=/home/YOUR_USERNAME/.gnupg/secring.gpg

sdkman_consumer_key=...        # (2)
sdkman_consumer_token=...

sonatypeUsername=...           # (3)
sonatypePassword=...

1. Settings for signing the artifacts

2. Credentials for publishing a new release to sdkman

3. Credentials for publishing artifacts to oss.sonatype.org

The following steps are necessary to build a new release:

1. Update the version in gradle.properties to a release version, i.e. from 2.4.4-SNAPSHOT to 2.4.4.

2. Build the release with

   # ./gradlew clean build

3. After testing publish all artifacts to a local repository under build/repos with

   # ./gradlew publishAllPublicationsToLocalRepository -i

4. When everything is fine publish the artifacts to a staging repository on https://oss.sonatype.org and close the repository:

   # ./gradlew publishAllPublicationsToSonatypeRepository -i
   # ./gradlew closeRepository -i

5. Visit https://oss.sonatype.org/#stagingRepositories and check the staging repository. The artifacts are not published yet. The repository URL shown there can be used for testing this version before publishing to Maven central.

6. When everything is fine publish the artifacts in the staging repository by clicking the "Release" button. Alternatively you can release it with

   # ./gradlew releaseRepository

7. Publish the new version to sdkman with

   # ./gradlew asciidoctorj-distribution:sdkMajorRelease

8. Commit everything and assign a tag:

   # git commit -m "Release v2.x.y"
   # git tag v2.x.y

9. Upgrade the version to the next version by changing the version property in gradle.properties to version=2.x.y+1-SNAPSHOT and commit:

   git commit -m "Prepare next release"

Resources

The source code for AsciidoctorJ, including the latest developments and issues, can be found in the project’s repository on GitHub. If you identify an issue while using AsciidoctorJ, please don’t hesitate to file a bug report. Also, don’t forget to join the Asciidoctor Zulip community, where you can ask questions and leave comments.