Math and equations#

Math can be written in the common LaTeX markup. There are several syntaxes to define inline and block math, depending on your preference.

1.  Math role and directive#

The math role and directive are used used to define inline and block math respectively.

The directive supports multiple equations, which should be separated by a blank line. Each single equation can have multiple aligned lines, which should be separated by \\ characters, and each line can have multiple & characters to align the equations.

The label option can also be used to reference the equation later on, with the eq role.

Since Pythagoras, we know that {math}a^2 + b^2 = c^2.

{math}
:label: mymath
(a + b)^2 = a^2 + 2ab + b^2

(a + b)^2  &=  (a + b)(a + b) \\
&=  a^2 + 2ab + b^2


The equation {eq}mymath is a quadratic equation.


Since Pythagoras, we know that $$a^2 + b^2 = c^2$$.

(1)#\begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\end{aligned}\end{align}

The equation (1) is a quadratic equation.

See also

Sphinx documentation on the role and directive, and math support for HTML outputs in Sphinx.

2.  Dollar delimited math#

Enabling the dollarmath extension will allow parsing the following syntax:

• Inline math: $...$

• Display (block) math: $$...$$

Additionally if myst_dmath_allow_labels=True is set (the default):

• Display (block) math with equation label: $$...$$ (1)

$$(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2$$ (mymath2)

The equation {eq}mymath2 is also a quadratic equation.

(2)#$\begin{split} (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2 \end{split}$

The equation (2) is also a quadratic equation.

3.  Direct LaTeX Math#

Enabling the amsmath extension will directly parse the following top-level math environments:

equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.

As expected, environments ending in * will not be numbered, for example:

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

\begin{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\end{align}

$\begin{gather*} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather*}$
(3)#\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}