How to read Mermaid diagrams without reading the code

Why does my AI diagram show as code instead of a picture?

An AI diagram shows as code because Claude or ChatGPT wrote it in Mermaid, a small text language for diagrams, and the app you opened it in doesn't draw Mermaid. You asked for a map of a process, and somewhere in the answer you got this:

graph LR
  A[Idea] --> B[Draft]
  B --> C{Approved?}
  C -->|yes| D[Publish]
  C -->|no| B

On top is what's actually in the file. Underneath is what it's meant to look like. The Mermaid text on top is complete and working: a set of instructions for drawing the picture underneath.

AI tools use Mermaid because they can't attach an image to a text file, but they can write text that describes an image. Any app that understands Mermaid turns that text into boxes, arrows and labels. Apps that don't, show you the recipe. (If the .md file itself is new to you, start with what a .md file is.)

a diagram in disguise. dashes are arrows. brackets are boxes.

Where does Mermaid come from?

Mermaid is an open-source project Knut Sveidqvist started in 2014 so diagrams in documentation could be updated as easily as the text around them (Wikipedia). Instead of redrawing a flowchart in a design tool every time a step changes, you edit one line of text.

Mermaid spread when popular platforms began drawing it automatically. GitHub has drawn Mermaid blocks in Markdown files since 2022 (GitHub blog), and many documentation tools and Markdown apps now support it. That's why AI tools, which learned from a lot of technical writing, reach for Mermaid so readily.

How do I spot a Mermaid diagram in a .md file?

In a raw .md file, a Mermaid diagram always sits inside a fenced code block that names the language:

    ```mermaid
    graph TD
      A[Start] --> B[Finish]
    ```

Three backticks, the word mermaid, then the diagram, then three backticks to close. If you see that, everything until the closing backticks is one diagram.

The first line inside the block tells you what kind of diagram it is. That single word is the most useful thing to read first. This table lists the first lines you'll meet and the diagram each one starts.

For most people using AI for planning and writing, the first five diagram types cover almost everything you'll meet. The rest show up mainly in technical work.

How do I read a Mermaid flowchart as text?

You read a Mermaid flowchart as text by looking at four things: the direction, the boxes, the arrows and the loops. Flowcharts are by far the most common diagram AI tools write, so these four cover most of what you'll see.

1. The direction

The letters after graph or flowchart say which way the chart flows:

This doesn't change the meaning, only the layout. TD charts read like a list of steps down the page. LR charts read like a sentence.

2. The boxes

Each box has a short ID and a label. The ID is how the rest of the diagram refers to it. The brackets around the label set the shape, as this table shows.

When you're reading, you can mostly ignore the IDs. Read the words inside the brackets, and let the bracket shape tell you if it's a question.

3. The arrows

Arrows connect boxes. Read each arrow as goes to or leads to. This table shows the arrow styles you'll see.

So C -->|no| B means from C, if the answer is no, go back to B.

4. The loops

When an arrow points back to an earlier box, that's a loop: a step that repeats until something changes. In the example at the top, C -->|no| B sends you back to drafting until the answer is yes.

Loops are where raw flowcharts are hardest to follow, because your eyes have to jump back up the text to find the box. Drawn, they're obvious.

Putting it together

Here's a slightly longer one, the kind an AI might write for a hiring process.

flowchart TD
  A([Application in]) --> B[Screen CV]
  B --> C{Good fit?}
  C -->|no| X([Send polite no])
  C -->|yes| D[Phone call]
  D --> E{Still keen?}
  E -->|yes| F[Paid task]
  E -->|no| X
  F --> G([Offer])

Read as text, you'd say: An application comes in. Screen the CV. Is it a good fit? If not, send a polite no. If yes, have a phone call. Still keen? If yes, set a paid task, then make an offer. If not, send a polite no.

That's a completely readable process, but it took some translation. The drawing needs none.

How do I read a Mermaid Gantt chart as text?

A Mermaid Gantt chart is readable as text once you know that each task line is a name, an optional status, a start and a length. AI tools love Gantt charts for project plans.

gantt
  title Launch plan
  dateFormat YYYY-MM-DD
  section Build
  Reader   :done,   2026-09-01, 14d
  Search   :active, 2026-09-10, 10d
  section Ship
  Beta     :2026-09-22, 7d
  Launch   :milestone, 2026-10-01, 0d

Here's how to read each line:

• title is the chart's name.
• dateFormat tells the chart how dates are written. You can skip it.
• section starts a group of tasks. Read it like a heading.
• Each task line is name, then a colon, then details separated by commas.
• done, active and crit (critical) are statuses. They change the bar's color.
• A date is when the task starts. 14d means it lasts fourteen days.
• milestone with 0d marks a single moment, like a launch day.

Sometimes a task starts after another one, like Beta :after Search, 7d. That means start when Search finishes, last seven days. This is where text gets hard: to know when Beta happens, you have to find Search, work out when it ends, and add. A drawn chart does that arithmetic for you.

How do I read a Mermaid pie chart as text?

A Mermaid pie chart is the simplest diagram to read as text: each line is a label and a number.

pie title Where the week went
  "Hunting for files" : 42
  "Fixing formatting" : 27
  "Actually reading" : 31

The label sits in quotes and the number follows the colon. The numbers don't have to add up to 100. Mermaid works out each slice's share of the total. To read it as text, add the numbers and compare each one to the total.

How do I read a Mermaid sequence diagram?

A Mermaid sequence diagram shows a conversation between people or systems, in order. They appear when an AI explains how something works step by step.

sequenceDiagram
  participant You
  participant Claude
  participant Mac
  You->>Claude: Write the launch plan
  Claude->>Mac: Save launch-plan.md
  Mac-->>Claude: Saved
  Claude-->>You: Done, here is the path

• participant lines list who's involved, left to right.
• A->>B: message is a message from A to B. Solid arrows are requests.
• -->> with two dashes is a dotted reply.
• Read the arrow lines top to bottom, like a script.

What other Mermaid diagrams might an AI write?

Mind maps, user journeys and state diagrams turn up less often in AI answers, and each one has one simple rule for reading it.

Mind maps

mindmap
  root((Launch))
    Website
      Hero
      Pricing
    App
      Search
      Themes

In a mind map, indentation does all the work. Each line indented under another branches from it. This is similar to a nested list, and just as hard to follow when it gets deep.

User journeys

A journey diagram lists steps a person takes, each with a score from 1 to 5 for how it feels and who's involved. Read each step as a line in a story and treat the number as a mood: 5 is great, 1 is painful. They're useful for spotting the worst moment in an experience at a glance, which is exactly what's hard to see in text.

State diagrams

A state diagram shows what state something is in and what moves it between states. [*] --> Draft means it starts as a draft. Draft --> Review : submit means submitting moves it from Draft to Review. Read each arrow as a rule.

How do I use a Mermaid diagram to check the AI's process?

A drawn Mermaid diagram is the quickest way to check whether the AI understood your process, because gaps you'd miss in text jump out in a picture. Say you asked for a refund process and got this:

flowchart TD
  A([Refund request]) --> B{Within 30 days?}
  B -->|yes| C[Refund in full]
  B -->|no| D{Faulty?}
  D -->|yes| C
  C --> E([Email receipt])

Read as text, it looks complete. Drawn, you notice straight away that the no branch from Faulty? goes nowhere. What happens to a customer who asks after 30 days for something that isn't faulty? The AI didn't say.

That's the real value of seeing the diagram: missing arrows, dead ends and loops that never exit are visible at a glance, and invisible in text. When you spot one, tell the AI exactly what's missing: Add what happens when the item isn't faulty and it's past 30 days.

A quick checklist for any flowchart:

What patterns do AI tools use in Mermaid diagrams?

AI tools reach for the same six shapes in Mermaid diagrams again and again, and recognizing them makes even raw diagrams quicker to read. This table names each pattern and what it tells you.

If you can name the pattern, you can often understand the diagram from its first few lines without reading the rest.

What do classDef and style lines mean in a Mermaid diagram?

Lines like classDef done fill:#DDEFDD or style C fill:#FDE7EC at the bottom of a Mermaid diagram only set colors. They don't change the diagram's shape, so when you read raw Mermaid you can skip them.

Color is worth asking for, though. A flowchart where finished steps are green and blocked ones are red is far quicker to read than a gray one. Our guide to adding color to Mermaid diagrams shows every method, with prompts to paste into Claude or ChatGPT.

Why won't my Mermaid diagram draw?

A Mermaid diagram that won't draw, even in an app that supports Mermaid, usually has one of five causes. This table matches what you see to the likely cause and the fix.

AI-written Mermaid is usually valid, but long diagrams sometimes contain a small mistake. The quickest fix is to paste the error back to the AI and ask it to correct the block. A line number makes that much faster: Line 7 of the refund diagram has a syntax error. Fix it.

How do I ask Claude or ChatGPT for easier-to-read diagrams?

Five short instructions make Mermaid diagrams from Claude or ChatGPT easier to read, drawn or not:

• Ask for top-to-bottom. Use flowchart TD. Tall diagrams fit pages better than wide ones.
• Ask for short labels. Keep each box under five words. Long labels make boxes huge.
• Ask for one idea per diagram. Two small diagrams beat one giant one.
• Ask for a text summary too. Add a numbered list of the steps below the diagram. Then you have both.
• Name the type. If you want a timeline, say Gantt chart. If you want proportions, say pie chart.

For more ways to make AI documents easier to take in, see reading AI documents when you think in pictures.

How do I see Mermaid diagrams drawn on a Mac?

To see Mermaid diagrams drawn on a Mac, open the .md file in an app that draws Mermaid, and you won't need to read any of the code. Your options (checked 28 September 2026):

• GitHub draws Mermaid in .md files you view on its website. Useful if your files are already there, but you'd need to upload them.
• Editors and note apps draw it, including Typora, Obsidian and Marked. VS Code's built-in Markdown preview now draws Mermaid too (VS Code docs).
• One Clear Reader draws Mermaid diagrams in the reading view, locally on your Mac, with no internet needed. Paste the path your AI gave you, or type part of the file name, and flowcharts, timelines and charts appear as pictures.

A few things in One Clear Reader help with the diagram problems above. Diagrams that don't set their own colors follow the page, so they stay readable when you switch to a dark page. If a diagram won't draw, you get a plain message such as This diagram has a syntax error on line 7, with the diagram code shown underneath, ready to copy back to your AI. Full View gives wide diagrams the whole screen. With Pro, Expand opens a diagram full size with zoom from 25% to 400%, and Copy SVG copies the drawing as SVG code, which design tools like Figma can paste in as a picture.

For every way to open the file in the first place, see how to open a .md file on a Mac.

the best way to read Mermaid is not to.

Questions people ask