Equations and Formulas

If you need to display Science, Technology, Engineering and Math (STEM) expressions in your output, the HTML backend integrates with MathJax and Docbook backend integrates with the AsciiMath RubyGem.

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).

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

By default, Asciidoctor’s stem support assumes all equations are AsciiMath if not specified explicitly. The HTML backend supports STEM content written in Asciimath and TeX and LaTeX math notation. The DocBook backend only supports AsciiMath notation.

If you want to use the LaTeX notation by default, assign latexmath to the stem attribute.

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

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.

Example 3. 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 expression within the square brackets ([ ]) of the macro.

The result of Example 3 is displayed below.

\$sqrt(4) = 2\$

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

If the inline stem equation contains a right square bracket, you must escape this character using a backslash.

Example 4. Inline stem macro with a right square bracket
A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))].

The result of Example 4 is displayed below.

A matrix can be written as \$[[a,b],[c,d]]((n),(k))\$.

A stem macro is an implicit passthrough macro. That’s why, despite the fact that the x expression matches the syntax of an attribute reference, you don’t have to escape it.

Block STEM content

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

Example 5. 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 Example 5 is rendered beautifully in the browser thanks to MathJax!

\$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!

Mixing STEM notations

You can use multiple notations for STEM content within the same document by using the notation’s name instead of the keyword stem.

For example, if you want to write an inline equation using the LaTeX notation, name the macro latexmath.

Example 6. Inline latexmath macro syntax
latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]

The result of Example 6 is displayed below.

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

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

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

[asciimath]
++++
sqrt(4) = 2
++++