Mermaid Maker#

Turn intent into .mmd text, then render it as themed SVG, ASCII, PNG, or PDF.

Key advantage: text-based syntax with fully automatic layout — no x/y coordinates. Source lives in git and embeds in Markdown.

When to use / when NOT to use#

Use this skill for: diagrams-as-code with automatic layout (flowchart, sequence, class, state, ER, gantt, mindmap, C4, …) — and for producing polished, themed, or terminal-friendly output from that source.

Do NOT use it — route elsewhere — for:

• Pixel-precise placement, custom layout, branded icons, heavy styling → drawio.
• A hand-drawn / sketchy aesthetic → excalidraw or tldraw.
• A freeform whiteboard or freehand strokes → tldraw.
• Strict, conventional UML notation → plantuml.

Workflow#

1. Pick diagram type — from the table below.
2. Generate — write the .mmd to disk (start from assets/templates/ if helpful).
3. Validate — REQUIRED before export: trial-render with your chosen backend (see Validation).
4. Choose a backend & render/export — themed SVG / ASCII / batch → beautiful-mermaid; PNG / PDF → mmdc; no install → Kroki (see Rendering).
5. Self-check (vision) — read the rendered image and fix readability defects automatic layout can't prevent; re-validate + re-export. Max 2 rounds; skip if no vision.
6. Review loop — show the image, apply the minimal .mmd edit per request, re-export until approved (5-round safety valve).
7. Report — tell the user the output file paths.

Diagram Types#

TypeKeywordUse forSyntaxFlowchartflowchart TD/LRprocesses, pipelines, decisionsFLOWCHART.mdSequencesequenceDiagramAPI calls, message passingSEQUENCE.mdClassclassDiagramOOP models, data structuresCLASS-ER.mdERerDiagramdatabase schemasCLASS-ER.mdStatestateDiagram-v2state machines, lifecycleOTHER-TYPES.mdGanttganttproject timelinesOTHER-TYPES.mdGit GraphgitGraphbranch strategiesOTHER-TYPES.mdPiepieproportionsOTHER-TYPES.mdMind Mapmindmaptopic breakdownsOTHER-TYPES.mdC4 ContextC4Contexthigh-level architectureOTHER-TYPES.mdUser JourneyjourneyUX flowsOTHER-TYPES.md

Reusable starters live in assets/templates/ (flowchart, sequence, state, class, er, gantt, gitgraph).

Rendering#

Pick the backend by what you need to ship. Full flags, install, and troubleshooting are in RENDERING.md.

NeedBackendOne-line commandThemed SVG, ASCII, or batchbeautiful-mermaidnode scripts/render.mjs -i d.mmd -o d.svg --theme tokyo-nightPNG or PDF, offlinemmdcmmdc -i d.mmd -o d.png -w 2048 --backgroundColor whiteNo install (just curl)Krokicurl -X POST -H "Content-Type: text/plain" --data-binary @d.mmd https://kroki.io/mermaid/svg -o d.svg

• ASCII (terminal / README): node scripts/render.mjs -i d.mmd -f ascii --use-ascii
• Batch a folder: node scripts/batch.mjs -i ./diagrams -o ./out --theme dracula -w 4
• beautiful-mermaid emits SVG/ASCII only; for PNG/PDF use mmdc. Its dependency auto-installs on first run.

Theming#

beautiful-mermaid ships 15 themes. Quick picks:

• Dark docs → tokyo-night ⭐ · github-dark · dracula
• Light docs → github-light · zinc-light · catppuccin-latte

List all: node scripts/themes.mjs. Full catalog, custom palettes, and a decision tree: THEMES.md. mmdc uses its own standard themes ( default/ dark/ neutral/ forest) via --theme.

Validation (Required)#

Never export without validating first. Trial-render with the backend you'll use:

bash

node scripts/render.mjs -i diagram.mmd -o /tmp/test.svg          # beautiful-mermaid
mmdc -i diagram.mmd -o /tmp/test.png 2>&1                        # mmdc
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo Valid || echo Invalid

A Could not find Chrome error from mmdc is a setup problem, not a syntax error — don't rewrite valid .mmd; fix the browser or validate via another backend.

Self-Check (vision)#

Validation proves syntax is legal — not that the render is readable. After exporting, read the image and catch what auto-layout can't prevent (these are about content, not overlaps):

CheckLook forFixLabel truncationNode/edge text clippedShorten, or wrap with <br/>Cramped densityToo many nodes, tangled linesFlip TD ↔ LR, split into subgraph s, reduce nodesWrong orientationFar too wide or too tallChange flowchart TD ↔ LR (or direction in class/state)Edge spaghettiMany crossing edgesReorder declarations so connected nodes are adjacent; group with subgraphWrong typeType doesn't suit contentSwitch ( gantt, sequenceDiagram, stateDiagram-v2, …)Low contrastText blends into fillAdjust theme / classDef, or pick a higher-contrast theme

Max 2 rounds; re-validate and re-export after every fix. If vision is unavailable, skip and show the image directly.

Review Loop#

Show the image, collect feedback, apply the minimal .mmd edit, then re-validate + re-export:

User requestEdit actionChange a labelEdit the node/edge textAdd/remove a node or edgeAdd/delete the matching lineChange a colorSwitch --theme, or add classDef + class <node> <className>Change layout directionSwap TD ↔ LR, or set direction (class/state)Restructure / groupWrap related nodes in a subgraph, or regenerate

Overwrite the same diagram.mmd / output each round — don't create v1, v2, …. After 5 rounds, suggest fine-tuning at mermaid.live.

Examples#

Example 1 — API authentication (sequence)#

Rendering diagram...

Render: node scripts/render.mjs -i auth-flow.mmd -o auth-flow.svg --theme tokyo-night

Example 2 — Microservices architecture (flowchart)#

Rendering diagram...

Export PNG: mmdc -i ecommerce-arch.mmd -o ecommerce-arch.png -w 2048 --backgroundColor white

Example 3 — Order lifecycle (state)#

Rendering diagram...

ASCII for a README: node scripts/render.mjs -i order-states.mmd -f ascii --use-ascii

Common Mistakes#

MistakeFixmmdc error Could not find Chrome``npx puppeteer browsers install chrome-headless-shell (or use Kroki)Cannot find module 'beautiful-mermaid'Auto-installs on first run; else npm install in the skill rootKroki PDF fails HTTP 400Kroki does PNG/SVG only for Mermaid; use mmdc for PDFWrong arrow in sequence->> request, -->> responseSpecial chars in labelQuote it: A["Label: value"]Blank / tiny PNGAdd -w 2048 (mmdc)Participant order wrongDeclare participant explicitly at topSubgraph name with spacesQuote it: subgraph "My Layer"

Full backend flags and troubleshooting: RENDERING.md.