Skip to content

SuperFences

SuperFences is a powerful PyMdown extension that enhances code blocks with advanced features like nested fences, custom fence processors, and live rendering capabilities.

Overview

SuperFences extends the standard Markdown fenced code blocks with:

  • Nested code blocks - Place code blocks inside other content
  • Custom fence processors - Support for Mermaid diagrams and other languages
  • Syntax highlighting - Advanced highlighting with line numbers
  • Language detection - Automatic language detection
  • Copy button - Easy code copying

Basic Usage

Standard Code Blocks

def hello_world():
    """Simple function example."""
    print("Hello, World!")

Nested Code Blocks

SuperFences allows you to nest code blocks inside other content:

Nested Code Example

Here's how to use nested code blocks:

def process_data(data):
    """Process data with error handling."""
    try:
        result = data.strip().upper()
        return result
    except AttributeError:
        return "Invalid data"

Mermaid Diagrams

SuperFences is configured to render Mermaid diagrams directly in your documentation.

Flowchart Example

flowchart LR
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

Sequence Diagram

sequenceDiagram
    participant User
    participant System
    participant Database

    User->>System: Request Data
    System->>Database: Query
    Database-->>System: Results
    System-->>User: Response

Class Diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    class Cat {
        +String color
        +meow()
    }
    Animal <|-- Dog
    Animal <|-- Cat

Advanced Features

Line Numbers

Enable line numbers for better code reference:

1
2
3
4
5
6
7
8
def calculate_fibonacci(n):
    """Calculate Fibonacci number."""
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

Highlighting Specific Lines

Highlight important lines in your code:

def validate_email(email):
    """Validate email format."""
    if "@" not in email:
        return False
    if "." not in email.split("@")[1]:
        return False
    return True

Title and Line Number Start

Add titles and custom line number starts:

utils/validators.py
42
43
44
45
46
47
48
49
50
def validate_password(password):
    """Check password strength."""
    if len(password) < 8:
        return False
    if not any(c.isupper() for c in password):
        return False
    if not any(c.isdigit() for c in password):
        return False
    return True

Configuration

SuperFences is configured in mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Working with Highlight

SuperFences works seamlessly with the Highlight extension:

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

Live Examples

Interactive Python Example

# This is a live example that demonstrates Python features
import json

data = {
    "name": "MkDocs",
    "type": "Documentation Generator",
    "features": ["Markdown", "Themes", "Plugins"]
}

# Pretty print JSON
print(json.dumps(data, indent=2))

Shell Commands

# Install MkDocs and dependencies
pip install mkdocs-material
pip install pymdown-extensions

# Serve documentation locally
mkdocs serve --dev-addr localhost:8000

Configuration Files

.github/workflows/docs.yml
name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Best Practices

  1. Choose the right diagram type: Use flowcharts for processes, sequence diagrams for interactions
  2. Keep diagrams simple: Complex diagrams are hard to maintain
  3. Use consistent styling: Follow your documentation's visual style
  4. Add descriptions: Explain complex diagrams with text
  5. Test rendering: Verify diagrams render correctly across devices

Browser Compatibility

Mermaid diagrams are rendered using JavaScript and require:

  • Modern browsers with ES6 support
  • JavaScript enabled
  • Sufficient viewport width for complex diagrams

Troubleshooting

Diagrams Not Rendering

  1. Check JavaScript console for errors
  2. Verify Mermaid library is loaded
  3. Ensure proper fence syntax
  4. Check for syntax errors in diagram code

Syntax Highlighting Issues

  1. Verify language identifier is correct
  2. Check Pygments supports the language
  3. Ensure proper indentation
  4. Clear browser cache