What is mermaid-diagrams?

A CLI tool that renders Mermaid .mmd files into themed SVGs using beautiful-mermaid and bun.

Which Mermaid diagrams and themes are supported?

All Mermaid diagram types with 14 themes including tokyo-night; use --list-themes to see names.

How do I render multiple diagrams at once?

Use --outdir to write to an output directory or -o for a single-file per input, as shown in examples.

mermaid-diagrams

Use Caution

npx machina-cli add skill ahundt/autorun/mermaid-diagrams --openclaw

Files (1)

SKILL.md

3.1 KB

Mermaid Diagram Rendering with beautiful-mermaid

Render Mermaid .mmd files into styled SVG using beautiful-mermaid and bun.

Skill Contents

File	Purpose
`render-mermaid.ts`	CLI tool: renders `.mmd` files to SVG
`gemini-diagram-prompt.md`	Prompt for Gemini image generation

Installation

Only bun is required. The beautiful-mermaid dependency is auto-installed by bun on first run.

# macOS
brew install oven-sh/bun/bun

# Or universal installer
curl -fsSL https://bun.sh/install | bash

CLI Reference

render-mermaid — Render Mermaid .mmd files to themed SVG

Usage:
  bun run render-mermaid.ts [options] <input.mmd...>
  echo 'graph TD; A-->B' | bun run render-mermaid.ts -o out.svg

Options:
  -o, --output <file>   Output file (single input only)
  --outdir <dir>        Output directory for multiple files
  -t, --theme <name>    Theme (default: tokyo-night)
  --list-themes         List available themes
  --help                Show this help

Output defaults: Without -o or -d, writes <name>.svg next to each input file.

Shorthand: Set MERMAID=plugins/autorun/skills/mermaid-diagrams/render-mermaid.ts for shorter commands.

Examples

MERMAID=plugins/autorun/skills/mermaid-diagrams/render-mermaid.ts

# Render single file (output next to input)
bun run $MERMAID diagram.mmd

# Render to specific output
bun run $MERMAID diagram.mmd -o pretty.svg

# Render all .mmd files to output directory
bun run $MERMAID docs/diagrams/*.mmd --outdir docs/diagrams

# Different theme
bun run $MERMAID -t dracula diagram.mmd

# Pipe from stdin
echo 'graph TD; A-->B-->C' | bun run $MERMAID -o quick.svg

# List themes
bun run $MERMAID --list-themes

Project Diagrams

Mermaid source files (.mmd) and rendered output (.svg) in docs/diagrams/:

Source	Description
`docs/diagrams/autofile-policy.mmd`	AutoFile policy flowchart
`docs/diagrams/three-stage-autorun.mmd`	Three-stage autorun flowchart
`autorun-architecture.mmd`	Full architecture (too complex for beautiful-mermaid)

Regenerate:

bun run $MERMAID docs/diagrams/*.mmd --outdir docs/diagrams

Known Limitations

Complex diagrams with deeply nested subgraphs may hit dagre layout bugs. Failed diagrams are reported but don't block other renders.
%%{init:...}%% front matter is stripped automatically (beautiful-mermaid applies its own theming).

Gemini Image Generation

gemini-diagram-prompt.md contains a prompt for Gemini to generate an outcome-focused project overview image. Copy the prompt into a Gemini conversation.

Source

git clone https://github.com/ahundt/autorun/blob/main/plugins/autorun/skills/mermaid-diagrams/SKILL.mdView on GitHub

Overview

mermaid-diagrams renders Mermaid .mmd sources into styled SVGs using beautiful-mermaid and bun. It supports all Mermaid diagram types with 14 themes (including tokyo-night) and provides a CLI to render single or multiple files with flexible output options.

How This Skill Works

The render-mermaid.ts CLI converts .mmd files to themed SVGs via beautiful-mermaid. You can pipe input, render multiple files into an output directory, and choose a theme with -t; a shorthand MERMAID environment variable lets you shorten commands.

When to Use It

You need to render a Mermaid diagram to SVG for a document.
You want to convert a directory of .mmd files to themed SVGs.
You need to apply a specific theme (e.g., tokyo-night or dracula) to diagrams.
You require outputting to a particular file path with -o or to a directory with --outdir.
You want to pipe Mermaid syntax from stdin and generate an SVG.

Quick Start

Step 1: Set MERMAID=plugins/autorun/skills/mermaid-diagrams/render-mermaid.ts
Step 2: Run bun run $MERMAID diagram.mmd
Step 3: Use -o or --outdir and -t to control output and theme

Best Practices

Validate Mermaid syntax before rendering for best results.
List and pick a theme with --list-themes to know available options.
Use -o for a single-file output or --outdir for multiple files to organize outputs.
Set MERMAID environment variable to point to render-mermaid.ts for quick commands.
Be aware of dagre layout limitations with complex diagrams; test and regenerate if needed.

Example Use Cases

Render single file next to input: bun run $MERMAID diagram.mmd
Render to a specific output: bun run $MERMAID diagram.mmd -o pretty.svg
Render all .mmd files to an output directory: bun run $MERMAID docs/diagrams/*.mmd --outdir docs/diagrams
Change theme to Dracula: bun run $MERMAID -t dracula diagram.mmd
Pipe from stdin: echo 'graph TD; A-->B-->C' | bun run $MERMAID -o quick.svg

Frequently Asked Questions

Add this skill to your agents