Equations and Formulas (STEM)

If you need to include Science, Technology, Engineering and Math (STEM) expressions in your document, the AsciiDoc language supports embedding math-mode macros from LaTeX and/or AsciiMath notation as block or inline elements. These elements act as passthroughs to preserve the expressions as entered. The expressions are then passed on to the converter to be processed and rendered for display using a STEM provider (e.g., MathJax).

Activating STEM support

To activate equation and formula support, 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, AsciiDoc’s stem integration assumes all equations are AsciiMath if not specified explicitly. The HTML converter supports STEM content written in AsciiMath and TeX and LaTeX math notation. The DocBook converter only processes AsciiMath notation, leaving LaTeX to be processed by a separate tool in the DocBook toolchain.

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. The AsciiDoc processor handles that for you automatically!

Newlines in AsciiMath blocks

Newlines in an AsciiMath block are only preserved in certain circumstances. The following examples illustrate how newlines are handled.

Single newline not preserved

x
y

Single newline preserved if escaped

x\
y

Sequential newlines preserved if escaped

x\
\
y

Paragraph break preserved

x

y

Sequential newlines between paragraph break preserved

x


y

The first preserved newline splits the expression into two. Subsequent newlines get translated into a <br> element.

Newlines in LaTeX blocks

Newlines in a LaTeX block are only preserved in certain circumstances. The following examples illustrate how newlines are handled.

Single newline not preserved

x
y

Single newline preserved if escaped

x\\
y

Sequential newlines preserved if escaped and prefixed by null character

x\\
~\\
y

Paragraph break not preserved

x

y

Paragraph break preserved if separated by newline spacer

x
\\[1em]
y

The first preserved newline splits the expression into two. Subsequent newlines get translated into a <br> element.

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. Using both asciimath and latexmath notations in a single document

= My Diabolical Mathematical Opus
Jamie Moriarty
:stem: latexmath

.An e-xciting limit with LaTeX!
[stem]
++++
\lim_{n \to \infty}\frac{n}{\sqrt[n]{n!}} = {\large e}
++++

.A basic square root with AsciiMath
[asciimath]
++++
sqrt(4) = 2
++++

Here’s how the body of this example will be shown:

An e-xciting limit with LaTeX!

\[\lim_{n \to \infty}\frac{n}{\sqrt[n]{n!}} = {\large e}\]

A basic square root with AsciiMath

\$sqrt(4) = 2\$