PyMdown Extensions¶

PyMdown Extensions is a collection of extensions for Python Markdown that adds a wealth of features to enhance your documentation. Material for MkDocs integrates seamlessly with these extensions.

Overview¶

PyMdown Extensions provides over 30 extensions that add features like:

Enhanced code blocks with line highlighting and annotations
Content tabs for organizing related information
Task lists with checkboxes
Emoji support
Mathematical notation with LaTeX
Keyboard keys Ctrl+C
Critic markup for tracking changes
And much more!

Code and Highlighting¶

Highlight¶

Enhanced code blocks with line numbers and highlighting:

def hello_world():
    # This line is highlighted
    print("Hello, World!")
    return True

InlineHilite¶

Inline code highlighting: print("Hello") or console.log("Hi")

SuperFences¶

Nested code blocks and custom fences:

```python
print("Regular code block")
```

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

Content Organization¶

Tabbed Content¶

PythonJavaScriptRuby

def greet(name):
    return f"Hello, {name}!"

function greet(name) {
    return `Hello, ${name}!`;
}

def greet(name)
  "Hello, #{name}!"
end

Details (Collapsible Sections)¶

Click to expand

This content is hidden by default and can be expanded by clicking.

It's great for: - Optional information - Advanced details - Lengthy examples

Expanded by default

This section starts expanded but can be collapsed.

Snippets¶

The snippets extension allows including content from other files. For example, all abbreviations on this page are automatically included from a central file.

Text Formatting¶

Caret, Mark, and Tilde¶

Superscript text with ^^text^^
~~Subscript~~ text with ~~text~~
Highlighted text with ==text==
~~Strikethrough~~ with ~~text~~
_Subscript with ~text~

Smart Symbols¶

Smart quotes and symbols are automatically converted:

© becomes ©
™ becomes ™
® becomes ®
→ becomes →
← becomes ←
==> becomes ⇒

Critic¶

Track changes in your documentation:

Addition
~~Deletion~~
~~Old~~New
Highlight
Comment

Keys¶

Keyboard shortcuts: Ctrl+Alt+Del, Cmd+Shift+P, Space, Tab

Lists and Tasks¶

Task Lists¶

Special Features¶

Emoji¶

Use standard emoji codes or shortcodes:

:smile:
:heart:
:rocket:
:python: :python:
:material-language-python:

MagicLink¶

Auto-linking for:

URLs: https://www.mkdocs.org
Email: example@domain.com
GitHub references: python/cpython#1234
Repository mentions: @facelessuser

Arithmatex¶

Mathematical notation with LaTeX:

\[ \frac{n!}{k!(n-k)!} = \binom{n}{k} \]

Inline math: \(p(x|y) = \frac{p(y|x)p(x)}{p(y)}\)

Configuration Examples¶

Basic Setup¶

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

Advanced Configuration¶

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Best Practices¶

1. Choose Relevant Extensions¶

Don't enable every extension—choose those that add value to your documentation:

Technical docs: highlight, superfences, arithmatex
Tutorials: tabbed, tasklist, keys
Collaborative docs: critic, details

2. Configure Consistently¶

Maintain consistent configuration across your documentation:

# Consistent slug generation
- pymdownx.tabbed:
    slugify: !!python/object/apply:pymdownx.slugs.slugify
      kwds:
        case: lower

3. Test Compatibility¶

Some extensions may conflict. Test thoroughly when adding new extensions.

4. Document Usage¶

Create a style guide for your team showing how to use enabled extensions.

Common Use Cases¶

API Documentation¶

def process_data(data: list[dict]) -> dict:
    """Process the input data.

    Args:
        data: List of dictionaries to process

    Returns:
        Processed data as a dictionary
    """
    return {"processed": len(data)}

Multi-Language Examples¶

cURLPythonJavaScript

curl -X GET https://api.example.com/users \
  -H "Authorization: Bearer TOKEN"

import requests

response = requests.get(
    "https://api.example.com/users",
    headers={"Authorization": "Bearer TOKEN"}
)

fetch('https://api.example.com/users', {
  headers: {
    'Authorization': 'Bearer TOKEN'
  }
})

Keyboard Shortcuts Documentation¶

Action	Windows/Linux	macOS
Copy	`Ctrl`+`C`	`Cmd`+`C`
Paste	`Ctrl`+`V`	`Cmd`+`V`
Save	`Ctrl`+`S`	`Cmd`+`S`
Undo	`Ctrl`+`Z`	`Cmd`+`Z`