STEM Processing
AsciiDoc defines syntax elements for adding science, technology, engineering, and math (STEM) expressions to an AsciiDoc document. Much like AsciiDoc itself, this STEM notation allows the graphical notation that scientists, mathematicians, and engineers use to describe equations, formulas, etc. be expressed in a plain text format. It’s up to the converter to interpret and transform the source of these expressions into a displayable format. That’s where STEM processing comes in.
On this page, we look at how STEM expressions are handled when converting AsciiDoc and survey the integrations Asciidoctor offers to process them for various output formats.
How it works
When a converter comes across a STEM node in an AsciiDoc document, it passes the source of the expression to a STEM processing library, such as MathJax. That library either displays the rendered expression itself (e.g., MathJax), turns it into an image the converter can link to or embed in the output file (e.g., Asciidoctor Mathematical), or translates it into another format that something further down the pipeline can process (e.g., AsciiMath).
The STEM integrations are activated when the stem document attribute is set on the document and, if required, the relevant library is installed.
STEM integrations
| Library Name | Supported Versions | Backends | Loaded By |
|---|---|---|---|
MathJax |
2.7.9 |
html |
client |
Asciidoctor Mathematical |
0.3.5 |
any |
processor |
AsciiMath (Ruby) |
1.0.x or 2.0.x |
docbook |
processor |
You can explore these integrations in depth on the MathJax and HTML, Asciidoctor Mathematical, and AsciiMath Gem pages.
If you’re planning to convert to DocBook to leverage the DocBook toolchain, be sure to consider STEM Support in the DocBook Toolchain when deciding which STEM notation to use in your AsciiDoc document.