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.
AsciidoctorJ is published to Maven Central. The artifact information can be found in the tables below.
| Group Id | Artifact Id | Version | Download |
|---|---|---|---|
org.asciidoctor |
pom jar javadoc (jar) sources (jar) distribution (zip tar) |
||
org.asciidoctor |
|||
org.asciidoctor |
asciidoctorj-epub3 |
1.5.1 |
|
org.asciidoctor |
asciidoctorj-pdf |
1.6.2 |
|
🔥
|
The artifactId changed to asciidoctorj starting in 1.5.0.
|
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.batNext, 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.adocBoom! 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.adocThe rest of the document addresses the asciidoctorj API, for doing more complex conversions from within a JVM-based application.
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.
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>2.5.7</version> <!--(1)-->
</dependency>
</dependencies>dependencies {
compile 'org.asciidoctor:asciidoctorj:2.5.7'
}libraryDependencies += "org.asciidoctor" % "asciidoctorj" % "2.5.7" // (1)-
Specifying the version of AsciidoctorJ implicitly selects the version of Asciidoctor
: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. |
|
📎
|
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.
|
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.adocPre-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>-
The exact URL differs for every build
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/'
}
}AsciidoctorJ is built using Gradle. The project is structured as a multi-module build.
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
-
asciidoctorjcommand Java components. Produces the asciidoctorj-cli. - asciidoctorj-distribution
-
Produces the distribution zip that provides the standalone
asciidoctorjcommand 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
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.
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.
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.
To build and publish a release the following properties have to be set, for example in the file ~/.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=...-
Settings for signing the artifacts
-
Credentials for publishing a new release to sdkman
-
Credentials for publishing artifacts to oss.sonatype.org
The following steps are necessary to build a new release:
-
Update the version in gradle.properties to a release version, i.e. from
2.4.4-SNAPSHOTto2.4.4. -
Build the release with
# ./gradlew clean build
-
After testing publish all artifacts to a local repository under
build/reposwith# ./gradlew publishAllPublicationsToLocalRepository -i
-
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
-
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.
-
When everything is fine publish the artifacts in the staging repository by clicking the "Release" button. Alternatively you can release it with
# ./gradlew releaseRepository
-
Publish the new version to sdkman with
# ./gradlew asciidoctorj-distribution:sdkMajorRelease
-
Commit everything and assign a tag:
# git commit -m "Release v2.x.y" # git tag v2.x.y
-
Upgrade the version to the next version by changing the version property in gradle.properties to
version=2.x.y+1-SNAPSHOTand commit:git commit -m "Prepare next release"
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent