Sphinx

# Math support for HTML outputs in Sphinx

Added in version 0.5.

Changed in version 1.8: Math support for non-HTML builders is integrated to sphinx-core. So mathbase extension is no longer needed.

Since mathematical notation isn’t natively supported by HTML in any way, Sphinx gives a math support to HTML document with several extensions. These use the reStructuredText math `directive` and `role`.

## `sphinx.ext.imgmath` – Render math as images

Added in version 1.4.

This extension renders math via LaTeX and dvipng or dvisvgm into PNG or SVG images. This of course means that the computer where the docs are built must have both programs available.

There are various configuration values you can set to influence how the images are built:

imgmath_image_format
  Type:
    `'png' | 'svg'`
  Default:
    `'png'`

  The output image format. It should be either `'png'` or `'svg'`. The image is produced by first executing `latex` on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.

imgmath_use_preview
  Type:
    `bool`
  Default:
    `False`

  `dvipng` and `dvisvgm` both have the ability to collect from LaTeX the “depth” of the rendered math: an inline image should use this “depth” in a `vertical-align` style to get correctly aligned with surrounding text.

  This mechanism requires the LaTeX preview package (available as `preview-latex-style` on Ubuntu xenial). Therefore, the default for this option is `False` but it is strongly recommended to set it to `True`.

  Changed in version 2.2: This option can be used with the `'svg'` `imgmath_image_format`.

imgmath_add_tooltips
  Type:
    `bool`
  Default:
    `True`

  If false, do not add the LaTeX code as an “alt” attribute for math images.

imgmath_font_size
  Type:
    `int`
  Default:
    `12`

  The font size (in `pt`) of the displayed math. This must be a positive integer.

imgmath_latex
  Type:
    `str`
  Default:
    `'latex'`

  The command name with which to invoke LaTeX. You may need to set this to a full path if `latex` is not in the executable search path.

  Since this setting is not portable from system to system, it is normally not useful to set it in `conf.py`; rather, giving it on the sphinx-build command line via the `-D` option should be preferable, like this:

      sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build

  This value should only contain the path to the latex executable, not further arguments; use `imgmath_latex_args` for that purpose.

  Hint

  To use OpenType Math fonts with `unicode-math`, via a custom `imgmath_latex_preamble`, you can set `imgmath_latex` to `'dvilualatex'`, but must then set `imgmath_image_format` to `'svg'`. Note: this has only been tested with `dvisvgm 3.0.3`. It significantly increases image production duration compared to using standard `'latex'` with traditional TeX math fonts.

  Hint

  Some fancy LaTeX mark-up (an example was reported which used TikZ to add various decorations to the equation) require multiple runs of the LaTeX executable. To handle this, set this configuration setting to `'latexmk'` (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed.

  Changed in version 6.2.0: Using `'xelatex'` (or a full path to it) is now supported. But you must then add `'-no-pdf'` to the `imgmath_latex_args` list of the command options. The `'svg'` `imgmath_image_format` is required. Also, you may need the `dvisvgm` binary to be relatively recent (testing was done only with its `3.0.3` release).

  Note

  Regarding the previous note, it is currently not supported to use `latexmk` with option `-xelatex`.

imgmath_latex_args
  Type:
    `Sequence[str]`
  Default:
    `()`

  Additional arguments to give to latex, as a list.

imgmath_latex_preamble
  Type:
    `str`
  Default:
    `''`

  Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. Use it e.g. to add packages which modify the fonts used for math, such as `'\\usepackage{newtxsf}'` for sans-serif fonts, or `'\\usepackage{fouriernc}'` for serif fonts. Indeed, the default LaTeX math fonts have rather thin glyphs which (in HTML output) often do not match well with the font for text.

imgmath_dvipng
  Type:
    `str`
  Default:
    `'dvipng'`

  The command name to invoke `dvipng`. You may need to set this to a full path if `dvipng` is not in the executable search path. This option is only used when `imgmath_image_format` is set to `'png'`.

imgmath_dvipng_args
  Type:
    `Sequence[str]`
  Default:
    `('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')`

  Additional arguments to give to dvipng, as a list. The default value makes the image a bit darker and larger than it is by default (this compensates somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a transparent background. This option is used only when `imgmath_image_format` is `'png'`.

imgmath_dvisvgm
  Type:
    `str`
  Default:
    `'dvisvgm'`

  The command name to invoke `dvisvgm`. You may need to set this to a full path if `dvisvgm` is not in the executable search path. This option is only used when `imgmath_image_format` is `'svg'`.

imgmath_dvisvgm_args
  Type:
    `Sequence[str]`
  Default:
    `('--no-fonts',)`

  Additional arguments to give to dvisvgm, as a list. The default value means that `dvisvgm` will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only when `imgmath_image_format` is `'svg'`.

imgmath_embed
  Type:
    `bool`
  Default:
    `False`

  If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk.

  Added in version 5.2.

## `sphinx.ext.mathjax` – Render math via JavaScript

Attention

The default version of MathJax changed from version 2 to version 3 in Sphinx 4.0, and from version 3 to version 4 in Sphinx 9.0.

You may need to override `mathjax_path` to load an older version, or update your `configuration options`. In general, MathJax v3 and v4 options are compatible.

Added in version 1.1.

This extension puts math as-is into the HTML files. The JavaScript package MathJax is then loaded and transforms the LaTeX markup to readable math live in the browser.

Because MathJax (and the necessary fonts) is very large, it is not included in Sphinx but is set to automatically include it from a third-party site.

Attention

You should use the math `directive` and `role`, not the native MathJax `$$`, `\(`, etc.

Tip

MathJax configuration can be supplied in a JavaScript file by using the `mathjax_config_path` option. This is useful for more complex configurations that are hard to express only using a Python dictionary, for example JavaScript functions.

mathjax_path
  Type:
    `str`
  Default:
    `'https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js'`

  The path to the JavaScript file to include in the HTML files in order to load MathJax.

  The default is the `https://` URL that loads the JS files from the jsdelivr Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path.

  The path can be absolute or relative; if it is relative, it is relative to the `_static` directory of the built docs.

  For example, if you put MathJax into the static path of the Sphinx docs, this value would be `MathJax/MathJax.js`. If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location.

  You can also give a full `https://` URL different from the CDN URL.

  Changed in version 4.0: The default version of MathJax is now version 3. To keep using MathJax v2, you must explicitly load it via this option. For example:

      mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

  Changed in version 9.0: The default version of MathJax is now version 4. To keep using MathJax v3, you must explicitly load it via this option. For example:

      mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

mathjax_options
  Type:
    `dict[str, Any]`
  Default:
    `{}`

  The options to script tag for mathjax. For example, you can set integrity option with following setting:

      mathjax_options = {
          'integrity': 'sha384-......',
      }

  Added in version 1.8.

  Changed in version 4.4.1: Allow to change the loading method (async or defer) of MathJax if “async” or “defer” key is set.

mathjax4_config
  Type:
    `dict[str, Any] | None`
  Default:
    `None`

  The configuration options for MathJax v4 (which is used by default). The given dictionary is assigned to the JavaScript variable `window.MathJax`. For more information, please read Configuring MathJax.

  For help converting your old MathJax configuration to to the new `mathjax4_config`, see Converting your old Configuration to v4.

  Added in version 9.0.

mathjax3_config
  Type:
    `dict[str, Any] | None`
  Default:
    `None`

  The configuration options for MathJax v3 (which can be loaded via `mathjax_path`). If given, the dictionary is converted to a JSON object and assigned to the JavaScript variable `window.MathJax`.

  For more information, please read Configuring MathJax.

  Added in version 4.0.

mathjax2_config
  Type:
    `dict[str, Any] | None`
  Default:
    `None`

  The configuration options for MathJax v2 (which can be loaded via `mathjax_path`). The value is used as a parameter of `MathJax.Hub.Config()`. For more information, please read Using in-line configuration options.

  For example:

      mathjax2_config = {
          'extensions': ['tex2jax.js'],
          'jax': ['input/TeX', 'output/HTML-CSS'],
      }

  For help converting your old MathJax configuration to to the new `mathjax3_config`, see Converting Your v2 Configuration to v3.

  Added in version 4.0: `mathjax_config` has been renamed to `mathjax2_config`.

mathjax_config
  Type:
    `dict[str, Any] | None`
  Default:
    `None`

  Former name of `mathjax2_config`.

  Added in version 1.8.

  Changed in version 4.0: This has been renamed to `mathjax2_config`. `mathjax_config` is still supported for backwards compatibility.

mathjax_config_path
  Type:
    `str`
  Default:
    `''`

  If given, this must be the path of a JavaScript (`.js`) file (path relative to the configuration directory) that contains the configuration options for MathJax. Example:

      mathjax_config_path = 'mathjax-config.js'

  Important

  The user is responsible for ensuring that the given file is compatible with the version of MathJax being used.

  For more information, please read Configuring MathJax.

  Added in version 9.0.

## `sphinxcontrib.jsmath` – Render math via JavaScript

This extension works just as the MathJax extension does, but uses the older package jsMath. jsMath is no longer actively developed, but it has the advantage that the size of the JavaScript package is much smaller than MathJax.

Added in version 0.5: The `sphinx.ext.jsmath` extension.

Changed in version 2.0: `sphinx.ext.jsmath` was moved to `sphinxcontrib.jsmath`.

Removed in version 4.0: The alias from `sphinx.ext.jsmath` to `sphinxcontrib.jsmath`.

Config value:

jsmath_path
  Type:
    `str`
  Default:
    `''`

  The path to the JavaScript file to include in the HTML files in order to load JSMath.

  The path can be absolute or relative; if it is relative, it is relative to the `_static` directory of the built docs.

  For example, if you put jsMath into the static path of the Sphinx docs, this value would be `jsMath/easy/load.js`. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location.