mmdc - Mermaid Diagram Converter

A Python tool for converting Mermaid diagrams to SVG, PNG, and PDF using PhantomJS (via phasma) - the only dependency needed. Unlike other tools, mmdc works completely offline without requiring browsers, drivers, npm, or nodejs installations. It's a faithful Python port of mermaid.js that allows you to run exactly the same Mermaid code with full CLI and Python API functionality. Perfect for automating diagram generation in documentation pipelines, CI/CD workflows, and static site generation.

Features

• No Browser/Driver Dependencies: Works completely without external browsers or drivers like Chrome/Chromium
• No NPM/Node.js Required: Unlike other tools, no need to install npm, nodejs or any JavaScript runtime
• Powered by Phasma: Uses the Phasma package as the only dependency to interface with PhantomJS, providing a pure Python solution
• Direct Mermaid.js Port: A faithful Python port of mermaid.js - use exactly the same Mermaid code
• Completely Offline: Run Mermaid diagrams locally without any internet connection or external dependencies
• Command Line Interface: CLI functionality similar to mmdc in mermaid-cli for easy automation
• Python API: Full-featured Python API for integration into your Python applications
• Multiple Output Formats: Convert Mermaid diagrams to SVG, PNG, and PDF
• Multiple Diagram Types: Supports flowcharts, sequence diagrams, Gantt charts, pie charts, and more
• Configurable Options: Set custom timeouts, dimensions, resolution, background colors, and CSS styling
• Comprehensive Testing: Fully tested with parametrized tests covering various scenarios
• Unique Differentiation: Unlike other packages on PyPI, provides a complete solution without external dependencies

Installation

From PyPI

pip install mmdc

From Source

pip install git+https://github.com/MohammadRaziei/mmdc.git

Usage

Command Line Interface

Convert a Mermaid file to SVG:

mmdc --input diagram.mermaid --output diagram.svg

Convert to PNG or PDF (output format determined by file extension):

# Convert to PNG
mmdc --input diagram.mermaid --output diagram.png

# Convert to PDF
mmdc --input diagram.mermaid --output diagram.pdf

With custom timeout (in seconds):

mmdc --input diagram.mermaid --output diagram.svg --timeout 60

Enable verbose logging:

mmdc --input diagram.mermaid --output diagram.svg --verbose

Python API

Basic Conversion

from mmdc import MermaidConverter
from pathlib import Path

converter = MermaidConverter()

# Convert a diagram (output format determined by file extension)
converter.convert(
    input=Path("diagram.mermaid"),
    output_file=Path("diagram.svg")  # or .png or .pdf
)

Direct Format Conversion

from mmdc import MermaidConverter
from pathlib import Path

converter = MermaidConverter()

# Convert to SVG string
svg_content = converter.to_svg("graph TD\n  A --> B")

# Convert to SVG file
converter.to_svg("graph TD\n  A --> B", output_file=Path("output.svg"))

# Convert to PNG bytes
png_bytes = converter.to_png("graph TD\n  A --> B")

# Convert to PNG file
converter.to_png("graph TD\n  A --> B", output_file=Path("output.png"))

# Convert to PDF bytes
pdf_bytes = converter.to_pdf("graph TD\n  A --> B")

# Convert to PDF file
converter.to_pdf("graph TD\n  A --> B", output_file=Path("output.pdf"))

Advanced Options

from mmdc import MermaidConverter

converter = MermaidConverter(timeout=60)  # Set timeout to 60 seconds

# Convert with custom styling and dimensions
converter.to_svg(
    input="graph TD\n  A --> B",
    output_file=Path("styled.svg"),
    css=".node { fill: #ff0000; }"
)

# Convert PNG with custom dimensions and background
converter.to_png(
    input="graph TD\n  A --> B",
    output_file=Path("custom.png"),
    width=800,
    height=600,
    background="#FFFFFF",
    css=".node { fill: #00ff00; }"
)

# Convert PDF with custom resolution
converter.to_pdf(
    input="graph TD\n  A --> B",
    output_file=Path("high_res.pdf"),
    resolution=150,
    background="#000000"
)

Examples

Basic Flowchart

Create a file flowchart.mermaid:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Convert to different formats:

# To SVG
mmdc --input flowchart.mermaid --output flowchart.svg

# To PNG
mmdc --input flowchart.mermaid --output flowchart.png

# To PDF
mmdc --input flowchart.mermaid --output flowchart.pdf

Sequence Diagram

Create a file sequence.mermaid:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I'm good thanks!

Convert to different formats:

mmdc --input sequence.mermaid --output sequence.png

Gantt Chart

Create a file gantt.mermaid:

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1, 20d
    section Another
    Task in sec      :2014-01-12, 12d
    another task     :24d

Convert with custom timeout for complex diagrams:

mmdc --input gantt.mermaid --output gantt.pdf --timeout 60

Testing

The project includes comprehensive tests using pytest. Run the tests with:

pytest tests/ -v

Or use the hatch test environment:

hatch run test

Test Coverage

Tests cover:

• Various Mermaid diagram types (flowcharts, sequence diagrams, Gantt charts, pie charts)
• Different output formats (SVG, PNG, PDF)
• Different timeout values
• Error cases (non-existent files, empty diagrams)
• Special characters in diagrams
• Custom styling with CSS
• Custom dimensions and background colors
• Integration with the command line interface

How It Works

mmdc uses PhantomJS via the Phasma Python package - the only dependency needed - to render Mermaid diagrams completely offline, without requiring external browsers, drivers, npm, or nodejs installations. This makes it a pure Python solution that's a faithful port of mermaid.js. The process:

1. Template Preparation: Uses embedded HTML/JavaScript templates in mmdc/assets/
2. Diagram Rendering: PhantomJS loads the Mermaid library and renders the diagram
3. Output Generation: The rendered diagram is converted to the requested format (SVG, PNG, or PDF)

This approach differentiates mmdc from other packages on PyPI by providing a complete solution without external dependencies, allowing you to run exactly the same Mermaid code offline with both CLI and Python API functionality.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code passes all tests and follows the project's coding standards.

License

mmdc is distributed under the terms of the MIT license.

Acknowledgments

• Mermaid.js for the amazing diagramming library
• Phasma for the PhantomJS Python integration that enables our pure Python solution without external dependencies
• PhantomJS for headless browser capabilities that allow offline processing

Support

If you encounter any problems or have questions, please open an issue on GitHub.