sphinx-math-dollar

sphinx-math-dollar is a Sphinx extension to let you write LaTeX math in RST using $$.

To enable install it

pip install sphinx-math-dollar

conda install -c conda-forge sphinx-math-dollar

Then in your conf.py, add 'sphinx_math_dollar' to your extensions list:

extensions = ['sphinx_math_dollar', 'sphinx.ext.mathjax']

mathjax_config = {
    'tex2jax': {
        'inlineMath': [ ["\\(","\\)"] ],
        'displayMath': [["\\[","\\]"] ],
    },
}

mathjax3_config = {
  "tex": {
    "inlineMath": [['\\(', '\\)']],
    "displayMath": [["\\[", "\\]"]],
  }
}

The mathjax_config is needed to prevent MathJax from parsing dollar signs which are ignored by the extension because they should not be parsed as math.

You will now be able to use dollar signs for math, like $\int\sin(x)\,dx$, which will produce $intsin(x),dx$. You can also use double dollar signs for display math, like $$\int\sin(x)\,dx$$, which produces $$intsin(x),dx$$ (if you are reading this on GitHub, look at the version built by Sphinx here). The usual Sphinx :math: and .. math:: directives will also continue to work.

The extension will also work with docstrings when combined with the sphinx.ext.autodoc extension.

Configuration

sphinx-math-dollar uses a blacklist to determine which docutils nodes should not be parsed. The default blacklist is

(FixedTextElement, literal, math)

FixedTextElement covers the Simple Body Elements nodes.

Any docutils node that is contained in a blacklisted node or a subclass of a blacklisted node will not have $math$ parsed as LaTeX.

You can modify this by setting math_dollar_node_blacklist in conf.py. For example, to also prevent $math$ from rendering in headers nodes, add

from sphinx_math_dollar import NODE_BLACKLIST
from docutils.nodes import header

math_dollar_node_blacklist = NODE_BLACKLIST + (header,)

Note that configuring this variable replaces the default, so it is recommended to always include the above default values (NODE_BLACKLIST) in addition to additional nodes.

To debug which nodes are skipped, set the environment variable MATH_DOLLAR_DEBUG=1 or set math_dollar_debug = True in conf.py.

If you feel a node should always be part of the default blacklist, please make a pull request.

Known Issues

See the issue tracker for a full list of known issues.

Absolute values can produce errors like Inline substitution_reference start-string without end-string.. See issue #16.

This is because Sphinx parses the vertical bars |x| as inline substitutions. To work around this, add spaces around the absolute value bars, like 1 + | x | + y. If an absolute value bar is at the beginning or end of the math expression, use curly braces (to avoid false positives, sphinx-math-dollar will not parse dollar signs as math if there is a space after the first $ or before the last $). For example, replace $|y| \geq |x^e|$ with ${ | y | \geq | x^e | }$, which produces ${ | y | geq | x^e | }$.

Markdown

sphinx-math-dollar is designed to work with RST, which does not natively support dollar signs for LaTeX math. If you prefer Markdown, we recommend using [MyST](https://myst-parser.readthedocs.io/en/latest/), which natively supports dollar math (this extension is not required).

License

MIT.

Metadata

Release files for sphinx-math-dollar 1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-math-dollar 1.3
File	Size	Uploaded
sphinx_math_dollar-1.3.tar.gz	27.2 kB	Feb 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sphinx-math-dollar 1.3
File	Interpreter	ABI	Platform	Reset
sphinx_math_dollar-1.3-py3-none-any.whl 7.5 kB Feb 5, 2026	Python 3	none	any	Details

Total release size: 34.7 kB

Release files / sphinx_math_dollar-1.3.tar.gz

Download URL	sphinx_math_dollar-1.3.tar.gz
Size	27.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`9e18e9ed398c9e556eab74eef9333f7a0b39a8c176988b61aedecd085336a20f`
BLAKE2b-256 checksum How to use checksums	`b113beff9449bf32affac2cecac33962bc799344fe960c2c49f570ed66361952`
Upload date	Feb 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Release files / sphinx_math_dollar-1.3-py3-none-any.whl

Download URL	sphinx_math_dollar-1.3-py3-none-any.whl
Size	7.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`85211b21a547cdce97a684a0c91936efded7b30a2e142de2dd89124e4ba8e34f`
BLAKE2b-256 checksum How to use checksums	`b1090ab0853d6d634455fe70d90a306162160ead7592eceaca194168a16d3beb`
Upload date	Feb 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`