AsciidoctorJ: running Asciidoctor inside the JVM

The official way to run Asciidoctor from Java

AsciidoctorJ is the official library for running Asciidoctor on the JVM, and it is maintained by people close to the upstream project, with Alex Soto, Dan Allen and Robert Panzer named in the README header. The problem it solves is narrow. Asciidoctor itself is a Ruby program, and a Java application that wants to turn AsciiDoc into HTML has three options: shell out to a Ruby installation, bundle a Ruby runtime, or use a JVM port. AsciidoctorJ is the third option, and it removes the Ruby dependency from your build by wrapping Asciidoctor for the JVM. The library covers two use cases that the documentation states plainly: converting AsciiDoc content, and analysing the structure of a parsed AsciiDoc document. That second capability is the one that makes it more than a converter, because a parsed document can be walked and inspected programmatically instead of only rendered to output. The project is Apache-2.0 licensed, its homepage is asciidoctor.org, and the documentation lives on the Asciidoctor docs site rather than in the repository.

Four artifacts on Maven Central, one of which changed its name

AsciidoctorJ is published to Maven Central under the group id org.asciidoctor, with four artifacts listed in the README. The main one is asciidoctorj, which carries the pom, the jar, the javadoc jar, the sources jar and a binary distribution in zip and tar form. There is asciidoctorj-api, a separate artifact with the same set of jar variants, which is the API-only dependency for code that needs the interfaces without the full implementation. Two more artifacts are format specific: asciidoctorj-epub3 for EPUB output and asciidoctorj-pdf for PDF output. The README attaches a version to each of them, and the two format artifacts carry their own version numbers, epub3 at 1.5.1 and pdf at 1.6.2, which tells you that the PDF and EPUB renderers move on their own schedule rather than in step with the core. One migration note deserves repeating, the caution in the README: the artifactId changed to asciidoctorj starting in 1.5.0, so an old build file that still names the previous artifact will not resolve.

The distribution gives you a command line converter

Not every use of Asciidoctor is from inside an application. The README describes a quick path for people who just want to convert files: download the zip or tar distribution, expand it, and you have a directory named after the artifact version containing bin and lib directories. The bin directory holds the executables, asciidoctorj on Linux and macOS and asciidoctorj.bat on Windows, and the lib directory holds the supporting libraries. Running the executable with no parameters prints the available run options, which is the documented way to check that the download works. Converting a file then takes the backend flag, for example the pdf backend applied to README.adoc, which produces README.pdf, and adding the output flag with a file name writes to that name instead. Because the distribution bundles its own libraries, this route needs no Ruby, no gem install and no dependency management, and it is the same engine the library exposes, so the output matches.

Embedding the API instead of shelling out

The library route exists for the case where conversion has to happen inside a running JVM application, and the two approaches differ in more than ergonomics. Shelling out to the command line means a process per conversion, a serialisation boundary for the document, and an error path that has to be parsed out of a stream. Using the API keeps the parsed document in memory, which is what makes the second advertised capability possible: analysing the structure of a parsed document rather than only rendering it. A service that wants to extract headings, count admonitions or validate internal references can do that on the same object it would otherwise render, without writing to a file. The trade-off is footprint. A JVM application now carries the Asciidoctor engine, and depending on the output format, an additional renderer dependency, inside its own classpath and its own memory footprint.

Adding the dependency, or the classpath by hand

The installation section says to add the required dependency to the dependency management system in use, naming Maven, Gradle and Apache Ivy, and it shows the coordinates for each: the group id is org.asciidoctor, the artifact id is asciidoctorj, and the version is the one you want. A Gradle build declares the same coordinates in its dependencies block, and the README shows an SBT build doing the same with the libraryDependencies syntax. There is also a fallback for projects without a dependency management system: check the dependency graph and add all the jars in it to the classpath. That fallback is a real option rather than a formality, and it is the same set of jars the distribution ships in its lib directory. The integration documentation with a JVM language of choice is on the Asciidoctor docs site, which is where the guides for the Maven and Gradle plugins live as well.

The module layout shows what the project considers separable

The repository is a Gradle multi-project build, and the module names describe the design. asciidoctorj-core holds the engine, asciidoctorj-api the public interfaces, asciidoctorj-cli the command line front end and asciidoctorj-distribution the packaged output with the bin and lib layout described above. There is a documentation module, a test support module, and an Arquillian extension for running integration tests in a container. Two integration test modules stand out: asciidoctorj-springboot-integration-test and asciidoctorj-wildfly-integration-test, which are the clearest statement in the tree about where the library is expected to run, since a library that behaves differently inside a Spring Boot fat jar or a WildFly deployment needs its own test target. The rest of the tree is ordinary build machinery, with build.gradle, settings.gradle, gradle.properties, a ci/ directory, config/, a chocolatey/ directory for Windows packaging and a docs/ directory.

The documented version and the released version are not the same

Here is the practical catch for an adopter. The README sets an artifact-version attribute of 2.5.7 and builds its Maven coordinates and download links from it, while the release list shows v3.0.1 from 2025-11-07, v3.0.0 from 2024-08-25 and v3.0.0-beta.1 from 2024-08-11. The documentation in the repository therefore points at a 2.x coordinate, and a build that copies those coordinates verbatim will land on a line that is two major versions behind the newest tag. The repository is not archived and the last push was on 2026-10-19, so the work continues and the gap is a documentation lag rather than an abandoned 3.x line. Two other upgrade costs are visible in the tree. The artifactId rename in 1.5.0 will break any build file that predates it, and the PDF and EPUB renderers version independently, so pinning the core does not pin the output format. The Apache-2.0 licence removes the licensing question, and the CHANGELOG.adoc file at the root is where the user-visible changes between those versions are recorded.

Editorial conclusion

AsciidoctorJ is the right choice for a Java service that has to render or parse AsciiDoc inside its own process, for example a documentation portal or a report generator, since the library and the CLI both come from the same project. Do not pick it for a shell-oriented docs pipeline, where invoking the asciidoctorj executable against a distribution is simpler than adding a dependency. Before adding the dependency, check which version the build actually resolves, because the README still points at the 2.5.7 line while the latest tag is v3.0.1, and the artifactId changed name in 1.5.0.

Frequently asked questions

Official sources

1. asciidoctor/asciidoctorj on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases