A mentor once showed me a configuration based tool to generate diagrams.

This tool was called Mermaid.

At first I was apprehensive - another tool to learn?

Aren’t UI based tools like LucidCharts or even Google Slides a quicker way to generate architectural diagrams?

The main purpose of Mermaid is to help documentation catch up with development. (source)

After learning the syntax and getting to the point I’m fluent in using Mermaid - my perspective is that it is a great tool & well worth learning.

What is it?

Mermaid turns this:

graph LR;
  A-->B;
  B-->C;

into this flowchart

graph LR; A-->B; B-->C;

graph is just one of the few diagrams supported by Mermaid.

Examples

I’m not going to go into detail about how to create each diagram since that already exists in the documentation, but here are some more examples:

State Diagram

stateDiagram-v2 state isAlive <> state isHealthy <> [*] --> Unknown Unknown --> isAlive: probe liveliness isAlive --> Pending: failure isAlive --> Running: success Pending --> isAlive: probe liveliness Running --> isHealthy : probe health isHealthy --> Failed: failure isHealthy --> Running: success - Container Running isHealthy --> Succeeded: success - Container Terminated (Job) Failed --> [*] Succeeded --> [*]

Pie Chart

  • Diagram Type: pie
  • Example: Pretend example of company usage of React state management
pie title State Management Usage "useState" : 623 "useContext" : 271 "Global Store / Redux" : 482 "Local Class Component State": 195

Sequence Diagram

sequenceDiagram title Gossiper (for Live, Dead, & Seed Nodes) participant a as Node A participant b as Node B Note over a,b: - Gossiper - loop GossipTask: scheduled/1s a->>b: GossipDigestSyn b->>a: GossipDigestAck a->>b: GossipDigestAck2 end

Git Graph

  • Diagram Type: gitGraph
  • Example: History of a cherry-pick being applied after a release branch was cut.
gitGraph commit branch feature checkout feature commit id: "Bad Commit" commit checkout main merge feature checkout main commit commit branch release branch feature-fix checkout feature-fix commit id: "Fix" type: HIGHLIGHT checkout main merge feature-fix checkout release cherry-pick id:"Fix" commit

Class Diagram

classDiagram IEnumerable <|-- ICollection : implements IEnumerable *-- IEnumerator IEnumerator <|-- IDisposable : implements class IEnumerator~T~ { +object Current +MoveNext() bool +Reset() +Dispose() } class IEnumerable~T~ { +GetEnumerator() IEnumerator~T~ } class ICollection~T~ { +int Count +bool IsReadOnly +Add(T item) +Clear() +Contains(T item) bool +CopyTo(T[] array, int arrayIndex) +GetEnumerator() IEnumerator~T~ +Remove(T item) bool } class IDisposable { +Dispose() }

All via configuration!

Not impressed? Like all tools, there are trade-offs and I’ve listed some below.

Tooling

In daily life

In the industry

Trade-offs

Advantages of Mermaid

  • Better organization: Diagrams can directly reside along the code they describe instead of an external tool.
  • Source control: Diagrams can now follow the flow all PR’s go through.
  • Speed: Typing is fast, dragging & dropping is not (after getting past the learning curve). Templating is also possible via your favorite method for simplifying creating repetitive diagrams.

Disadvantages of Mermaid

  • Learning Curve: Arguably a small learning curve, but does take familiarity learning new syntax & advanced options
  • Scale: As diagrams grow in size, Mermaid does a poor job of automatically scaling those diagrams appropriately - work-a-arounds exist, but take more effort than expected. Alternative is breaking down diagrams into smaller & more consumable chunks.
  • Tooling: Linting & error handling with tools aren’t very mature yet. If the diagram doesn’t load at all, time to squint and review at what you just typed. Some sites claiming to support Mermaid (looking at you Azure DevOps) do not actually support all the diagram types.

General thoughts

Like all tools, the problem being solved might determine whether Mermaid may or may not be a good fit.

Whether these are advantages or disadvantages depends on a lot of context:

  • Style | Simplicity vs. Customization: One can apply custom styling with Mermaid, but obviously there are less options than a free-form graphical tool.
  • Affordances | Clear vs. Opaque: By using configuration based diagramming, there aren’t the inbuilt expectations that most individuals rely on for modifying visual elements (front-end engineers with CSS wizardry excluded). Visually selecting, dragging, and modifying the style of elements with a mouse appears to be default for the majority.