Pipe Content Through the CLI

In addition to converting files, the Asciidoctor CLI can read content from standard input (STDIN) and/or write content to standard output (STDOUT). This feature is called piping.

Using the - flag, you can pipe content to the asciidoctor command. This flag tells Asciidoctor read the source from standard input (STDIN). For example:

This command is effectively the same as:

When reading source from STDIN, Asciidoctor doesn’t have a reference to an input file. Therefore, it sends the converted text to standard output (STDOUT) by default.

If, instead, you want to write the full document to an output file, you specify it using the -o flag. For example, the following command writes a standalone HTML document to output.html instead of STDOUT:

When you pipe content to the asciidoctor command, it no longer has a concept of where the document is located. Therefore, relative references such as includes may not work as expected. To resolve this problem, you should specify an absolute base directory using the -B option:

Alternately, you can set an artificial document directory by passing an absolute path to the docdir attribute:

Try both approaches to determine which one suits your needs better.

When piping source from STDIN to STDOUT through the asciidoctor command, you often just want the converted body (i.e., embeddable HTML). To produce that variant, add the -e flag, short for --embedded (previously the -s flag):

Or perhaps you want to include the doctitle as well: