stem.adoc

= Equations and Formulas
:stem: asciimath
:url-mathjax: https://www.mathjax.org
:url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html
:url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html
:url-mathjax-docs: https://meta.math.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference

If you need to display Science, Technology, Engineering and Math (STEM) expressions in your output, the HTML backend integrates with xref:asciidoctor:stem:mathjax.adoc[MathJax] and Docbook backend integrates with the xref:asciidoctor:stem:asciimath-gem.adoc[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).

.Setting the stem attribute
[source]
----
include::example$stem.adoc[tag=base-co]
----
<.> 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 {url-asciimath}[Asciimath^] and {url-latexmath}[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.

.Assigning an alternative notation to the stem attribute
[source]
----
include::example$stem.adoc[tag=base-alt]
----

TIP: 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-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]
== Inline STEM content

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

.Inline stem macro syntax
[source#ex-inline]
----
include::example$stem.adoc[tag=in-co]
----
<.> The inline stem macro contains only one colon (`:`).
<.> Place the expression within the square brackets (`[ ]`) of the macro.

The result of <<ex-inline>> is displayed below.

====
include::example$stem.adoc[tag=in]
====

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

.Inline stem macro with a right square bracket
[source#ex-square-bracket]
----
include::example$stem.adoc[tag=in-sb]
----

The result of <<ex-square-bracket>> is displayed below.

====
include::example$stem.adoc[tag=in-sb]
====

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]
== Block STEM content

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

.Delimited stem block syntax
[source#ex-block]
----
include::example$stem.adoc[tag=bl-co]
----
<.> Assign the stem style to the passthrough block.
<.> A passthrough block is delimited by a line of four consecutive plus signs (`pass:[++++]`).

The result <<ex-block>> is rendered beautifully in the browser thanks to MathJax!

include::example$stem.adoc[tag=bl]

TIP: You don't need to add special delimiters around the expression as the {url-mathjax-docs}[MathJax documentation^] suggests.
Asciidoctor handles that for you automatically!

[#mixing-notations]
== 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`.

.Inline latexmath macro syntax
[source#ex-latexmath]
----
include::example$stem.adoc[tag=multi-l]
----

The result of <<ex-latexmath>> is displayed below.

include::example$stem.adoc[tag=multi-l]

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

.Delimited asciimath block syntax
[source]
----
include::example$stem.adoc[tag=multi-a]
----