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.21 [https://asciidoctor.org] Runtime Environment (ruby 3.1.2p20 [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
CLI Options describes the available options and parameters for the Asciidoctor CLI.
--help option provides self-describing documentation for the
asciidoctor command, grouped by topic.
If you don’t specify a topic, the
--help option prints the usage statement for the
$ asciidoctor --help
You can generate the full documentation (i.e., man page) for the
asciidoctor command by passing the
manpage topic to the
You can pipe that output to the
man pager to view it:
$ asciidoctor --help manpage | man -l -
You can also find the man page for the
asciidoctor command rendered as HTML in this documentation, which you can view in a browser instead.
You can print an AsciiDoc syntax crib sheet by passing the
syntax topic to the
$ asciidoctor --help syntax
The crib sheet itself is composed in AsciiDoc.
You can convert it to HTML by piping the output back into the
$ asciidoctor --help syntax | asciidoctor -o syntax.html -
Navigate to the syntax.html file in your browser to see what the examples in the crib sheet look like when converted to HTML.