Mermaid / PlantUML - Diagramming Tools

When it comes to explaining a process, I always like to refer to a diagram.
You know the adage, " one picture is worth a thousand words “.

Legacy tools

At my previous clients, we were used to diagramming with software like Microsoft Visio, Modelio, etc. They are great tools, easy to use.
Need a box? Just drag and drop it from the toolbox panel.

However, when several people were working on the same project and had to modify the same diagrams, it became cumbersome:

  • Detecting changes and doing a diff was complicated
  • Updating required the software to be installed
  • Templating was not easy or impossible


Then we found a great tool called PlantUML. It solved most of our problems:

  • The diagrams were coded, and versioning was easy
  • We could store the diagram code with the project sources
  • It is free, and there are plugins for many editors (such as Visual Studio Code)
  • Diagrams are generated from the code and always rendered the same
  • Easy and accessible syntax

Many diagrams types are supported:

  • Sequence diagrams
  • Usecase diagrams
  • Class diagrams
  • Object diagram
  • Activity diagrams
  • Component diagrams
  • State diagram
  • Timing diagram


For this blog, I’m using Hugo because I wanted to write all my posts in Markdown for more or less the same reasons mentioned above. And it was the same for the diagramming. I wanted something well integrated. Plus, I wanted to test another diagramming tool :-).

And I found Mermaid, which appears to be a well-known tool with a large community.

When I’m writing this article:

  • 36k stars on Github
  • 3.6k commits
  • 250 contributors

I don’t know why it has been out of my radar for so long.

I will use Mermaid for all the diagrams I will write for this blog because:

  • The syntax is similar to the PlantUML’s one
  • The switch will be smooth
  • I can write diagrams directly into my Markdown file, using the <mermaid> tag
{{<mermaid class="text-center">}}
    Bob->>Alice: Hello!
    Alice->>Bob: Good bye!
    Bob->>Alice: Hello!
    Alice->>Bob: Good bye!