sphinx-typst-math¶

sphinx-typst-math renders native Typst equations as MathML in Sphinx HTML documentation. The equations below are compiled by the official Typst compiler; MathJax, a Typst-to-LaTeX conversion, and a browser-side JavaScript renderer are not involved.

Installation¶

Install the extension together with the integrations used by this demonstration:

pip install sphinx-typst-math myst-parser nbsphinx sphinx-immaterial

Enable the extensions and select the Typst renderer in conf.py:

extensions = [
    "sphinx_immaterial",
    "sphinx_immaterial.theme_result",
    "myst_parser",
    "nbsphinx",
    "sphinx_typst_math",
]

html_math_renderer = "typst"
myst_enable_extensions = ["dollarmath"]
nbsphinx_execute = "never"

Warning

Do not add sphinx.ext.mathjax: Typst produces the MathML included in the final HTML directly.

Native Typst equations¶

Use Typst syntax between MyST’s dollar delimiters. Inline equations can be placed directly in a sentence:

The first $n$ positive integers satisfy
$sum_(k=1)^n k = (n(n+1))/2$.

The first $𝑛$ positive integers satisfy $\sum_{𝑘 = 1}^{𝑛} 𝑘 = \frac{𝑛 (𝑛 + 1)}{2}$ .

Display equations work the same way:

$$
A = mat(1, 2; 3, 4)
quad det(A) = -2
$$

𝐴 = (\begin{matrix} 1 & 2 \\ 3 & 4 \end{matrix}) det (𝐴) = - 2

Typst features such as cases and text embedded in math remain available:

$$
abs(x) = cases(
  x & "if" x >= 0,
  -x & "if" x < 0,
)
$$

| 𝑥 | = {\begin{cases} 𝑥 & if 𝑥 \geq 0 \\ - 𝑥 & if 𝑥 < 0 \end{cases}

reStructuredText input¶

The renderer also handles the standard reStructuredText math role and directive. Their contents are still native Typst source:

reStructuredText math¶

Inline math uses :math:`sum_(k=1)^n k = (n(n+1))/2`.

.. math::

   integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2

Inline math uses $\sum_{𝑘 = 1}^{𝑛} 𝑘 = \frac{𝑛 (𝑛 + 1)}{2}$ .

\int_{0}^{\infty} 𝑒^{- 𝑥^{2}} d 𝑥 = \frac{\sqrt{𝜋}}{2}

Equation numbers and references¶

Attach a MyST label after a display equation. Sphinx owns the number, target, and cross-reference while Typst renders the equation body.

$$
E = m c^2
$$ (mass-energy)

Equation {eq}`mass-energy` is rendered as native MathML and retains the normal
Sphinx permalink and reference behavior.

𝐸 = 𝑚 𝑐^{2}

Equation (1) is rendered as native MathML and retains the normal Sphinx permalink and reference behavior.

Labels can also be attached to reStructuredText math directives:

.. math::
   :label: mass-energy-rst

   E = m c^2

Equation :eq:`mass-energy-rst` is rendered as native MathML and retains the
normal Sphinx permalink and reference behavior.

𝐸 = 𝑚 𝑐^{2}

Equation (2) is rendered as native MathML and retains the normal Sphinx permalink and reference behavior.

Shared definitions¶

The demonstration configuration defines an expectation helper in typst_math_preamble in conf.py:

typst_math_preamble = r"""
#let expectation(x) = $upright(E) lr([#x])$
"""

It is available in every Markdown page and notebook:

$$
expectation(X) = integral_(-infinity)^infinity x f(x) dif x
$$

E [𝑋] = \int_{- \infty}^{\infty} 𝑥 𝑓 (𝑥) d 𝑥

See Typst package examples for physica, MiTeX, and quick-maths, or open the nbsphinx notebook to see the same renderer used from Jupyter Markdown cells.

Note

The JupyterLab live preview normally uses MathJax and may not understand native Typst syntax. The rendered notebook page produced by nbsphinx and Sphinx is the authoritative preview for these equations.