Math and equations

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 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.

Escaping Dollars

Math can be escaped (negated) by adding a \ before the first symbol, e.g. \$a$ renders as $a$. Escaping can also be used inside math, e.g. $a=\$3$ renders as \(a=\$3\).

Conversely \\ will negate the escaping, so \\$a$ renders as \\(a\).

3.  Direct LaTeX Math#

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

equation, multiline, 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}\]
Contents