README.md
1[][Travis]
2
3[Travis]: https://travis-ci.org/mitya57/python-markdown-math
4
5Math extension for Python-Markdown
6==================================
7
8This extension adds math formulas support to [Python-Markdown].
9
10[Python-Markdown]: https://github.com/Python-Markdown/markdown
11
12Installation
13------------
14
15### Install from PyPI
16
17```
18$ pip install python-markdown-math
19```
20
21### Install locally
22
23Use `setup.py build` and `setup.py install` to build and install this
24extension, respectively.
25
26The extension name is `mdx_math`, so you need to add that name to your
27list of Python-Markdown extensions.
28Check [Python-Markdown documentation] for details on how to load
29extensions.
30
31[Python-Markdown documentation]: https://python-markdown.github.io/reference/#extensions
32
33Usage
34-----
35
36To use this extension, you need to include [MathJax] library in HTML files, like:
37
38```html
39<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js">
40</script>
41```
42
43[MathJax]: https://www.mathjax.org/
44
45Also, you need to specify a configuration for MathJax. Please note that
46most of standard configurations include `tex2jax` extension, which is not needed
47with this code.
48
49Example of configuration for MathJax 2.x:
50
51```html
52<script type="text/x-mathjax-config">
53MathJax.Hub.Config({
54 config: ["MMLorHTML.js"],
55 jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"],
56 extensions: ["MathMenu.js", "MathZoom.js"]
57});
58</script>
59```
60
61If you want to use MathJax 3.x, you need to teach it to understand 2.x-style
62`<script>` tags. See the [upgrading documentation] on how to do it.
63Alternatively, you may use the [Arithmatex] extension which has a generic
64output mode, that does not require such special configuration.
65
66To pass the extension to Python-Markdown, use `mdx_math` as extension name.
67For example:
68
69```python
70>>> md = markdown.Markdown(extensions=['mdx_math'])
71>>> md.convert('$$e^x$$')
72'<p>\n<script type="math/tex; mode=display">e^x</script>\n</p>'
73```
74
75Usage from the command line:
76
77```
78$ echo "\(e^x\)" | python3 -m markdown -x mdx_math
79<p>
80<script type="math/tex">e^x</script>
81</p>
82```
83
84[upgrading documentation]: https://docs.mathjax.org/en/latest/upgrading/v2.html#math-script-example
85[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
86
87Math Delimiters
88---------------
89
90For inline math, use `\(...\)`.
91
92For standalone math, use `$$...$$`, `\[...\]` or `\begin...\end`.
93
94The single-dollar delimiter (`$...$`) for inline math is disabled by
95default, but can be enabled by passing `enable_dollar_delimiter=True`
96in the extension configuration.
97
98If you want to use [GitLab-style delimiters] (``$`...`$`` for inline math,
99and a code block-like `` ```math...``` `` syntax for standalone), use
100`use_gitlab_delimiters=True` configuration option.
101
102If you want to this extension to generate a preview node (which will be shown
103when MathJax has not yet processed the node, or when JavaScript is unavailable),
104use `add_preview=True` configuration option.
105
106[GitLab-style delimiters]: https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math
107
108Notes
109-----
110
111If you use [ReText](https://github.com/retext-project/retext), this extension
112is not needed as it is included by default.
113
114This extension also works with Katex. Use the following in your page `<head>`:
115
116```html
117<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css" crossorigin="anonymous">
118<script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js" crossorigin="anonymous"></script>
119<script src="https://cdn.jsdelivr.net/npm/katex/dist/contrib/mathtex-script-type.min.js" defer></script>
120```
121
){kind=link}