Converters
After Asciidoctor parses an AsciiDoc document, it uses a converter to generate the output format of your choice, such as HTML, DocBook, or PDF. Asciidoctor includes a handful of built-in converters. The Asciidoctor project provides additional converters that you can add on, which are distributed separately. You also have the option to create your own converter or to use one published by a third party.
When working with converters, it’s important to understand the distinction between a converter and a backend. This page explains that difference while also providing more background on how converters function.
What is a converter?
A converter takes AsciiDoc and transforms it into a different format. More specifically, it processes each node (i.e., block or inline element) in a parsed AsciiDoc document in document order and returns a converted fragment, which the processor combines to create the output document. Each converter produces a specific output format, such as HTML or DocBook XML.
Asciidoctor provides several built-in converters and a facility for adding additional converters.
In addition to generating traditional articles and books from AsciiDoc documents, you can also use Asciidoctor to create HTML-based slide decks, static websites, and documentation sites. When using these add-on converters, you may need to include some additional structure rules to a document. However, nothing in this structure restricts you from being able to publish the content as a normal document, too.
What is a backend?
Each converter is correlated with an output format using a backend identifier.
From the user’s perspective, the backend represents the desired output format.
A converter will register itself with a backend identifier to claim that it produces that output format.
For example, the backend identifier for the built-in HTML 5 converter is html5.
Thus, from the processor’s perspective, the backend is the value it uses to identify which converter to use.
The term backend is often used interchangeably with the name of a converter.
For example, you might hear “the html5 backend” when someone is talking about the HTML 5 converter.
However, there’s an important distinction between these terms.
|
A custom converter can either introduce or reclaim a backend identifier. Since it’s possible for a converter to reclaim a backend identifier, we can’t say that a backend universally equates to a given converter. Rather, the backend identifier informs the processor which converter to select to handle the requested backend based on what’s currently registered.
The user selects which converter to use to convert a document by specifying the backend document attribute, -b (--backend) command line option, or backend API option (e.g., --backend=docbook5).
The html5 and docbook5 backends can be referred to using the aliases html and docbook, respectively.
In summary, a converter is a software component that handles the conversion from a parsed AsciiDoc document to a publishable output format.
The backend represents the user’s intent to transform the AsciiDoc document to a given format (e.g., html5 for HTML 5).
That backend also serves as an identifier that tells the processor which converter to use.
More than one converter can bind to (i.e., stake claim to) the same backend in order to provide the user with alternatives for generating a given output format.
For example, the backend pdf could be satisfied by Asciidoctor PDF, but it may also be mapped to a different implementation.
The last converter that registers itself with a backend wins.