Mermaid Diagrams

Overview

Mermaid is a text language for drawing diagrams. Because the source is plain text, it lives in the same repository as the code and goes through the same review process. A reviewer sees exactly which service or arrow was added, which is impossible with a binary image.

How it works

Place the definition in a fenced block labeled mermaid. GitHub and many docs tools render it inline.

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant O as Order Service
  participant P as Payment Service
  C->>G: POST /orders
  G->>O: create order
  O->>P: authorize payment
  P-->>O: authorized
  O-->>C: 201 Created

Choose the type by the question being answered: flowcharts for components and dependencies, sequence diagrams for request flows, state diagrams for lifecycles. Pair the diagrams with a short caption stating scope and abstraction level, for example a C4 container view.

Pitfalls

• Cramming everything into one diagram. Split by concern and level of detail.
• Relying on automatic layout for large graphs; readability collapses past a few dozen nodes.
• Forgetting the renderer. Pin or check the Mermaid version your docs platform uses.
• Treating diagrams as optional in pull requests. Make diagram updates part of the definition of done.
• Using inconsistent naming, so the diagram disagrees with the code.

Key takeaways

• Diagrams as text get the benefits of version control.
• One diagram, one question, one abstraction level.
• Keep source next to the docs and the code it describes.
• Accept less layout control in exchange for maintainability.