AK
Published on

Mermaid: A Text-to-Diagram Tool for Coders

Authors
  • avatar
    Name
    Abdullah Khallouf
    Twitter

It was a cold, bright day in September and the clock was striking thirteen ⏰. I was rushing to deliver a thesis draft to my supervisor and needed to include some flowcharts. I was not in the mood to draw them manually in my usual go-to tool, draw.io, and time was limited.

The thing with draw.io, and I suspect anyone who uses it would agree, is that you end up endlessly nudging arrows, fixing directions, and making sure shapes are symmetrical. Being a perfectionist (something I am not necessarily proud of) does not help: if I see one rectangle that is a fraction different from its siblings, I cannot help but tweak it until it is pixel-perfect. You end up wasting a lot of time on tiny edits here and there.

Then I thought: there must be a diagramming tool built for programmers — something I could describe in code and get a chart instantly. Five minutes later, I was down a Reddit rabbit hole searching for the best text-based diagram tool for coders...

2000-years-later

Yeeeeeess! I found it! Mermaid. It is just what I wanted: a text-to-diagram tool.

Mermaid supports various diagram types like Sequence diagrams, Gantt charts, Entity-Relationship diagrams, and more. Here is an example of a sequence diagram of OpenID Connect (OIDC) implicit flow, an authentication protocol.

sequenceDiagram
    participant User
    participant RP
    participant AuthorizationServer as Authorization Server (OP)

    %% Step 1
    User->>RP: (1) Access RP (e.g., web app)

    %% Step 2
    RP->>AuthorizationServer: (2) Authorization request (response_type=id_token)

    %% Step 3
    AuthorizationServer->>User: (3) User authentication and consent

    %% Step 4
    User->>AuthorizationServer: (4) Submit user credentials

    %% Step 5
    AuthorizationServer->>RP: (5) Redirect with ID token

    %% Step 6
    RP->>User: (6) User is authenticated, app proceeds

On the third line, the "as" keyword introduces an alias for an entity: the left-hand name is used in the code, while the right-hand, more readable name is shown in the chart. The rest of the code is fairly self-explanatory. If you run it in the Mermaid Live Editor (or with the Mermaid VS Code extension), you will see the following chart:

OIDC-implicit

However, my excitement dropped a little when I saw that the entities were duplicated at the bottom. It felt redundant and left a bad taste in my mouth, and as I expected, my supervisor pointed it out later...

Dissapointing

Finally, as with most tools, it is not a one-size-fits-all solution. One downside is that sequence diagrams duplicate entities at the bottom, which can feel a bit redundant. On the positive side, Mermaid is great for quick prototyping, especially when you are short on time. Plus, since diagrams are defined in text, you can version-control them in Git just like any other code.

That’s it, though — check the references :)

bye

References