= AsciidoctorJ: Java bindings for Asciidoctor Alex Soto https://github.com/lordofthejars[@lordofthejars]; Dan Allen https://github.com/mojavelinux[@mojavelinux]; Robert Panzer https://github.com/robertpanzer[@robertpanzer] // Settings: :compat-mode!: :page-layout: base :toc: macro :toclevels: 2 ifdef::awestruct[:toclevels: 1] :experimental: //:table-caption!: :source-language: java :language: {source-language} ifndef::env-github[:icons: font] ifdef::env-github[] :badges: :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Aliases: :dagger: † // URIs: ifdef::awestruct[:uri-docs: link:/docs] ifndef::awestruct[:uri-docs: https://asciidoctor.org/docs] :uri-asciidoctor: {uri-docs}/what-is-asciidoctor :uri-repo: https://github.com/asciidoctor/asciidoctorj :uri-issues: {uri-repo}/issues :uri-zulip: https://asciidoctor.zulipchat.com/ :artifact-version: 2.5.7 :asciidoctorj-epub3-version: 1.5.1 :asciidoctorj-pdf-version: 1.6.2 :uri-maven-artifact-query: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.asciidoctor%22%20AND%20a%3A%22asciidoctorj%22%20AND%20v%3A%22{artifact-version}%22 :uri-maven-artifact-detail: http://search.maven.org/#artifactdetails%7Corg.asciidoctor%7Casciidoctorj%7C{artifact-version}%7Cjar :uri-maven-artifact-file: http://search.maven.org/remotecontent?filepath=org/asciidoctor/asciidoctorj/{artifact-version}/asciidoctorj-{artifact-version} :uri-maven-artifact-api-query: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.asciidoctor%22%20AND%20a%3A%22asciidoctorj-api%22%20AND%20v%3A%22{artifact-version}%22 :uri-maven-artifact-api-detail: http://search.maven.org/#artifactdetails%7Corg.asciidoctor%7Casciidoctorj-api%7C{artifact-version}%7Cjar :uri-maven-artifact-api-file: http://search.maven.org/remotecontent?filepath=org/asciidoctor/asciidoctorj-api/{artifact-version}/asciidoctorj-api-{artifact-version} :uri-maven-guide: {uri-docs}/install-and-use-asciidoctor-maven-plugin :uri-gradle-guide: {uri-docs}/install-and-use-asciidoctor-gradle-plugin :uri-tilt: https://github.com/rtomayko/tilt :uri-font-awesome: http://fortawesome.github.io/Font-Awesome :uri-gradle: https://gradle.org :uri-chocolatey: https://chocolatey.org

{uri-repo}[AsciidoctorJ] is the official library for running {uri-asciidoctor}[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 https://docs.asciidoctor.org/asciidoctorj/latest/[Asciidoctor Docs site].

ifdef::badges[] image:https://github.com/asciidoctor/asciidoctorj/workflows/Build%20Main/badge.svg?event=push[Build Status (Github Actions)] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link=https://asciidoctor.zulipchat.com/] endif::[]

ifdef::awestruct,env-browser[] toc::[] endif::[]

== Distribution

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

[cols="2,2,^2,4"] .Artifact information for AsciidoctorJ in Maven Central |=== |Group Id |Artifact Id |Version |Download

|org.asciidoctor |{uri-maven-artifact-query}[asciidoctorj] |{uri-maven-artifact-detail}[{artifact-version}] |{uri-maven-artifact-file}.pom[pom] {uri-maven-artifact-file}.jar[jar] {uri-maven-artifact-file}-javadoc.jar[javadoc (jar)] {uri-maven-artifact-file}-sources.jar[sources (jar)] distribution ({uri-maven-artifact-file}-bin.zip[zip] {uri-maven-artifact-file}-bin.tar[tar])

|org.asciidoctor |{uri-maven-artifact-api-query}[asciidoctorj-api] |{uri-maven-artifact-api-detail}[{artifact-version}] |{uri-maven-artifact-api-file}.pom[pom] {uri-maven-artifact-api-file}.jar[jar] {uri-maven-artifact-api-file}-javadoc.jar[javadoc (jar)] {uri-maven-artifact-api-file}-sources.jar[sources (jar)]

|org.asciidoctor |asciidoctorj-epub3 |{asciidoctorj-epub3-version} |{empty}

|org.asciidoctor |asciidoctorj-pdf |{asciidoctorj-pdf-version} |{empty} |===

CAUTION: 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-{artifact-version}. 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).

[source] [subs="specialcharacters,attributes,callouts"]

Linux: asciidoctorj-{artifact-version}/bin/asciidoctorj Windows: asciidoctorj-{artifact-version}\bin\asciidoctorj.bat

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

[source] [subs="specialcharacters,attributes,callouts"]

Linux: asciidoctorj-{artifact-version}/bin/asciidoctorj -b pdf README.adoc Windows: asciidoctorj-{artifact-version}\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:

[source] [subs="specialcharacters,attributes,callouts"]

Linux: asciidoctorj-{artifact-version}/bin/asciidoctorj -b pdf -o READTHIS.pdf README.adoc Windows: asciidoctorj-{artifact-version}\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.

// SW: Need functional tests for a java maven project and a java gradle project

[source,xml] [subs="specialcharacters,attributes,callouts"] .Declaring the dependency in a Maven build file (i.e., pom.xml)

<dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj</artifactId> <version>{artifact-version}</version> <!--1--> </dependency> </dependencies> ----

[source,groovy] [subs="specialcharacters,attributes,callouts"] .Declaring the dependency in a Gradle build file (e.g., build.gradle)

dependencies { compile 'org.asciidoctor:asciidoctorj:{artifact-version}' }

[source,scala] [subs="specialcharacters,attributes,callouts"] .Declaring the dependency in an SBT build file (e.g., build.sbt)

libraryDependencies += "org.asciidoctor" % "asciidoctorj" % "{artifact-version}" // <1>

<1> Specifying the version of AsciidoctorJ implicitly selects the version of Asciidoctor

[source,clojure] [subs="specialcharacters,attributes,callouts"] .Declaring the dependency in a Leiningen build file (e.g., project.clj)

:dependencies [[org.asciidoctor/asciidoctorj "{artifact-version}"]]

// DA: Should we mention how to download if you just want to use the asciidoctorj command?

[TIP]

In addition to using AsciidoctorJ directly, you can invoke it as part of your build using the Maven or Gradle plugin.

• {uri-maven-guide}[How to Install and Use the Asciidoctor Maven Plugin]
• {uri-gradle-guide}[How to Install and Use the Asciidoctor Gradle Plugin] ====

[NOTE] 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 {uri-chocolatey}[Chocolatey] package is available which installs the asciidoctorj-{artifact-version}-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:

[source, xml]

<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:

[source,xml]

<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 {uri-gradle}[Gradle] add the repository like this to your build:

[source,groovy]

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

== Development

AsciidoctorJ is built using {uri-gradle}[Gradle]. The project is structured as a multi-module build.

=== P