Mermaid

This guide gets you from "I draw boxes in a separate tool and forget to update them" to "my diagrams live next to my code and stay correct because they are text I can diff." It is for founders, operators, and technical teams who want flowcharts, sequence diagrams, ER models, and Gantt charts that travel with the repo or the doc, rather than rotting in a design file nobody opens twice.

Getting set up

Mermaid is diagram-as-code, so the first decision is where the code lives. You write a small block of plain-text syntax, and Mermaid renders it into a diagram. The setup that matters is choosing your rendering surface, because that determines how friction-free the tool feels day to day.

The lightest path is the official live editor in the browser, where you type Mermaid syntax on one side and watch the diagram render on the other. Use it when you want a one-off picture to drop into a slide or a message, with nothing to install.

The path that pays off long-term is rendering inside the places you already write. Many documentation surfaces and developer platforms render Mermaid natively from a fenced code block, so a diagram inside a README or a wiki page just appears. Your note-taking app may render it too. If you write a lot of docs, get Mermaid rendering inside your editor and your knowledge base first, because that is where it earns its keep.

For anything beyond casual use, decide early whether you treat diagrams as committed artefacts. The whole point of Mermaid is that a diagram is text, which means it diffs, reviews, and version-controls like any other file. If you commit the source next to the thing it describes, the diagram updates in the same pull request as the change, and that is the behaviour you want to design for from day one.

How to actually use it

Start by picking the right diagram type for the question you are answering, because Mermaid has a distinct grammar for each and choosing wrong makes the syntax fight you. A process or decision flow is a flowchart. An interaction between systems or people over time is a sequence diagram. A data model is an entity-relationship diagram. A project timeline is a Gantt chart. State machines, user journeys, and class diagrams each have their own type too.

The core workflow is iterative and fast. Write a few lines, render, read what came back, adjust. A flowchart begins by declaring a direction (top-down or left-right), then you name nodes and connect them with arrows. You are describing the graph in words, and Mermaid handles the layout, which is the trade you are making: you give up pixel control and you get speed plus a diagram that never drifts from its source.

Build in this order. First get the nodes and connections correct so the logic is right, ignoring how it looks. Then set the direction so it reads naturally, top-down for processes and left-right for pipelines or timelines. Only then add labels on the arrows, grouping, and styling. Doing it in that order stops you from polishing a diagram whose logic is still wrong, which is the most common way time disappears here.

Keep each diagram to one idea. Mermaid auto-layouts, and a single diagram crammed with thirty nodes turns into spaghetti no algorithm can save. Two clean diagrams beat one overloaded one every time.

Power moves

Subgraphs are the feature that separates a readable diagram from a wall of boxes: you group related nodes into a labelled container, so a system diagram visibly clusters "frontend", "backend", and "data" instead of scattering them. Reach for subgraphs the moment a flowchart has more than a handful of nodes.

Styling by class, rather than node by node, keeps large diagrams consistent. You define a style once and apply it to many nodes, so every "external system" or every "error path" looks the same, and changing the look means editing one definition instead of twenty.

Theming and configuration let you match a diagram to a brand or a dark interface without touching the content. Because the styling is separate from the structure, you can restyle a diagram wholesale and the logic stays put.

The genuinely non-obvious move is generating Mermaid rather than hand-writing it. Because the syntax is plain text with a simple grammar, you can have a script, or an AI assistant, emit the diagram from a source of truth: turn a database schema into an ER diagram, or a list of steps into a flowchart, programmatically. That is when diagram-as-code stops being a drawing convenience and becomes a way to keep pictures generated from real data, never hand-maintained.

Where it fits your stack

Mermaid slots in wherever you already keep words. In your code repository, committed Mermaid renders inside READMEs and pull requests, so architecture and data-flow diagrams sit beside the code and get reviewed with it. In your documentation or wiki, it turns a paragraph describing a process into a picture that updates when you edit the text.

In your knowledge base and notes, it gives you living diagrams inside the doc rather than an exported image you have to re-export every time something changes. For a growth or ops toolset specifically, that means your funnel logic, your lead-to-cash sequence, your data model, and your automation flows can live as text right next to the strategy that describes them, reviewed in the same place, never out of sync. It pairs naturally with an AI workflow too, since a language model can write the Mermaid for you and you keep the result in version control.

Pitfalls to avoid

The first mistake is treating Mermaid as a replacement for a real design tool. It is not. When you need precise visual control, exact positioning, or a polished marketing graphic, use a canvas tool and accept that it will drift. Mermaid is for diagrams whose correctness matters more than their pixels.

The second is overloading one diagram. The auto-layout that makes Mermaid fast also means you cannot rescue a thirty-node tangle by nudging boxes, because there are no boxes to nudge. Split it.

The third is forgetting where it renders. A block that renders beautifully in the live editor may not render on a platform that does not support Mermaid, so confirm your target surface supports it before you commit a diagram there expecting it to appear.

The fourth is fighting the layout engine. If a diagram looks wrong, the fix is almost always to change the direction or restructure the nodes, not to wrestle with styling. Let the grammar do the work it is good at.

INTERVIEW EWOUD: Where do you actually render Mermaid day to day (live editor, your editor, your knowledge base, the repo), and is the source committed alongside what it describes or kept somewhere separate?

INTERVIEW EWOUD: Which diagram type and which one workflow do you rely on most, and do you hand-write the syntax or generate it (script or AI) from a source of truth?

INTERVIEW EWOUD: What is the hard-won tip you would give someone setting Mermaid up for the first time, the thing you wish you had known before you committed your first diagram?

Mermaid is a diagramming tool that renders flowcharts, sequence diagrams, Gantt charts and 20+ other diagram types from a Markdown-inspired text syntax. The core library (mermaid.js) is open source and free; Mermaid Chart is the commercial hosted editor adding AI generation, collaboration and team features. It suits developers, technical writers and teams who want diagrams that live alongside code and documentation.

Mermaid is an open-source tool that turns plain text into diagrams. You write a few lines in its markdown-like syntax (a flowchart, a sequence diagram, a Gantt chart, an entity-relationship diagram, a state machine) and Mermaid renders the picture for you. Because the diagram lives as text, it sits happily inside a Git repo, a README, a Notion page, or a docs site, and it redraws itself whenever you change the words. The Mermaid Live Editor lets you sketch and export without installing anything.

Where it fits

Mermaid is for people who already live in text and want diagrams that travel with their code and docs. Engineers documenting an architecture, a database schema, or a request flow get the most out of it, because the diagram is versioned alongside the thing it describes and never drifts into a stale screenshot. It is genuinely useful for anyone writing technical documentation, onboarding notes, or runbooks, and it is a natural fit when you want an AI to generate a diagram, since a model writes Mermaid syntax far more reliably than it places boxes on a canvas.

It is not the right tool for pixel-perfect presentation graphics, brand-led visuals, or the kind of freeform whiteboarding where you drag shapes around and nudge them by hand. If the diagram is the deliverable and it needs to look designed, reach for a canvas tool instead. Mermaid wins when the diagram is a by-product of the writing, not the main event.

The honest take

The real strength is that diagrams become code: they live in version control, they review in a pull request, and they update by editing text rather than reopening a design file. That kills the stale-screenshot problem that haunts most documentation, and it makes diagrams something an AGENT can produce and maintain without a human opening an editor. It is open source, widely supported across GitHub, GitLab, and most docs platforms, and free to use, which lowers the cost of adopting it to almost nothing.

The trade-off is control. You describe intent and Mermaid decides the layout, so when a graph gets large the auto-layout can sprawl or cross lines in ways you cannot fully tame. The syntax is forgiving until it is not, and a small mistake can break the render with a terse error. You are trading manual precision for speed and maintainability, which is the right trade for documentation and the wrong one for a polished one-off.

INTERVIEW EWOUD: What is your overall verdict on Mermaid in one or two flowing sentences?

INTERVIEW EWOUD: What do you rate it out of five, and why that number?

INTERVIEW EWOUD: Is Mermaid in your own stack, and if so what do you actually use it for? What is the one line you would tell a peer who is weighing it up?

Developers and technical teams who keep diagrams as version-controlled text inside docs and code