nimgyo

README

nimgyo

A command-line tool that converts Mermaid diagrams to images (PNG, JPG, SVG) with beautiful hand-drawn Excalidraw styling.

Features

• Convert Mermaid diagrams to PNG, JPG, or SVG images
• Uses Excalidraw's hand-drawn aesthetic for beautiful diagrams
• Supports reading from files or stdin
• Customizable image quality and padding
• Optional image size constraints
• Cross-platform support (Linux, macOS, Windows)

Installation

Using Pre-built Binaries

Download the latest release for your platform from the releases page.

Extract the archive and move the binary to a directory in your PATH:

# macOS/Linux
tar -xzf nimgyo_*.tar.gz
sudo mv nimgyo /usr/local/bin/

# Windows
# Extract nimgyo.exe from the zip file and add to your PATH

Building from Source

Requirements:

• Go 1.24.4 or later
• Chrome/Chromium browser installed on your system

git clone https://github.com/tsuzu/nimgyo.git
cd nimgyo
go build -o nimgyo main.go

Usage

Basic Usage

Convert a Mermaid file to PNG:

nimgyo diagram.mmd

This will create diagram.png in the current directory.

Reading from stdin

cat diagram.mmd | nimgyo -
# or
echo "graph TD; A-->B;" | nimgyo -

Command-Line Options

nimgyo [options] <input-file>

Options:
  -output string
        Output file path (default: input filename with new extension)
  -type string
        Output image type: jpg, png or svg (default "png")
  -quality float
        Quality of the output image, 0.0-1.0 (only for jpg) (default 0.92)
  -padding int
        Padding around the diagram in pixels (default 10)
  -max-width-or-height int
        Maximum width or height of the output image in pixels (default: no limit)

Examples

Convert to SVG:

nimgyo -type svg diagram.mmd

Convert to JPG with custom quality:

nimgyo -type jpg -quality 0.95 diagram.mmd

Specify output file:

nimgyo -output my-diagram.png diagram.mmd

Limit image size:

nimgyo -max-width-or-height 1920 diagram.mmd

Increase padding:

nimgyo -padding 50 diagram.mmd

Mermaid Syntax

nimgyo supports 3 Mermaid diagram types. Here are some examples:

Flowchart

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

Sequence Diagram

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

Class Diagram

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()

For more Mermaid syntax examples, see the Mermaid documentation.

How It Works

nimgyo uses:

1. Mermaid for diagram parsing
2. Excalidraw for rendering diagrams with hand-drawn aesthetics
3. Chrome/Chromium (via chromedp) for headless rendering
4. Embedded web UI for the conversion process

Requirements

• Chrome or Chromium browser must be installed on your system
• The browser is controlled headlessly via the Chrome DevTools Protocol

License

MIT License - see LICENSE file for details.

Contributing

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

Credits

Built with:

• Mermaid - Diagram and flowchart generation
• Excalidraw - Hand-drawn diagram aesthetics
• chromedp - Chrome DevTools Protocol client