Pymdown Extensions

10.21.2 · active · verified Tue Mar 31

Pymdown Extensions is an extension pack for Python Markdown, offering a comprehensive collection of features to enhance Markdown rendering. It provides over 30 extensions for capabilities such as enhanced code blocks with highlighting, content tabs, emoji support, and mathematical notation. Currently at version 10.21.2, the library is actively developed with a consistent release cadence.

Warnings

breaking The 'Critic' extension's `view` mode was deprecated in version 10.18 and is slated for future removal. Users should explicitly set `mode` to either `accept` or `reject` to avoid warnings and ensure future compatibility.
Fix: Update Critic extension configuration to use `mode: accept` or `mode: reject` instead of `view`.
gotcha The 'Highlight' extension, prior to version 10.21.2, had issues handling `None` as a filename for code block titles, leading to potential errors with newer Pygments versions.
Fix: Upgrade to version 10.21.2 or later. Ensure a string is always provided for `filename` if custom titles are used.
gotcha The new 'Quotes' extension (introduced in 10.20) handles blockquote grouping differently than Python Markdown's default, following a more modern parsing approach. This may change expected behavior if migrating from the default blockquote parsing.
Fix: Review documentation for the 'Quotes' extension, especially regarding its grouping behavior, and adjust content or expectations if coming from Python Markdown's default blockquote parsing.
gotcha A bug in 'Arithmatex' prior to 10.19.1 could cause incorrect parsing of block math (`$$`) when used inline within a paragraph, resulting in nested math parsing issues.
Fix: Upgrade to version 10.19.1 or later to resolve the nested math parsing issue.

Install

pip install pymdown-extensions Install latest version

Imports

markdown.Markdown
```
import markdown
html = markdown.Markdown(extensions=['pymdownx.superfences', 'pymdownx.highlight']).convert(md_text)
```
Pymdown Extensions are loaded by their module name (e.g., 'pymdownx.superfences') into the `extensions` list of `markdown.Markdown`.

Quickstart

Initialize a Markdown converter with `pymdown-extensions` by listing their names (e.g., `pymdownx.superfences`, `pymdownx.highlight`) in the `extensions` argument. The example demonstrates basic Markdown conversion with code block highlighting and emoji support.

import markdown

md_text = '''
# Hello Pymdown!

This is a simple markdown with `inline code`.

```python
# SuperFences and Highlight example
def greet(name):
    print(f"Hello, {name}!")

greet("World")
```
''')

# To use Pymdown Extensions, pass their names (prefixed with 'pymdownx.')
# to the 'extensions' argument of markdown.Markdown.
# 'superfences' allows nested code blocks, and 'highlight' provides syntax highlighting.
html = markdown.Markdown(
    extensions=[
        'pymdownx.superfences',
        'pymdownx.highlight',
        'pymdownx.emoji'
    ]
).convert(md_text)

print(html)

view raw JSON →