Skip to content

PyMdown Extensions Showcase

This page demonstrates all PyMdown Extensions features in action. Use it as a reference for syntax and capabilities.

Code Features

Syntax Highlighting with Line Numbers

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import asyncio
import aiohttp

async def fetch_data(url):
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

# Highlighted line showing usage
data = await fetch_data("https://api.example.com/data")

Inline Code Highlighting

The range() function returns a sequence of numbers. In JavaScript, use Array.from() instead.

Code Annotations

def calculate_area(radius):
    """Calculate the area of a circle."""
    return 3.14159 * radius ** 2  # (1)!
  1. Using an approximation of π. For more precision, use math.pi.

Content Organization

Tabbed Content Examples

mkdocs.yml
theme:
  name: material
  features:
    - content.code.copy
    - content.tabs.link

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

The tabs you're looking at right now!

Grouped Tabs

#include <stdio.h>

int main() {
    printf("Hello, World!\n");
    return 0;
}

#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

fun main() {
    println("Hello, World!")
}

Collapsible Sections

Database Connection Details

Host: localhost
Port: 5432
Database: myapp_db
Username: app_user

SELECT * FROM users WHERE active = true;
Important Security Note

Always use environment variables for sensitive configuration:

import os

DATABASE_URL = os.getenv('DATABASE_URL')
API_KEY = os.getenv('API_KEY')
Deprecated Feature

This feature will be removed in version 3.0. Please migrate to the new API.

Text Formatting

Basic Formatting

  • Highlighted text for emphasis
  • Superscript for exponents: x^2^ + y^2^ = z^2^
  • Subscript for chemical formulas: H~2~O
  • Added text for additions
  • Deleted text for deletions
  • Old textNew text for replacements
  • Important textWith a comment

Smart Symbols

  • Copyright: © 2024
  • Trademark: MkDocs™
  • Registered: Material®
  • Arrows: → ← > <
  • Ellipsis: ...
  • Fractions: ½, ¼, ¾

Lists and Tasks

Task Lists

Project Setup: - [x] Install MkDocs - [x] Configure Material theme - [x] Add PyMdown Extensions - [ ] Write documentation - [x] Create structure - [ ] Add content - [ ] Review and edit

Features to Implement: - [ ] Search functionality - [ ] Dark mode toggle - [ ] PDF export - [ ] Multi-language support

Definition Lists

MkDocs
A fast, simple static site generator for building documentation
Material for MkDocs
A Material Design theme for MkDocs with many built-in features
PyMdown Extensions
A collection of extensions for Python Markdown
Adds many useful features for technical documentation

Special Features

Emoji Support

  • Standard emoji: 😄 ❤ 🚀 🎉 💯
  • Material icons:
  • FontAwesome:
  • Octicons:

Keyboard Keys

Common shortcuts:

  • Save: Ctrl+S (Windows/Linux) or Cmd+S (macOS)
  • Copy: Ctrl+C or Cmd+C
  • Paste: Ctrl+V or Cmd+V
  • Undo: Ctrl+Z or Cmd+Z
  • Select all: Ctrl+A or Cmd+A
  • Find: Ctrl+F or Cmd+F

Special keys: Esc, Tab, Caps Lock, Shift, Ctrl, Alt, Cmd, Fn

Mathematical Notation

Inline math: The quadratic formula is \(x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\)

Block equations:

\[ \begin{align} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &= \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} &= 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} &= \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} &= 0 \end{align} \]

Tables with Alignment

Feature Description Status
Tabs Organize content ✅
Highlighting Emphasize code ✅
Task lists Track progress ✅
Math LaTeX support ✅

Footnotes

MkDocs1 uses Python-Markdown2 with various extensions to process content. PyMdown Extensions3 adds even more features.

Advanced Examples

Nested Admonitions

Configuration Options

You can nest different types of content:

Pro Tip

Use nested admonitions sparingly to avoid overwhelming readers.

# Example configuration
config = {
    "nested": True,
    "max_depth": 2
}

Complex Code Examples

def create_documentation():
    """Generate documentation with nested code blocks."""

    markdown_content = '''
    ## Example Section

    ```python
    # This is a code block within a code block
    def nested_function():
        return "Hello from nested code!"
    ```

    More content here...
    '''

    return markdown_content

Mermaid Diagrams

graph TD
    A[Start] --> B{Choose Extension}
    B -->|Code| C[Highlight/SuperFences]
    B -->|Content| D[Tabbed/Details]
    B -->|Text| E[Caret/Mark/Tilde]
    B -->|Special| F[Emoji/Keys/Math]
    C --> G[Enhanced Documentation]
    D --> G
    E --> G
    F --> G

Best Practices Summary

Do's

  • ✅ Use appropriate extensions for your content type
  • ✅ Configure extensions consistently
  • ✅ Test all features before deployment
  • ✅ Document custom configurations

Don'ts

  • ❌ Enable all extensions unnecessarily
  • ❌ Nest content too deeply
  • ❌ Overuse formatting features
  • ❌ Ignore performance impacts

Remember: With great power comes great responsibility. Use these extensions to enhance readability, not to show off! 😉

  1. MkDocs is a static site generator focused on documentation ↩

  2. Python-Markdown is a Python implementation of John Gruber's Markdown ↩

  3. Created by Isaac Muse, PyMdown Extensions enhances Markdown capabilities ↩