Skip to content

PyMdown Extensions

Extended Markdown features for enhanced documentation.

Core Attributes

Package Name

pymdown-extensions

Repository

https://github.com/facelessuser/pymdown-extensions

Installation

Bash
pip install pymdown-extensions

What It Does

PyMdown Extensions is a collection of Markdown extensions that add powerful features like syntax highlighting, admonitions, tabbed content, math support, and much more.

Enabled Extensions

Admonition

Create callout boxes:

Note

This is a note admonition.

Custom Title

This is a warning with custom title.

Danger

This is a danger alert!

Tip

This is a helpful tip.

Success

Operation successful!

Collapsible Admonitions

Click to expand

This content is hidden by default.

Expanded by default

This content is shown by default but can be collapsed.

Highlight

Code highlighting with advanced features:

Python
def example():
    # This line is highlighted
    # This line too
    return True

SuperFences

Advanced code blocks with custom fences:

Markdown
```python title="example.py"
def hello():
    print("Hello, World!")
```

Tabbed

Create tabbed content:

Content for tab 1

Content for tab 2

Content for tab 3

Task Lists

Create checklists:

  • Completed task
  • Another completed task
  • Pending task
  • Another pending task

Keys

Display keyboard shortcuts:

Press Ctrl+C to copy and Ctrl+V to paste.

Use Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows/Linux.

Arithmatex (Math)

Inline math: \(E = mc^2\)

Block math:

\[ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \]

BetterEm

Smart emphasis handling:

This is italic and bold and both.

Caret

Insert and superscript:

Inserted text

x2 + y2 = z2

Mark

Highlight text:

This text is highlighted

Tilde

Delete and subscript:

Deleted text

H2O is water

Details

Collapsible sections:

Click to expand details

Hidden content here.

Can contain multiple paragraphs.

Snippets

Include external files:

Markdown
*[API]: Application Programming Interface
*[CLI]: Command Line Interface
*[CSS]: Cascading Style Sheets
*[HTML]: HyperText Markup Language
*[HTTP]: HyperText Transfer Protocol
*[HTTPS]: HyperText Transfer Protocol Secure
*[JSON]: JavaScript Object Notation
*[MkDocs]: Markdown Documentation
*[REST]: Representational State Transfer
*[UI]: User Interface
*[URL]: Uniform Resource Locator
*[YAML]: YAML Ain't Markup Language
*[SQL]: Structured Query Language
*[SVG]: Scalable Vector Graphics

SmartSymbols

Automatic symbol conversion:

  • ™ becomes ™
  • © becomes ©
  • ® becomes ®
  • → becomes →
  • ← becomes ←

Automatic link conversion:

https://github.com/facelessuser/pymdown-extensions

Configuration Examples

Code Highlighting

YAML
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.superfences

Tabbed Content

YAML
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

Math Support

YAML
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

All Extensions Reference

arithmatex

Math support (LaTeX syntax)

betterem

Improved emphasis handling

caret

Insert and superscript

critic

Critic markup for tracking changes

details

Collapsible details sections

emoji

Emoji support

highlight

Syntax highlighting

inlinehilite

Inline code highlighting

keys

Keyboard key styling

magiclink

Auto-link URLs

mark

Text highlighting

smartsymbols

Smart symbol conversion

snippets

Include external files

superfences

Advanced code blocks

tabbed

Tabbed content

tasklist

Task list support

tilde

Delete and subscript

Best Practices

  1. Use admonitions for important information
  2. Leverage tabs for multi-language examples
  3. Include line numbers for longer code blocks
  4. Use task lists for checklists and todos
  5. Highlight important code lines
  6. Use collapsible sections for optional content