pymeregen

A Python tool for converting Mermaid diagrams to various image formats (SVG, PDF, PNG, JPG) with enhanced typography control.

Features

• Multiple Input Formats: Process Mermaid diagrams from markdown files, HTML divs, or standalone .mmd files
• Batch Processing: Convert multiple files at once using glob patterns
• Multiple Output Formats: Generate SVG, PDF, PNG, or JPG files
• Smart Output Location: By default, outputs files in the same directory as input files
• Font Scaling: Enlarge diagram text by 1-5x for better readability
• High DPI Support: Control resolution for raster formats (PNG/JPG)
• Theme Support: Apply different Mermaid themes (default, dark, forest, neutral)
• Automatic Installation: Installs Mermaid CLI if not present

Installation

Prerequisites

• Python 3.6+
• Node.js and npm (for Mermaid CLI)
• Pillow/PIL (optional, for JPG conversion)

Quick Start

# Clone the repository
git clone <repository-url>
cd merefig

# Make the script executable
chmod +x pymeregen

# The script will auto-install mermaid-cli on first run

Manual Dependencies

If automatic installation fails:

# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli

# Install Pillow for JPG support (optional)
pip install Pillow

Usage

Basic Examples

# Convert a single file to SVG (default)
./pymeregen diagram.mmd

# Convert all markdown files to PDF
./pymeregen *.md -f pdf

# Generate high-resolution PNGs
./pymeregen diagrams/*.mmd -f png --dpi 300

# Convert to JPEG with enlarged text
./pymeregen diagram.md -f jpg --enlarge 2 --dpi 200

Command Line Options

positional arguments:
  files                 Input files containing Mermaid diagrams

optional arguments:
  -h, --help            Show help message
  -o, --output OUTPUT   Output directory (default: same as input file)
  -f, --format {svg,pdf,png,jpg}
                        Output format (default: svg)
  --theme {default,dark,forest,neutral}
                        Mermaid theme
  --width WIDTH         Diagram width
  --height HEIGHT       Diagram height
  --background COLOR    Background color (e.g., "white", "#ffffff")
  --enlarge {1,2,3,4,5}
                        Enlarge all fonts by a factor (1-5)
  --dpi DPI             DPI for PNG/JPG output (default: 150)

Font Scaling

The --enlarge option scales fonts to improve readability:

• --enlarge 1: 1.25x (20px from 16px base)
• --enlarge 2: 1.5x (24px)
• --enlarge 3: 1.75x (28px)
• --enlarge 4: 2x (32px)
• --enlarge 5: 2.25x (36px)

Input Format Support

Markdown Code Blocks

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do something]
    B -->|No| D[Do something else]

### HTML Divs
```html
<div class="mermaid">
graph LR
    A --> B
    B --> C
</div>

Standalone Files

Create .mmd files with raw Mermaid syntax:

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!

Examples

Convert Files in Place

# Outputs SVG files in the same directory as the markdown files
./pymeregen docs/*.md -f svg

# Convert all diagrams in subdirectories, keeping outputs with source files
./pymeregen projects/**/*.mmd -f pdf --enlarge 2

Batch Convert with Theme to Specific Directory

./pymeregen docs/*.md -f svg --theme dark -o ./output/dark-diagrams

High-Quality Print PDFs

./pymeregen figures/*.mmd -f pdf --enlarge 3 --width 1200

Web-Optimized PNGs

./pymeregen *.md -f png --dpi 144 --background transparent

Troubleshooting

Mermaid CLI Installation Fails

• Ensure Node.js and npm are installed: node --version and npm --version
• Try manual installation: npm install -g @mermaid-js/mermaid-cli

JPG Conversion Error

• Install Pillow: pip install Pillow
• JPG format requires converting from PNG, so it may be slower

Diagrams Not Found

• Check that your Mermaid blocks use proper markdown syntax
• Standalone files must have .mmd extension or recognizable Mermaid syntax

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 Tim O'Shea

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.