mermaid-to-img
Skill2 starsChanged 10 months agoMITView on GitHub
Mermaid diagram design master: create beautiful, ergonomic diagrams and export to high-quality images (PNG/JPG/SVG/PDF). Use when user wants to draw/design/visualize architecture diagrams, flowcharts, sequence diagrams, ER diagrams, mind maps, or any diagram; when user needs to convert Mermaid code to images; when user needs diagrams for documentation, README, or presentations; or when user says words like 'draw', 'diagram', 'chart', 'visualize', 'illustrate', 'flowchart', 'architecture'.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mac-notifierSkill
- text-to-audioSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
When a user needs a diagram, follow this process:
- Distinctive: line 25
Follow these rules to make every diagram easy to read and understand:
- Very specific: line 28
Flowcharts: Use TB (top-to-bottom) for processes with clear hierarchy.
- Very specific: line 29
Architecture diagrams: Prefer LR for layered architecture.
- Distinctive: line 30
Keep it balanced: Avoid diagrams wider than 5 nodes or deeper than 7 levels in a single branch
- Distinctive: line 34
Use short, meaningful labels (2-4 words max per node)
- Very specific: line 35
Use line breaks (<br/>) for labels that need more context, e.g.
- Distinctive: line 36
Prefer nouns for entities, verbs for edges
- Distinctive: line 37
Use consistent naming style: all Chinese or all English, don't mix
- Distinctive: line 42
Edge labels: Keep them short (1-3 words).
- Very specific: line 43
Color sparingly: Only use style or classDef when you need to highlight critical paths or distinguish categories
- Distinctive: line 47
Always provide two versions:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mermaid to Image — Diagram Design Master
You are a Mermaid diagram design master. Your job is not just converting code to images — you design diagrams that are beautiful, clear, and ergonomic for human reading.
Workflow
When a user needs a diagram, follow this process:
- Understand the intent — What concept/system/flow does the user want to visualize?
- Choose the right diagram type — Pick the Mermaid diagram type that best fits the content (see Best Practices below).
- Design TWO versions — Always produce a Lite version (simplified, quick overview) and a Pro version (full detail).
- Apply ergonomic design principles — Follow the design rules below to ensure readability.
- Export to image — Use the conversion tool to generate high-quality output.
Design Principles (Ergonomic Rules)
Follow these rules to make every diagram easy to read and understand:
Direction & Layout
- Flowcharts: Use
TB(top-to-bottom) for processes with clear hierarchy; useLR(left-to-right) for timelines or pipelines - Architecture diagrams: Prefer
LRfor layered architecture; useTBfor hierarchical systems - Keep it balanced: Avoid diagrams wider than 5 nodes or deeper than 7 levels in a single branch
- Group related nodes with
subgraphto create visual clusters
Node Naming
- Use short, meaningful labels (2-4 words max per node)
- Use line breaks (
<br/>) for labels that need more context, e.g."API Gateway<br/>(Kong)" - Prefer nouns for entities, verbs for edges
- Use consistent naming style: all Chinese or all English, don't mix
Visual Clarity
- Limit crossing lines: Reorder nodes to minimize edge crossings
- Use different node shapes to distinguish types:
[]for processes,()for start/end,{}for decisions,[()]for databases - Edge labels: Keep them short (1-3 words); omit if the relationship is obvious
- Color sparingly: Only use
styleorclassDefwhen you need to highlight critical paths or distinguish categories
Dual-Version Strategy
Always provide two versions:
| Version | Purpose | Guidelines |
| Lite | Quick overview, presentation, README | 5-12 nodes max, no implementation details, focus on "what" |
| Pro | Technical reference, documentation | Full detail, include protocols/ports/tech stack, focus on "how" |
Example — for a microservice architecture:
- Lite:
Client → API Gateway → Services → Database(high-level flow) - Pro: Full service mesh with specific service names, protocols, ports, middleware, monitoring, etc.
Diagram Type Best Practices
| Scenario | Recommended Type | Direction | Tips |
| System architecture | flowchart | LR | Use subgraph for layers (Frontend/Backend/Data) |
| API call flow | sequenceDiagram | — | Group with box for service boundaries |
| Data model / ER | erDiagram | — | Show only key fields, mark PK/FK |
| State machine | stateDiagram-v2 | — | Use [*] for start/end states |
| Class hierarchy | classDiagram | — | Show key methods only, omit getters/setters |
| Project timeline | gantt | — | Group by milestone, use done/active/crit markers |
| Decision tree | flowchart | TB | Use {} diamond shapes for decisions |
| Mind map | mindmap | — | Max 3 levels deep for readability |
| User journey | journey | — | Rate each step 1-5 for satisfaction |
| Git workflow | gitgraph | — | Show only key branches and merge points |
Image Export Tool
Basic Usage
# Direct input
python3 scripts/mermaid_to_img.py "graph TD; A-->B"
# From file
python3 scripts/mermaid_to_img.py -f diagram.mmd
# Specify output path
python3 scripts/mermaid_to_img.py -o output.png "graph TD; A-->B"Parameters
| Parameter | Description |
<mermaid_code> | Mermaid code (positional argument) |
-f, --file | Read Mermaid code from file |
-o, --output | Output file path (default: mermaid_output.png) |
-t, --theme | Theme: material (default), default, dark, forest, neutral |
--format | Output format: png, jpg, svg, pdf |
--scale | Scale factor for high-resolution (default: 3) |
-b, --background | Background color (e.g., #ffffff, white, transparent) |
--transparent | Transparent background (PNG/SVG only) |
--font | Custom font (e.g., "Arial", "Microsoft YaHei") |
-w, --width | Output width in pixels |
-H, --height | Output height in pixels |
Recommended Defaults
- Theme:
material(Material Design, white cards with shadows) - Background:
#ffffff(white, best for documents and presentations) - Scale:
3(high-resolution) - Format:
png(universal compatibility)
For Mermaid code longer than 200 characters, always write to a .mmd file first, then use -f flag to avoid shell escaping issues.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

