Skip to content

MkDocs Mermaid Zoom Plugin

PyPI version License: MIT

A MkDocs plugin that adds zoom, pan, and lightbox functionality to Mermaid diagrams.

✨ Features

  • 🖱️ Click to Open: Click any Mermaid diagram to open it in a lightbox
  • 🔍 Mouse Wheel Zoom: Zoom in/out using your mouse wheel
  • 👆 Drag to Pan: Click and drag to move around large diagrams
  • ⌨️ Keyboard Support: Press ESC to close the lightbox
  • 📱 Responsive: Works on desktop and mobile devices
  • 🎨 All Diagram Types: Supports flowcharts, sequence diagrams, class diagrams, and more

🚀 Installation

Install the plugin using pip:

pip install mkdocs-mermaid-zoom

⚙️ Configuration

Add the plugin to your mkdocs.yml:

plugins:
  - search
  - mermaid-zoom

# Load Mermaid.js manually for compatibility
extra_javascript:
  - assets/javascripts/mermaid.min.js

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

Important Configuration

Critical: Use fence_div_format instead of fence_code_format to ensure proper DOM access for the zoom functionality.

Mermaid.js Setup

Download mermaid.min.js from Mermaid releases and place it in your docs/assets/javascripts/ directory.

📖 How to Use

  1. Add Mermaid diagrams to your markdown files using standard Mermaid syntax
  2. Click on any diagram to open it in a lightbox
  3. Scroll to zoom in/out
  4. Drag to pan around large diagrams
  5. Press ESC or click outside to close

The plugin automatically detects and enhances all Mermaid diagrams on your pages!

🛠️ Requirements

  • Python 3.8+
  • MkDocs 1.4.0+
  • mkdocs-material (recommended)
  • Mermaid.js

📝 License

This project is licensed under the MIT License.