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).
= 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.
= 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.
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.
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.
[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!
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
.
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.
= My Diabolical Mathmatical Opus
Jamie Moriarty
:stem: latexmath
[asciimath]
++++
sqrt(4) = 2
++++