Mermaid CLI (Python)

A command-line interface and Python library for mermaid, which allows you to generate diagrams and flowcharts from text.

This code has been ported to Python from the following library: https://github.com/mermaid-js/mermaid-cli

Features

• Render Mermaid diagrams to SVG, PNG, or PDF formats
• Process Markdown files with embedded Mermaid diagrams
• Use as a command-line tool or Python library
• Customize output with themes, colors, and CSS
• Support for icon packs

Installation

pip install mermaid-cli

After installation, you need to install the Playwright browsers:

playwright install chromium

Usage

Command Line

# Simple diagram rendering
mmdc -i input.mmd -o output.svg

# Markdown file with mermaid diagrams
mmdc -i input.md -o output.md

# Customize output
mmdc -i input.mmd -o output.png -t dark -b transparent -w 1024 -H 768

Playwright Config (Custom Executable)

If you cannot install the bundled Playwright Chromium, you can point to a custom binary and pass additional launch args using --playwright-config-file:

{
  "headless": true,
  "executable_path": "/path/to/chromium",
  "args": ["--no-sandbox", "--disable-gpu"]
}

Python usage with a custom executable:

await render_mermaid(
    definition,
    output_format="svg",
    playwright_config={
        "headless": True,
        "executable_path": "/path/to/chromium",
        "args": ["--no-sandbox", "--disable-gpu"],
    },
)

Python Library

import asyncio
from mermaid_cli import render_mermaid, render_mermaid_file

# Render a diagram directly
async def render_diagram():
    definition = """
    graph TD
        A[Start] --> B{Is it?}
        B -->|Yes| C[OK]
        C --> D[Rethink]
        D --> B
        B ---->|No| E[End]
    """
    
    title, desc, svg_data = await render_mermaid(
        definition,
        output_format="svg",
        background_color="white",
        mermaid_config={"theme": "forest"}
    )
    
    with open("output.svg", "wb") as f:
        f.write(svg_data)

# Render from a file
async def render_file():
    await render_mermaid_file(
        input_file="input.mmd",
        output_file="output.svg",
        output_format="svg",
        mermaid_config={"theme": "dark"}
    )

# Run the async functions
asyncio.run(render_diagram())
asyncio.run(render_file())

# Or use the synchronous wrapper
from mermaid_cli import render_mermaid_file_sync

render_mermaid_file_sync(
    input_file="input.mmd",
    output_file="output.png",
    output_format="png"
)

Command Line Options

Option	Description
-t, --theme [theme]	Theme of the chart (default, forest, dark, neutral)
-w, --width [width]	Width of the page
-H, --height [height]	Height of the page
-i, --input <input>	Input mermaid file or markdown with mermaid code blocks
-o, --output [output]	Output file (svg, png, pdf, or md)
-e, --output-format [format]	Output format (svg, png, pdf)
-b, --background-color [color]	Background color (e.g., transparent, white, #F0F0F0)
-c, --config-file [file]	JSON configuration file for mermaid
-C, --css-file [file]	CSS file for styling the output
-I, --svg-id [id]	ID attribute for the SVG element
-s, --scale [scale]	Browser scale factor
-f, --pdf-fit	Scale PDF to fit chart
-q, --quiet	Suppress log output
-p, --playwright-config-file [file]	JSON configuration file for Playwright launch options
--icon-packs <icons...>	Icon packs to use (e.g., @iconify-json/logos)

API Reference

render_mermaid

async def render_mermaid(
    definition: str,
    output_format: str = "svg",
    viewport: Dict[str, int] = None,
    background_color: str = "white",
    mermaid_config: Dict[str, Any] = None,
    css: str = None,
    pdf_fit: bool = False,
    svg_id: str = None,
    icon_packs: List[str] = None,
    playwright_config: Dict[str, Any] = None,
) -> Tuple[Optional[str], Optional[str], bytes]

Renders a Mermaid diagram definition to the specified format.

Parameters:

• definition: Mermaid diagram definition string
• output_format: Output format (svg, png, pdf)
• viewport: Viewport dimensions (width, height, deviceScaleFactor)
• background_color: Background color
• mermaid_config: Mermaid configuration dictionary
• css: Custom CSS string
• pdf_fit: Scale PDF to fit chart
• svg_id: ID attribute for the SVG element
• icon_packs: List of icon packages to use
• playwright_config: Playwright launch options dictionary (e.g., headless, executable_path, args)

Returns: A tuple of (title, description, data) where data is the binary content of the rendered diagram.

render_mermaid_file

async def render_mermaid_file(
    input_file: Optional[str],
    output_file: str,
    output_format: Optional[str] = None,
    playwright_config: Dict[str, Any] = None,
    quiet: bool = False,
    **kwargs
) -> None

Renders a Mermaid diagram from a file or processes a Markdown file with embedded Mermaid diagrams.

Parameters:

• input_file: Path to input file or None for stdin
• output_file: Path to output file
• output_format: Output format (svg, png, pdf)
• playwright_config: Playwright launch options dictionary
• quiet: Suppress log output
• **kwargs: Additional options for render_mermaid

render_mermaid_file_sync

def render_mermaid_file_sync(
    input_file: Optional[str],
    output_file: str,
    output_format: Optional[str] = None,
    **kwargs
) -> None

Synchronous wrapper for render_mermaid_file.

Examples

Basic Flowchart

graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]

Sequence Diagram

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Class Diagram

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

License

MIT