Equations and Formulas with STEM

If you need to get technical in your writing, Asciidoctor integrates with MathJax. MathJax is the standard library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser.

Thanks to MathJax JavaScript library, Asciidoctor supports both AsciiMathML and TeX and LaTeX math notation in the same document.

Activating STEM support

To activate equation and formula support, simply set the stem attribute in the document’s header (or by passing the attribute to the command line or API).

Setting the stem attribute
= My Diabolical Mathematical Opus
Jamie Moriarty
:stem: (1)
1 The default interpreter value, asciimath, is assigned implicitly.

By default, Asciidoctor’s stem support assumes all equations are AsciiMath if not specified explicitly. If you want to use the LaTeX interpreter by default, assign latexmath to the stem attribute.

The html backend will just use mathjax client-side to render math notation, whereas the docbook backend will use it to convert math to mathml.

Assigning an alternative interpreter to the stem attribute
= My Diabolical Mathematical Opus
Jamie Moriarty
:stem: latexmath
You can still use both interpreters in the same document. The value of the stem attribute merely sets the default interpreter. To set the interpreter explicitly for a given block or inline span, just use asciimath or latexmath in place of stem as explained in Using multiple STEM interpreters.

Stem content can be displayed inline with other content or as discrete blocks. No substitutions are applied to the content within a stem macro or block.

Inline stem content

The best way to mark up an inline formula is to use the stem macro.

Inline stem macro syntax
stem:[sqrt(4) = 2] (1) (2)

Water (stem:[H_2O]) is a critical component.
1 The inline stem macro contains only one colon (:).
2 Place the content you want interpreted within the square brackets ([ ]) of the macro.
Rendered inline stem content

\$sqrt(4) = 2\$

Water (\$H_2O\$) is a critical component.

Block stem content

Block formulas are marked up by assigning the stem style to a delimited passthrough block.

Delimited stem block syntax
[stem]   (1)
++++     (2)
sqrt(4) = 2
1 Assign the stem style to the passthrough block.
2 A passthrough block is delimited by a line of four consecutive plus signs (++++).

The result is rendered beautifully in the browser thanks to MathJax!

Rendered delimited stem block
\$sqrt(4) = 2\$
You don’t need to add special delimiters around the expression as the MathJax documentation suggests. Asciidoctor handles that for you automatically!

Using multiple STEM interpreters

You can use multiple interpreters for stem content within the same document by using the interpreter’s name instead of the default stem name.

For example, if you want LaTeXMath to interpret an inline equation, name the macro latexmath.

Inline latexmath macro syntax
latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]
Rendered latexmath content

\(C = \alpha + \beta Y^{\gamma} + \epsilon\)

The name that maps to the interpreter you want to use can also be applied to block stem content.

Delimited asciimath block syntax
= My Diabolical Mathmatical Opus
Jamie Moriarty
:stem: latexmath

sqrt(4) = 2

Enabling STEM expressions in the DocBook toolchain

When converting to HTML, Asciidoctor relies on MathJax to parse and render the STEM expressions in the browser. We can’t rely on MathJax when converting to DocBook, so Asciidoctor must explicitly convert the expressions into something the DocBook toolchain can understand. Enter the asciimath gem.

The asciimath gem converts AsciiMath expressions to MathML. The DocBook converter uses this functionality if the gem is available. Thus, to enable AsciiMath support when converting to DocBook, you need to install the asciimath gem:

$ gem install asciimath

For full functionality, you’ll also need at least Asciidoctor version 1.5.4.

The asciimath gem converts AsciiMath to MathML. If you’re generating a PDF from the DocBook, the MathML needs to be interpreted and drawn into the PDF. In the DocBook FOP pipeline, this is handled by JEuclid.

Fortunately, fopub is already configured to use the JEuclid integration. When fopub generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions transformed from AsciiMath to MathML by the asciimath gem. As a result, AsciiMath stem expressions in the AsciiDoc file will render as expected in the generated PDF.

There’s no equivalent gem for converting STEM expressions written in LaTeX to MathML. Instead, you can convert the DocBook to PDF using the dblatex pipeline, which obviously supports LaTeX expressions.