Math support for HTML outputs in Sphinx¶
Added in version 0.5.
Distinto en la versión 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¶
The output image format. The default is
'png'
. It should be either'png'
or'svg'
. The image is produced by first executinglatex
on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.
- imgmath_use_preview¶
dvipng
anddvisvgm
both have the ability to collect from LaTeX the «depth» of the rendered math: an inline image should use this «depth» in avertical-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 isFalse
but it is strongly recommended to set it toTrue
.Distinto en la versión 2.2: This option can be used with the
'svg'
imgmath_image_format
.
- imgmath_add_tooltips¶
Default:
True
. If false, do not add the LaTeX code as an «alt» attribute for math images.
- imgmath_font_size¶
The font size (in
pt
) of the displayed math. The default value is12
. It must be a positive integer.
- imgmath_latex¶
The command name with which to invoke LaTeX. The default is
'latex'
; you may need to set this to a full path iflatex
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.Consejo
To use OpenType Math fonts with
unicode-math
, via a customimgmath_latex_preamble
, you can setimgmath_latex
to'dvilualatex'
, but must then setimgmath_image_format
to'svg'
. Note: this has only been tested withdvisvgm 3.0.3
. It significantly increases image production duration compared to using standard'latex'
with traditional TeX math fonts.Consejo
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.Distinto en la versión 6.2.0: Using
'xelatex'
(or a full path to it) is now supported. But you must then add'-no-pdf'
to theimgmath_latex_args
list of the command options. The'svg'
imgmath_image_format
is required. Also, you may need thedvisvgm
binary to be relatively recent (testing was done only with its3.0.3
release).Nota
Regarding the previous note, it is currently not supported to use
latexmk
with option-xelatex
.
- imgmath_latex_args¶
Additional arguments to give to latex, as a list. The default is an empty list.
- imgmath_latex_preamble¶
Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. This is left empty by default. 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¶
The command name to invoke
dvipng
. The default is'dvipng'
; you may need to set this to a full path ifdvipng
is not in the executable search path. This option is only used whenimgmath_image_format
is set to'png'
.
- imgmath_dvipng_args¶
Additional arguments to give to dvipng, as a list. The default value is
['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
which makes the image a bit darker and larger then 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 whenimgmath_image_format
is'png'
.
- imgmath_dvisvgm¶
The command name to invoke
dvisvgm
. The default is'dvisvgm'
; you may need to set this to a full path ifdvisvgm
is not in the executable search path. This option is only used whenimgmath_image_format
is'svg'
.
- imgmath_dvisvgm_args¶
Additional arguments to give to dvisvgm, as a list. The default value is
['--no-fonts']
, which means thatdvisvgm
will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only whenimgmath_image_format
is'svg'
.
- imgmath_embed¶
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¶
Advertencia
Version 4.0 changes the version of MathJax used to version 3. You may need to
override mathjax_path
to
https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML
or update your configuration options for version 3
(see mathjax3_config
).
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.
- mathjax_path¶
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.
- mathjax_options¶
The options to script tag for mathjax. For example, you can set integrity option with following setting:
mathjax_options = { 'integrity': 'sha384-......', }
The default is empty (
{}
).Added in version 1.8.
Distinto en la versión 4.4.1: Allow to change the loading method (async or defer) of MathJax if «async» or «defer» key is set.
- mathjax3_config¶
The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable
window.MathJax
. For more information, please read Configuring MathJax.The default is empty (not configured).
Added in version 4.0.
- mathjax2_config¶
The configuration options for MathJax v2 (which can be loaded via
mathjax_path
). The value is used as a parameter ofMathJax.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'], }
The default is empty (not configured).
Added in version 4.0:
mathjax_config
has been renamed tomathjax2_config
.
- mathjax_config¶
Former name of
mathjax2_config
.For help converting your old MathJax configuration to to the new
mathjax3_config
, see Converting Your v2 Configuration to v3.Added in version 1.8.
Distinto en la versión 4.0: This has been renamed to
mathjax2_config
.mathjax_config
is still supported for backwards compatibility.
sphinx.ext.jsmath
– Render math via JavaScript¶
This extension works just as the MathJax extension does, but uses the older package jsMath. It provides this config value:
- jsmath_path¶
The path to the JavaScript file to include in the HTML files in order to load JSMath. There is no default.
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.