Command Line Interface

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

  • Manual installation using the binary distribution.

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

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

Linux and MacOS installation

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 installation

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