Skip to main content

Python-Markdown extension to escape math expressions like $2\pi$

Project description



Python-Markdown extension to escape math expressions like $e^{i\pi} + 1 = 0$.


The benefits of using this extension are:

  1. No special escaping syntax is needed
    • You can write \left\{, not \left\\{.
  2. On writing, you are free to choose any delimiter style as you like
    • They will be converted to "brackets" styled delimiters so that they can be processed using MathJax or KaTeX without any configuration.
    • If you are using GitLab, you can choose gitlab delimiter style so that the file will be rendered with beautiful mathematics on GitLab.
  3. It's fast
    • This extension does not render mathematics

On the other hand:

  • You need to setup either MathJax or KaTeX for client-side rendering
    • If you are using Nikola, you can use it's built-in feature to enable them
    • Otherwise, somehow you need to load and execute one of them (using a theme which supports them, for example)

Technically, this extension firstly protects math expressions from Python-Markdown and its other extensions so that no unexpected (unhappy) change will happen. Then it converts their delimiters (enclosing special characters) to "brackets" styled delimiters... which is supported by default configuration of MathJax and KaTeX.


Firstly, install the extension by the command below:

pip install markdown_math_escape

Secondly, you need to let Python-Markdown to use it. How to do it depends on how you are using Python-Markdown. Please see examples for an example which matches your usage.


The only available option is "delimiters" which specifies the type of delimiters enclosing mathematics in your markdown files. See the table below for supported values.

delimiters Inline (non-display mode) Display mode math
dollers $e^{i\pi} + 1 = 0$
e^{i\pi} + 1 = 0
brackets \(e^{i\pi} + 1 = 0\)
e^{i\pi} + 1 = 0
gitlab $`e^{i\pi} + 1 = 0`$
e^{i\pi} + 1 = 0


Python script

If you are using Python-Markdown directly in your Python script (or library), just do so in the standard way. For example:

import markdown as md
from markdown_math_escape import MathEscapeExtension


Please refer to the Python-Markdown's document for more details.


If you are using Python-Markdown as part of Pelican, you can use extension name markdown_math_escape. For example:

    'extension_configs': {
        # ...other extensions...
        "markdown_math_escape": {"delimiters": "dollers"},

Please refer to the Pelican's document for more details.


If you are using Python-Markdown as part of Nikola, you can use extension name markdown_math_escape. For example:

    # ...other extensions...

        "markdown_math_escape": {"delimiters": "dollers"},

Note that this extension is compatible with Nikola's built-in option to enable MathJax or KaTeX. Just set has_math metadata field in your post to true and select MathJax or KaTeX by specifying USE_KATEX value in

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markdown_math_escape- (6.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page