Diagrams are essential tools for visualizing processes, workflows and data structures. Whether you’re planning a software architecture, mapping out a business process or documenting a complex system, a picture makes the information easier to follow than the same thing written as paragraphs.

Drawing them by hand, though, is slow, and keeping them up to date is slower. Mermaid turns a diagram into a few lines of text, and ChatGPT is good at writing those lines. Together they get you from an idea to a diagram in a minute, and the diagram stays editable.

What is Mermaid?

Mermaid is an open-source JavaScript library that turns a text description into a diagram. You write what is connected to what, and Mermaid works out the layout:

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

graph TD starts a flowchart drawn top-down (Mermaid’s documentation now writes it flowchart TD; graph is the older alias). Square brackets make a box, curly braces a decision diamond, --> an arrow, and the text between pipes (|Yes|) labels an arrow. The last line sends the Debug step back to the question, which is the loop that makes this diagram honest.

Because the diagram is text, it lives happily in a Git repository: it shows up in diffs, gets reviewed in pull requests and never goes out of date because nobody could find the original file of a drawing tool.

Where the diagram is drawn

ChatGPT writes the Mermaid code; something else draws it. The places that render Mermaid include:

  • GitHub and GitLab: a code block marked mermaid in any Markdown file, issue, pull request or wiki is shown as the diagram.
  • Azure DevOps wikis: the code goes between ::: mermaid and :::.
  • Notion and Obsidian: a code block with the language set to Mermaid.
  • VS Code: Markdown preview extensions that support Mermaid show it as you type.
  • Mermaid Live Editor: paste the code and see the diagram next to it, then export it as SVG or PNG for a slide or a document.

That last one is the quickest way to check what ChatGPT gave you. In practice the loop is: ask, copy the code into the Live Editor, look, and ask ChatGPT for changes in plain words.

Asking ChatGPT for a diagram

“Create a flowchart showing the user authentication process” works, but it leaves ChatGPT to guess everything: how detailed to be, what the steps are called, which direction to draw. A good prompt answers those questions, the same way you would brief a colleague:

Write a Mermaid sequence diagram of a login in a web app with an API. Participants: Browser, API, Database. The browser posts the email and password; the API checks the password hash in the database; on success it returns an access token and a refresh token, on failure a 401. Then show the browser calling a protected endpoint with the access token. Only the Mermaid code, please.

The answer is a sequence diagram along these lines:

sequenceDiagram
    participant B as Browser
    participant A as API
    participant D as Database
    B->>A: POST /login (email, password)
    A->>D: Find user by email
    D-->>A: User and password hash
    alt Password matches
        A-->>B: 200 OK (access token, refresh token)
    else Unknown email or wrong password
        A-->>B: 401 Unauthorized
    end
    B->>A: GET /orders (Bearer access token)
    A-->>B: 200 OK (orders)

->> is a call and -->> a reply, drawn dashed. The alt and else blocks show the two outcomes in one diagram instead of two.

Three habits make the answers better:

  • Name the diagram type. Flowchart, sequence diagram, class diagram, entity relationship diagram, state diagram, Gantt chart: say which one you want, or ChatGPT picks for you.
  • Give the real names. Your services, tables and steps, not “Service A”. The diagram is for your team, and real names are what make it useful. (Check your company’s policy before pasting internal schemas or service names into ChatGPT; use a plan whose data isn’t used for training, or rename the sensitive parts.)
  • Ask for the code only. Otherwise the code comes wrapped in explanations you have to cut out.

Then iterate in plain words: “put the database on the right”, “add a step that logs failed logins”, “draw it left to right”. Each change costs a sentence instead of dragging boxes around.

Advertisement

Entity relationship diagrams from a description

Mermaid’s entity relationship diagrams are a good match for ChatGPT, because you can describe a schema in a sentence or two, or paste the CREATE TABLE statements and ask for the diagram:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_LINE : contains
    PRODUCT ||--o{ ORDER_LINE : "appears in"
    CUSTOMER {
        int id PK
        string email
    }
    ORDER {
        int id PK
        int customer_id FK
        date placed_on
    }

The symbols on each line are crow’s-foot notation: ||--o{ reads “exactly one to zero or more”, ||--|{ “exactly one to one or more”. A customer places zero or more orders; an order has at least one line. That is precisely the kind of detail that is easy to get wrong by hand and easy to check in a picture.

When the code doesn’t render

In a normal chat, ChatGPT doesn’t see the rendered diagram, so now and then it writes code that Mermaid rejects. The errors come from a handful of causes:

  • Brackets or parentheses inside a label. A[Call validate(user)] breaks, because the parentheses look like syntax. Put the text in quotes: A["Call validate(user)"].
  • The word “end” as a node id. In flowcharts, A --> end breaks the diagram, because end closes a block. Capitalise it (End) or give the node another id and use “end” as its text: A --> E[end].
  • Special characters in labels. Brackets, braces and quotes inside a flowchart label need the label wrapped in double quotes, and a double quote inside the text must be written #quot;: A["say #quot;hi#quot;"]. In sequence diagrams a semicolon ends the statement, so write it #59;.
  • A diagram type your renderer doesn’t know yet. Newer types (mind maps, timelines, architecture diagrams) need a recent version of Mermaid; an older wiki or plug-in may not draw them.

The fastest fix is usually to paste the error message back into ChatGPT along with the code. The Live Editor shows the error with the line it happened on, which gives ChatGPT exactly what it needs.

Best practices

  • Start from the question the diagram answers. “How does a login work?” makes a better diagram than “draw our system”.
  • One diagram, one idea. If a flowchart needs to scroll, split it in two.
  • Keep the code next to the thing it describes: in the README, the pull request or the wiki page, so it changes when the system does.
  • Review it like code. A diagram that says the wrong thing is worse than no diagram, and ChatGPT will happily draw a plausible flow that isn’t yours.

Conclusion

Mermaid makes a diagram something you write, and ChatGPT makes the writing fast. The combination is at its best for the diagrams teams need all the time and rarely draw: a sequence of calls between services, the tables behind a feature, the states of an order. Describe what you know, check the result in a renderer, and keep the text where your team will find it and keep it current.