Asciidoctor: AsciiDoc with new functions Performance Enhanced

Asciidoctor: AsciiDoc with new functions Performance Enhanced

Article from Issue 241/2020

The popular AsciiDoc documentation system still has a lot to offer, but more experienced users should check out Asciidoctor, which has some additional new features.

AsciiDoc [1] is a publication and documentation system, as well as a markup and formatting language. The simple syntax and clear-cut markup make source code edited with AsciiDoc easy to read directly.

However, those familiar with AsciiDoc may be interested in the additional features available with Asciidoctor. While Asciidoctor is designed for compatibility with AsciiDoc, there are points at which it differs from the original, including greater speed and a number of useful features.

New Capabilities

AsciiDoc's first versions date back to 2002. Today the packages are part of the standard feature set in many distributions and can be imported from their repositories. Besides HTML and XHTML, AsciiDoc supports the DocBook output format, which is useful as source material for generating specially formatted HTML, PDF, EPUB, DVI, LaTeX, roff, and PostScript files.

The AsciiDoc documentation system is based on Python 2, which is no longer supported. Before an AsciiDoc version adapted to the new Python 3 was released in June 2020, some interesting AsciiDoc variants were created – most notably Asciidoctor [2]. Asciidoctor's developers ensured its very extensive compatibility with AsciiDoc through more than 2,500 tests. They also implemented the program in Ruby, which speeds up conversion by a factor of about 100 compared to the classic Python variant. Later implementations in Java and JavaScript were added to support editing source code directly in the web browser [3].

Asciidoctor has a number of additional benefits [4]. One is that it extends the capabilities of the parser (i.e., the part of the program that reads and analyzes the input), which helps it support more complex constructions. Another benefit is a plugin system that allows for additional features such as special charts and the implementation of additional output formats, such as optimized PDFs, without the need to detour via DocBook as well as complex LaTeX and XHTML5.

There are also special Asciidoctor variants for different output formats, on which the developers work independently of the main distribution (currently version 2.0.10). For many editors there are plugins that help with the syntax and partly support compiling. The "Asciidoctor Variants" box looks at the most important examples. All of the converters mentioned are independent projects and accordingly have different documentation. Each of them achieves quite useful results. However, all of the variants require training if you need formatting that differs from the default settings.

Asciidoctor Variants

Asciidoctor EPUB3 [5] is not yet available as a package, but it works quite well with a few limitations. The aim is not only to translate into the EPUB3 format, but also to create an aesthetically pleasing design for ebooks. The option -a ebook-validate automatically calls EPUBCheck.

Asciidoctor LaTeX [6] allows more extensive customization of the output with respect to the LaTeX code than AsciiDoc. This variant uses AMSTeX instead of standard LaTeX. This allows for more granular layout control. For example, unnecessarily extensive title pages are no longer required.

Asciidoctor PDF [7] allows direct conversion to PDF without the DocBook tool chain. The software is stable and comes with an additional component, a variant that generates more compact PDFs (asciidoctor-pdf-optimize). The software lets you customize the output in terms of layout using a CSS-style mechanism.

The a2x shell script lets users quickly and automatically convert source code to various output formats, especially to PDF. Additionally, it can evaluate options contained in the imported source code. This allows certain settings in the documents to be made in advance, such as the language and format of the output, as well as the document type. The instructions are written as comments in the lines directly after the document header. A call to a2x <file> translates the document with all available options.

Installing Asciidoctor

Normally, you would install Asciidoctor from your distribution's repository. However, if some components are missing, such as asciidoctor-epub3, you can use Ruby's own gem installation system and import the missing components, or gems, directly from the Ruby repository:

$ gem install asciidoctor-epub3

The tool installs the gems in ~/.gem/ruby/2.7.0/bin/. You must include this path in the system PATH variable.

In some cases, as in the example of asciidoctor-epub3, there are no packages officially available as of yet, and you will receive an error message. If there are packages that are still under development, you can test them with the --pre option:

$ gem install asciidoctor-epub3 --pre

In this case, the installation will be performed and more packages will be added.

The packages available in the gem repositories for Asciidoctor are shown by this command:

$ gem search asciidoctor

Again, --pre will reveal unfinished packages if necessary.


AsciiDoc and Asciidoctor differ in some details. For simple documents, this is at most a minor issue. However, if you make full use of the capabilities of each piece of software, the differences become more apparent. You will find examples of both AsciiDoc and Asciidoctor extensions in the AsciiDoc Syntax Quick Reference [8] – search for the (Asciidoctor only) string, which designates these features. In most cases the capabilities of Asciidoctor go beyond what AsciiDoc supports, however thanks to the built-in compatibility mode, Asciidoctor can handle anything you formatted with AsciiDoc. Having said this, the newcomer does not offer a counterpart for the command a2x, see box, "AsciiDoc's a2x Command."

Alternatively, you can specify the options at the shell prompt. As a special feature, a2x has the --epubcheck option to automate the process of calling the a2x tool, which identifies potential problems in EPUB documents.

Like AsciiDoc, Asciidoctor is usually controlled via the command line. The most important options, which are very similar to those of AsciiDoc, are summarized in Table 1. A command call without options translates the specified file with the .adoc extension to HTML5:

$ asciidoctor tst.adoc

Table 1

Asciidoctor Command-Line Options



-b <Format>

Creates output as HTML5 (default), XHTML5, DocBook 5, manpage or – with appropriate plugins – as PDF, LaTeX, or EPUB

-d <Type>

Besides the classics article (default), book, and manpage, Asciidoctor offers output for included code, like single blocks, paragraphs, or similar

-o <File>

Saves the output under the specified name

-D <Directory>

Saves the result in the specified directory


Suppresses headers and footers (for included documents)


Auto numbering of sections

-a <Attribute>

Set AsciiDoc attributes (overwrites existing ones in the document)

-B <Base>

Defines the base directory for additional code; default is the current directory


Outputs detailed messages

--failure-level <Level>

Warning level, from which error codes were generated: WARN, ERROR, INFO, FATAL (default)


Output warnings on screen


Sets safe mode level; disables potentially insecure structures like include::

By default the tool suppresses messages during conversion. It only shows you serious errors, such as the absence of embedded images. But this does not stop further editing.

When switching from AsciiDoc to Asciidoctor, there are some differences to be considered, which are summarized in chapter 90 of the user manual [9].

For example, in terms of the syntax, there is now only the _<Text>_ syntax for text in italics, `<Text>` for code, and `+{<Text>}+` for literal text in code. Double quotation marks are created with "`<Text>`", as well as single quotation marks with '`<Text>`'.

For titles, the = <Title> syntax (asymmetrical form) remains valid, but not the symmetrical form (= <Title> =) or the form using underlining. Underlining in the title automatically leads to the use of compatibility mode. Section 90.8 in the manual also provides an overview of new or additional features.

Asciidoctor now supports UI macros for keyboard shortcuts (Figure 1). Also interesting in Asciidoctor is the standard approach of writing each sentence as one line of the source code, in the manner common for program code. This allows for sentence swapping, commenting out, and other manipulation much like in any programming language.

Figure 1: These UI macros for keyboard shortcuts are available in Asciidoctor, but not in AsciiDoc. ©

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • AsciiDoc

    AsciiDoc syntax along with its eponymous command lets users create a text document with unobtrusive markup and convert it to a variety of output formats.

  • Introduction

    This month in Linux Voice.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More