I Didn’t Set Out to Learn Mermaid. It Just Kept Showing Up.
This Is What Happens When You Keep Running Into Mermaid
- I did not wake up wanting to learn Mermaid. It ambushed me in competent documentation.
- The syntax feels foreign because it is not trying to draw pictures. It is trying to force you to admit relationships.
- Mermaid diagrams are not “visual aids.” They are structure with opinions.
I did not sit down with the goal of learning Mermaid diagrams.
I just kept encountering them.
They showed up in GitHub repositories I respected. In architecture documentation. In ADRs written by people who clearly hit the limits of prose and chose to stop negotiating with words alone.
At first, I ignored them. Then I skimmed them. Eventually, I realized I was avoiding something that was trying to tell me how it wanted to be used.
This post is not about mastering Mermaid. It is about understanding why it exists and why it kept showing up in my field of view.
The Initial Friction
At a surface level, Mermaid seems straightforward.
You write text.
A diagram appears.
That promise is appealing. The experience is not.
When I first looked at Mermaid syntax, I could understand individual parts. Nodes. Arrows. Labels. Subgraphs. Direction hints. But I could not reliably visualize what the final diagram would look like without rendering it.
That disconnect bothered me.
I am comfortable reading code and reasoning about systems. Mermaid did not map cleanly onto either skill. It felt declarative in a way my brain was not used to, and I could not tell whether that discomfort was a signal or just unfamiliarity.
The Question That Would Not Go Away
Do people actually write this by hand?
Some Mermaid examples were clean and intentional. Short identifiers. Clear structure. Obvious relationships.
Others were unreadable. Long opaque IDs. No semantic meaning. Clearly generated by a visual tool and exported as text.
That distinction mattered more than I expected.
If Mermaid was primarily machine output, then learning it deeply did not make sense. If it was a thinking tool that people actually authored, then I needed to understand how and why.
Example syntax
flowchart TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
Result
Where Mermaid Came From
Mermaid was created in 2014 by Knut Sveidqvist.
The problem it was designed to solve was not diagramming for its own sake. It was documentation drift.
Text documentation lived in repositories. Diagrams lived as images somewhere else. They aged at different rates and eventually told different stories.
Mermaid allowed diagrams to be defined as text so they could live alongside documentation, be versioned, reviewed, and changed as systems evolved.
The name is intentional.
Mermaids are mythological creatures that lure you toward something complex and dangerous. Diagrams do the same thing, but ideally in a productive way. They simplify just enough to be useful, without pretending the underlying system is simple.
Understanding that intent reframed everything for me.
What Finally Clicked
Mermaid is not a drawing tool.
It does not want coordinates. It does not want layout decisions. It does not want you to think in pixels.
It wants you to describe relationships.
What depends on what.
What flows where.
What defines what.
What boundaries exist.
What direction trust moves.
Once I stopped trying to visualize the diagram while reading the syntax and started treating Mermaid as a set of assertions about structure, the resistance eased.
The diagram was not the point. The relationships were.
Why It Feels So Foreign
Most tools ask you to describe outcomes.
Mermaid asks you to describe constraints.
You are not saying where something goes. You are saying how things relate. The rendering is a side effect of those relationships.
That is why reading Mermaid without rendering it feels uncomfortable. Your brain wants a picture. Mermaid wants a model.
Once I understood that, the discomfort felt earned instead of frustrating.
When a Diagram Earns Its Place
I still do not reach for Mermaid by default.
But I have started noticing the moments when it becomes appropriate.
When I am explaining flows instead of features.
When intent matters more than implementation.
When authority, trust, or boundaries are involved.
When prose keeps getting longer without getting clearer.
That is usually the signal.
Not that I need to draw a diagram, but that a structure already exists and I am avoiding naming it.
Why I Am Not Rushing This
I am not fluent in Mermaid.
I still render diagrams to validate my understanding. I still question whether a diagram clarifies or distracts. I still move slowly.
That is fine.
Mermaid is not something to adopt aggressively. It is something to recognize when it is useful.
Where I Landed
Mermaid stopped feeling strange once I understood its role.
It is not there to decorate documentation. It is there to preserve intent when words start to blur.
Future Me will not need more detail. Future Me will need context.
Mermaid helps with that.
I did not set out to learn Mermaid.
But now that I understand what it is actually for, I am paying attention when it shows up.
We will see where that leads.
Resources
