Process AsciiDoc Using the CLI

When the Asciidoctor gem is installed successfully, the Asciidoctor command line interface (CLI) named asciidoctor will be available on your PATH. To confirm that the CLI is available, execute the following command in your terminal application:

$ asciidoctor --version

If this command completes successfully, information about Asciidoctor and the runtime environment will be printed to the standard output of your terminal:

Asciidoctor 2.0.16 []
Runtime Environment (ruby 3.0.2p107 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

The runtime environment information varies based on the version of Ruby you’re using and the encoding settings of your operating system.

To invoke Asciidoctor from the CLI and convert an .adoc file, execute:

$ asciidoctor <asciidoc-file>

This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the .html extension.

CLI Options describes the available options and parameters for the Asciidoctor CLI.

You can output the usage for the asciidoctor command by appending the --help option:

$ asciidoctor --help

You can generate the full documentation (i.e., man page) for the asciidoctor command by passing the manpage argument to the --help option, which you can then pipe to the man pager for viewing:

$ asciidoctor --help manpage | man -l -

You can find the AsciiDoc source for the Asciidoctor man page online in the Asciidoctor repository, which you can preview in a browser.