Command Line Interface

There are three basic ways to make AsciidoctorJ available as a command line tool.

  • Manual installation using the binary distribution.

  • Automated installation using a package manager like SDKMAN or Chocolatey.

  • Directly running AsciidoctorJ using JBang.

Manual distribution installation

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

First, extract the downloaded file. That puts everything in directory asciidoctorj-3.0.0. Within that directory are the 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-3.0.0/bin/asciidoctorj
Windows: asciidoctorj-3.0.0\bin\asciidoctorj.bat

Next, say you want to convert an AsciiDoc (.adoc) file to a pdf.

Linux: asciidoctorj-3.0.0/bin/asciidoctorj -b pdf README.adoc
Windows: asciidoctorj-3.0.0\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-3.0.0/bin/asciidoctorj -b pdf -o READTHIS.pdf README.adoc
Windows: asciidoctorj-3.0.0\bin\asciidoctorj.bat -b pdf -o READTHIS.pdf README.adoc

Automated distribution installation

Linux and MacOS

A SDKMAN! candidate is available for easy installation in Linux and MacOS. This will install the binary distribution and set up the PATH automatically.

$ sdk install asciidoctorj
$ asciidoctorj -b pdf README.adoc

Windows

A Chocolatey package is available which installs the asciidoctorj-3.0.0-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

Running AsciidoctorJ using JBang

JBang enables you to run AsciidoctorJ without needing to install it first. As an added benefit, JBang automatically uses the most recent version of AsciidoctorJ, updating it automatically on subsequent runs.

Linux and MacOS
 $ jbang run asciidoctorj@asciidoctor -b pdf README.adoc
Windows
C:\> jbang run asciidoctorj@asciidoctor -b pdf README.adoc