How to Generate Mermaid Diagrams with ChatGPT and Claude

Mermaid is one of the few diagram formats AI assistants generate well. The syntax is text-based, the spec is small, and the training data is full of examples from GitHub READMEs. Ask ChatGPT or Claude to "diagram this in Mermaid" and you usually get something that renders on the first try.

Usually. The remaining 20 percent of the time you get arrows pointing the wrong way, mixed diagram types, or labels with parentheses that break the parser. This guide covers the prompts that produce valid output every time and the four mistakes models make most often — with one-line fixes for each.

Why AI is good at Mermaid

Three reasons make Mermaid uniquely AI-friendly:

• Text in, text out. No image generation, no SVG paths to hallucinate. The model writes plain text and a renderer turns it into a diagram.
• Tiny grammar. Each diagram type has a few dozen tokens. Even small models keep the syntax in working memory.
• Massive training corpus. Every Mermaid example in every GitHub README is fair game. The model has seen thousands of flowcharts.

The implication: prompts that work for code also work for Mermaid. Be specific, give an example, and constrain the output.

Five prompt patterns that work

1. Name the diagram type explicitly

Don't say "draw this." Say which Mermaid diagram type you want — flowchart, sequence, class, ER, state, gantt, mindmap, gitGraph, journey, or pie. The model picks better when the choice is closed.

Generate a Mermaid sequence diagram showing how a user signs in with OAuth: browser, app, identity provider, callback.

2. Give one example in the prompt

Few-shot beats zero-shot. Paste a tiny working snippet of the diagram type you want and ask the model to follow the same shape.

flowchart TD
    A[Start] --> B{Has account?}
    B -- Yes --> C[Sign in]
    B -- No --> D[Sign up]
    C --> E[Dashboard]
    D --> E

3. Constrain node count

Without a limit, models produce 20-node monsters. Say "max 8 nodes" or "group related steps into 3 subgraphs." Both ChatGPT and Claude respect this consistently.

4. Ask for labels in plain English

Models default to abbreviated node IDs like A, B, C1. Add: "node labels should be human-readable sentences." The output reads like documentation instead of a state machine sketch.

5. Iterate by paste-back

The fastest workflow is: prompt → render in MermanDraw → paste back any errors → ask the model to fix them. The error messages from the Mermaid parser are precise (line and column), and AI assistants resolve them on the first follow-up almost every time.

The four mistakes models make most often

Mistake 1: Wrong arrow syntax for the diagram type

Each Mermaid diagram has its own arrow grammar. Flowcharts use --> or --text-->; sequence diagrams use ->, ->>, or --> for dashed; class diagrams use --|> for inheritance.

Models sometimes mix them up. Fix: tell the model the exact arrow tokens in your prompt, or just paste the rendered error back and ask for a correction.

sequenceDiagram
    participant U as User
    participant A as App
    participant I as Identity Provider
    U->>A: Click "Sign in"
    A->>I: Redirect to /authorize
    I-->>U: Login form
    U->>I: Enter credentials
    I-->>A: Callback with code
    A->>I: Exchange code for token
    I-->>A: Access token
    A-->>U: Logged in

Mistake 2: Special characters in node labels

Parentheses, square brackets, and quotes inside labels confuse the parser if they aren't escaped. Common failure: A[Click (here)].

Two fixes:

• Wrap the label in double quotes: A["Click (here)"]
• Tell the model in your prompt: "avoid parentheses, brackets, or quotes inside node labels."

Mistake 3: Outdated syntax

Older training data contains graph TD (legacy) instead of the modern flowchart TD. Both still render, but newer features only work on flowchart. Add "use modern Mermaid syntax (v10 or later)" to your prompt and the output uses the current grammar.

Mistake 4: Mixed diagram types in one block

Occasionally a model starts a flowchart and slips in sequence-style arrows half-way through. The renderer fails on the first foreign token. Easiest fix: paste the broken code into MermanDraw, copy the error line, and ask the model to "fix the syntax error on line N."

A prompt template you can copy

Combine the patterns above and you get a prompt that works on the first try for almost any diagram:

Generate a Mermaid [flowchart / sequence / class / ER] diagram describing [your topic].

Constraints:
- Maximum 8 nodes.
- Labels should be human-readable sentences, no abbreviations.
- Avoid parentheses, brackets, or quotes inside labels.
- Use modern Mermaid syntax (v10 or later).

Output only the Mermaid code block, nothing else.

Copy the response, paste it into MermanDraw, and you get a rendered diagram in under a second. If anything fails, the error panel points at the line — paste it back to the model and the next response almost always works.

FAQ

Related

• Mermaid Cheatsheet — every diagram type with a copy-paste example.
• How to add Mermaid diagrams to a GitHub README