How to Create Mermaid Diagrams — The README<br>For AI agents: the site index is at /llms.txt and the full site content at /llms-full.txt. For a markdown version of a page, append .md to its URL or request it with Accept: text/markdown. llms.txt<br>When you need to add diagrams to your website, docs, or PDFs, there are a lot of options. In today's agentic world, numero uno is use an AI agent like Claude or Codex, and those usually work ok. However, the more complex the diagram, the more messed up the lines and arrows become.<br>For example, I asked Claude with Opus 4.8 to create the same flowchart using mermaid and by hand (or by AI). Here is how it looks:<br>Mermaid vs AI generated diagramOn the left is a Mermaid diagram and on the right is the AI generated diagram. You can see how messy it is with text going outside the boxes, no arrows, etc. This is why diagrams-as-code is so powerful, even in an agentic world.<br>So what is Mermaid? Essentially, Mermaid markdown inspired syntax that lets you write diagrams as plain text, commit them next to your code, and have a renderer draw them. You can change a line, open a pull request, and the diagram updates in the same review as the code it describes. This is why it is considered diagrams-as-code.<br>The alternative is the architecture PNG or SVG (which is code, so better) that you need to maintain separately and regenerate on any changes.<br>In the following sections, we'll cover the key areas of:<br>The syntax rules that unlock every diagram type.<br>Diagrams you can copy, paste, and adapt today.<br>How to wire diagrams into your Git and docs workflow.<br>The gotchas that trip people up, and where to write and preview.<br>Why Diagrams as Code Beats Drag-and-Drop<br>Mermaid is one of the best choices for markdown-like diagrams (others such as D2 also are popular), and the usage numbers prove it: about 9.8 million weekly downloads on npm and 88.9k stars on GitHub as of June 2026 (npm, 2026; GitHub, 2026).<br>npmjs.comIt's open source under the MIT license and free to use anywhere. Knut Sveidqvist created it, then built a company around it (TechCrunch, 2024).<br>The appeal of Mermaid is the workflow. A drag-and-drop diagram is a binary file that drifts out of sync the moment the system changes, because updating it is a separate chore from your actual work.<br>A Mermaid diagram is lines of text in the same repo as the thing it documents. It behaves like code because it is code.<br>The second awesome feature is portability. GitHub has drawn Mermaid blocks inside Markdown since February 2022, and GitLab, Notion, and Obsidian do too (GitHub Blog, 2022). You can paste the same snippet into a README, a wiki, or your docs tool and it renders with no plugin.<br>The Three Rules of Mermaid Syntax<br>Mermaid looks confusing until you notice that every diagram follows the same three rules, but if you're familiar with coding it's just a new syntax.<br>Wrap it in a fenced code block tagged mermaid. That's the signal renderers look for.<br>Declare the diagram type on the first line : flowchart, sequenceDiagram, erDiagram, and so on.<br>Describe the nodes and the connections between them. Mermaid handles the layout, you just need to give the flow.<br>A simple example is a flowchart that reads top to bottom:<br>flowchart TD<br>A[Start] --> B[Do the work] --> C[Ship it]
TD means top-down (LR is left-to-right), square brackets make a box, and --> draws an arrow. Everything below builds on those primitives.<br>Mermaid Diagram Examples<br>Mermaid handles a lot more than flowcharts. Below are seven of the most common types, each with the exact syntax and the rendered result. We generated every image here from the code block beside it, so copy any one into a Markdown file on GitHub and you'll see the same thing.<br>Flowcharts<br>Flowcharts are the workhorse: any process with steps and branches. Use a curly-brace node ({ }) for a decision and label the branches with |Yes| style text.<br>You'll see two keywords for this, flowchart and the older graph. They render almost identically, but reach for flowchart, since that's where new features land.<br>flowchart LR<br>A[Open PR] --> B{CI passing?}<br>B -->|Yes| C[Request review]<br>B -->|No| D[Fix and push]<br>D --> B<br>C --> E([Merge to main])
Sequence Diagrams<br>When you need to show who talks to whom and in what order, use a sequence diagram. For example, API requests, auth handshakes, or webhook retries. Solid arrows (->>) are calls; dashed arrows (-->>) are responses.<br>sequenceDiagram<br>actor User<br>participant API<br>participant DB as Database<br>User->>API: POST /login<br>API->>DB: Find user by email<br>DB-->>API: User record<br>API-->>User: 200 + session token
Entity Relationship Diagrams<br>ER diagrams document a database schema and the relationships between tables. The crow's-foot notation (||--o{) reads as "one customer places zero or many orders."<br>erDiagram<br>CUSTOMER ||--o{ ORDER : places<br>ORDER ||--|{ LINE_ITEM : contains<br>PRODUCT ||--o{ LINE_ITEM : "ordered in"<br>CUSTOMER {<br>int id<br>string name<br>string email<br>ORDER {<br>int id<br>date created_at<br>LINE_ITEM {<br>int...