In order to insert a rendered expression into the PDF, the toolchain must parse the expressions and convert them to a format the PDF writer (Prawn) can understand. That typically means converting to an image.
One solution that provides this capability is an extension named Asciidoctor Mathematical, which is covered in the next section.
Asciidoctor Mathematical is an extension that processes STEM blocks and inline macros and converts them to a PDF-compatible format. After the document has been parsed, the extension locates each asciimath, latexmath, and stem block and inline macro, converts the expression to an image, and replaces the expression with an image. It uses Mathematical to render the LaTeX notation as an image. If the expression is AsciiMath, it first uses AsciiMath gem to convert to LaTeX. Conversion then proceeds as normal.
Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Refer to the installation section in the Asciidoctor Mathematical README to learn how to install it.
Once Asciidoctor Mathematical is installed, you can enable it when invoking Asciidoctor PDF using the
$ asciidoctor-pdf -r asciidoctor-mathematical sample.adoc
If you’re invoking Asciidoctor PDF via the API, you need to require the Asciidoctor Mathematical gem before invoking Asciidoctor PDF.
require 'asciidoctor-mathematical' require 'asciidoctor-pdf' Asciidoctor.convert_file 'sample.adoc', backend: 'pdf', safe: :safe
To get the best quality output and maximize the speed of conversion, we recommend configuring Asciidoctor Mathematical to convert equations to SVG.
You control this setting using the
mathematical-format AsciiDoc attribute:
$ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc
Refer to the README for Asciidoctor Mathematical to learn about additional settings and options.