mmdc 0.2.0

Python-native Mermaid diagram converter – no browser, Node.js, or npm required. Renders diagrams to SVG using PhantomJS via phasma, perfect for documentation automation and CI/CD pipelines.

mmdc - Mermaid Diagram Converter

A Python tool for converting Mermaid diagrams to SVG using PhantomJS (via phasma). Perfect for automating diagram generation in documentation pipelines, CI/CD workflows, and static site generation.

Features

• Convert Mermaid to SVG: Transform .mermaid files into high-quality SVG images
• Multiple Diagram Types: Supports flowcharts, sequence diagrams, Gantt charts, pie charts, and more
• Command Line & Python API: Use as a CLI tool or import as a Python library
• Configurable Timeout: Set custom timeouts for complex diagrams
• Comprehensive Testing: Fully tested with parametrized tests covering various scenarios
• Logging Support: Built-in logging with verbose mode for debugging

Installation

From PyPI

pip install mmdc

From Source

git clone https://github.com/MohammadRaziei/mmdc.git
cd mmdc
pip install -e .

Usage

Command Line Interface

Convert a Mermaid file to SVG:

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

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

from mmdc import MermaidConverter
from pathlib import Path

converter = MermaidConverter()

# Convert a diagram
success = converter.convert(
    input_file=Path("diagram.mermaid"),
    output_file=Path("diagram.svg"),
    timeout=30  # optional, default is 30 seconds
)

if success:
    print("Conversion successful!")
else:
    print("Conversion failed.")

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 SVG:

mmdc --input flowchart.mermaid --output flowchart.svg

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 SVG:

mmdc --input sequence.mermaid --output sequence.svg

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 timeout values
• Error cases (non-existent files, empty diagrams)
• Special characters in diagrams
• Integration with the command line interface

How It Works

mmdc uses PhantomJS via the phasma Python package to render Mermaid diagrams. 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. SVG Extraction: The rendered SVG is extracted and saved to the output file
4. Cleanup: Temporary files are cleaned up automatically

Development

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/MohammadRaziei/mmdc.git
   cd mmdc
   

2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Run tests:

   pytest tests/ -v
   

Code Quality

The project uses several tools for maintaining code quality:

• Black: Code formatting
• Ruff: Linting
• MyPy: Type checking
• Pytest: Testing with coverage

Run all code quality checks:

hatch run lint:all

Format code:

hatch run lint:fmt

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
• PhantomJS for headless browser capabilities
• phasma for the PhantomJS Python integration

Support

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

---

Made with ❤️ by Mohammad Raziei