# How to read Mermaid diagrams without reading the code > What Mermaid is, how to tell which diagram an AI wrote, how to read flowcharts, timelines and pie charts as text, and how to see them drawn on a Mac. Source: https://oneclearreader.com/guides/read-mermaid-diagrams · Updated 28 September 2026 · One Clear Reader (Northlight Group Pty Ltd) > [!answer] **Mermaid** is a way of writing diagrams as text inside a Markdown file: a code block labeled `mermaid` holds a flowchart, timeline, pie chart or other diagram, and its first word (`graph`, `gantt`, `pie`, `sequenceDiagram`) tells you which type. To see it as a picture, open the file in an app that draws Mermaid. Without one, read the arrows as "goes to" and the brackets as boxes. ## 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: ```mermaid-pair caption: A Mermaid flowchart, as the AI wrote it and as a reader draws it. 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](/guides/what-is-a-md-file).) > [!scribble] 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](https://en.wikipedia.org/wiki/Mermaid_(software))). 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](https://github.blog/developer-skills/github/include-diagrams-markdown-files-mermaid/)), 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: ```text ```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. | First line | Diagram type | What it shows | |---|---|---| | `graph TD`, `graph LR`, `flowchart TD` | Flowchart | Steps, decisions and where each one leads | | `sequenceDiagram` | Sequence diagram | Who sends what to whom, in order | | `gantt` | Gantt chart | Tasks on a timeline, with start dates and lengths | | `pie` | Pie chart | How a whole splits into parts | | `timeline` | Timeline | Events grouped by period | | `journey` | User journey | Steps a person takes, with how each one feels | | `mindmap` | Mind map | Ideas branching from a central topic | | `stateDiagram-v2` | State diagram | The states something can be in and how it moves between them | | `erDiagram` | Entity relationship diagram | How pieces of data relate | | `classDiagram` | Class diagram | How parts of a program are structured | | `quadrantChart` | Quadrant chart | Items plotted on two axes | | `gitGraph` | Git graph | Branches and merges in a code history | 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: | Code | Direction | |---|---| | `TD` or `TB` | Top to bottom | | `LR` | Left to right | | `BT` | Bottom to top | | `RL` | Right to left | 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. | Written as | Shape | Usually means | |---|---|---| | `A[Label]` | Rectangle | A step or action | | `A(Label)` | Rounded rectangle | A softer step, often a start or end | | `A{Label}` | Diamond | A decision or question | | `A((Label))` | Circle | A start, end or key point | | `A[(Label)]` | Cylinder | A database or stored data | | `A>Label]` | Flag | A note or signal | 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. | Written as | What it draws | |---|---| | `A --> B` | Arrow from A to B | | `A --- B` | A plain line, no arrowhead | | `A -.-> B` | Dotted arrow, often an optional or indirect step | | `A ==> B` | Thick arrow, often the main path | | `A -->|yes| B` | Arrow with a label on it | | `A -- yes --> B` | Another way of labeling an arrow | 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. ```mermaid-pair caption: Read the words in brackets, then follow the arrows. 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. > [!note] Many flowcharts also group boxes with a `subgraph` line and an `end` line. Everything between them is drawn inside a labeled frame. Read the subgraph name as a section heading. ## 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. ```mermaid-pair caption: Each task line is a name, an optional status, a start and a length. 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. ```mermaid-pair caption: Labels in quotes, values after the colon. 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. ```mermaid-pair caption: Each arrow is one message, read from top to bottom. 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 ```mermaid-pair caption: Indentation shows which idea branches from which. 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: ```mermaid-pair caption: Drawn, the gap in this process is obvious. 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: - [ ] Does every diamond have an arrow for each answer? - [ ] Does every path reach an end? - [ ] Is there a loop that can never exit? - [ ] Are there two boxes that mean the same thing? ## 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. | Pattern | What it looks like | What it's telling you | |---|---|---| | Pipeline | A straight line of boxes, A to B to C | A fixed sequence of steps | | Gate | A diamond with yes and no branches | A decision that changes what happens next | | Retry loop | An arrow pointing back to an earlier box | Something repeats until it passes | | Fan out | One box with arrows to several boxes | Work that splits, often done in parallel | | Fan in | Several boxes pointing to one | Parts that come together before moving on | | Swim lanes | Subgraphs labeled with people or teams | Who is responsible for which steps | 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](/guides/color-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. | What you see | Likely cause | What to try | |---|---|---| | The code, with no drawing at all | The app doesn't support Mermaid | Open it in an app that does | | A "syntax error" message | One line is written slightly wrong | Note the line number if the app gives one, and ask the AI to fix that line | | An error that points at a box label | The label contains a character Mermaid treats as code, like brackets or quotes | Ask the AI to wrap labels in double quotes | | A newer diagram type shows as an error | The app uses an older version of Mermaid | Ask for a flowchart version instead | | It's drawn but tiny or cut off | The diagram is very wide | Ask for `TD` instead of `LR`, or split it in two | 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](/guides/visual-thinkers-reading-ai-docs). ## 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](https://code.visualstudio.com/docs/languages/markdown)). - **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](/guides/open-md-file-mac). > [!scribble] the best way to read Mermaid is not to. ## Questions ### What is Mermaid in Markdown? Mermaid is a text format for describing diagrams. You write it inside a code block marked mermaid, and apps that support it draw the diagram instead of showing the text. ### Why do Claude and ChatGPT write diagrams as code? Claude and ChatGPT write text, and Mermaid lets them describe a diagram in text, so the diagram can live inside a Markdown file and be edited like any other line. ### Which Mac apps draw Mermaid diagrams? One Clear Reader, Typora, Obsidian, Marked and VS Code's Markdown preview draw Mermaid diagrams from a .md file. TextEdit and Quick Look show only the code. ### What does graph TD mean in a Mermaid diagram? `graph TD` starts a Mermaid flowchart that flows top to bottom. `graph LR` starts one that flows left to right. ### Can I edit a Mermaid diagram in a .md file myself? Yes, you can edit a Mermaid diagram in any text editor. Change the words inside the brackets to rename a box, or add a line like B --> E to add an arrow. Keep the brackets and arrows intact so it still draws. ### Do Mermaid diagrams need the internet to draw? No, not if the app includes Mermaid itself. One Clear Reader draws diagrams on your Mac with no connection, so the file never leaves your computer.