Extend the PDF Converter
This page gives you a crash course in how to extend the PDF converter. It begins by introducing the technology the converter uses to generate the PDF and links you to a tutorial covering how to use it. Then it briefly explains how the theming system influences the converter. Finally, it gives you an overview of how to extend the converter.
Asciidoctor PDF uses Prawn under the covers to generate the PDF. Prawn is a low-level PDF writer that can load fonts, ink text, embed images, add graphics, and draw lines. With those operations alone, this converter manages to produce a PDF from an AsciiDoc document.
Before you dive into extending this converter, you’ll need to understand how to use Prawn. The article Hackable PDF Typesetting in Ruby with Prawn gives a crash course in how to create your first PDF document containing text, graphics, and images with Prawn. That article is essential reading for extending Asciidoctor PDF, because Asciidoctor PDF uses many of the same operations (as well as many helpful add-ons). Once you feel comfortable with Prawn, you’re ready to extend the converter.
While creating the PDF document, there are thousands of small decisions the converter must make about how to instruct Prawn to lay out the content elements on the page (so-called “hackable typesetting”). But once these elements are written, they can’t be moved or styled (as is the case with HTML and CSS). To help influence those decisions—and thus prevent the converter from becoming too opinionated, a theming system was introduced.
The theme support is there to provide basic customizations (fonts, colors, borders, spacing, etc.). But it can only go so far. At some point, it becomes necessary to extend the converter to meet advanced design requirements.
The pages Create an Extended Converter and Use the Extended Converter provide step-by-step instructions about how to create and use your first extended converter. If you have those steps under your belt, browse the Extended Converter Use Cases page to see examples of how to extend the converter and give you ideas about the kinds of customizations you can make in an extended converter.
The methods on a converter class that handle conversion of elements follow the pattern
convert_<name> for block elements (e.g.,
convert_inline_<name> for inline elements (e.g.,
<name> is the name of the element.
When you override a block element, you write PDF objects directly to the Prawn Document (the current context). When you override an inline element, you return pseudo-HTML, which is then parsed and converted into PDF objects.
The pseudo-HTML in Asciidoctor PDF evolved from the inline formatting in Prawn, now supporting the following elements: a, br, button, code, color, del, em, font, img, key, mark, span, strong, sub, sup.
All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g.,
You can change the font color using the
rgb attribute on the
color element (e.g.,
<color rgb="#ff0000">) and the font family and size using the
size attributes on the
font element, respectively (e.g.,
<font name="sans" size="12">).
You can also use the
style attribute on
span to control the font color, weight, and style using the relevant CSS property names.
The pseudo-HTML in Asciidoctor PDF also supports the
class attribute on any element for applying roles from the theme.
(Though not recommended, you can pass this pseudo-HTML straight through to Prawn using an inline passthrough in AsciiDoc).