Mermaid-diagrammen in Markdown: stroomdiagrammen, sequentiediagrammen en meer

Diagrammen leggen processen, architecturen en tijdlijnen beter uit dan alinea’s tekst. Maar als je ze in een tekenprogramma maakt, moet je afbeeldingen exporteren, ze naast de documentatie bewaren en alles opnieuw tekenen zodra er iets verandert.

Mermaid lost dat op: je beschrijft het diagram in een paar regels tekst in je Markdown-bestand, en de voorbeeldweergave tekent het. Het diagram staat in hetzelfde bestand, is zichtbaar in diffs en is net zo makkelijk bij te werken als een zin. GitHub, GitLab, Obsidian, veel documentatiegeneratoren en Markdown Preview Editor geven Mermaid direct weer.

Een Mermaid-diagram toevoegen

Maak een codeblok en stel de taal in op mermaid:

markdown```mermaid
flowchart LR
  A[Schrijven] --> B[Voorbeeld]
  B --> C{Klaar?}
  C -- ja --> D[Exporteren]
  C -- nee --> A
```

De voorbeeldweergave maakt daarvan:

De eerste regel noemt het type diagram. Alles daarna beschrijft knooppunten en verbindingen.

Stroomdiagrammen

Stroomdiagrammen (flowcharts) zijn het meest gebruikte type diagram. De richting komt na het sleutelwoord: TD of TB (van boven naar beneden), BT, LR (van links naar rechts) of RL.

mermaidflowchart TD
  start([Start]) --> input[/Bestand lezen/]
  input --> valid{Is het geldig?}
  valid -- Ja --> save[(Opslaan in database)]
  valid -- Nee --> error[Foutmelding tonen]
  error --> input

De haakjes rond een label bepalen de vorm van het knooppunt:

Verbindingen: --> is een pijl, --- een lijn zonder pijl, -.-> een stippelpijl en ==> een dikke pijl. Voeg een label toe met -- tekst --> of -->|tekst|.

Groepeer verwante knooppunten met subgraph:

mermaidflowchart LR
  subgraph Browser
    editor[Editor] --> preview[Voorbeeld]
  end
  preview --> export[HTML / PDF]

Sequentiediagrammen

Sequentiediagrammen laten zien hoe deelnemers in de loop van de tijd berichten uitwisselen — ideaal voor API’s, authenticatiestromen en klantreizen.

mermaidsequenceDiagram
  participant U as Gebruiker
  participant A as App
  participant S as Server
  U->>A: Klikt op "Inloggen"
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Dashboard tonen
  Note over A,S: Het token verloopt na 1 uur

->> is een doorgetrokken pijl (een verzoek), -->> een gestreepte pijl (een antwoord). Note over, Note left of en Note right of voegen opmerkingen toe. Gebruik blokken met loop, alt/else en opt om herhaling en vertakkingen te tonen.

Gantt-diagrammen

Een Gantt-diagram maakt van een takenlijst een tijdlijn. Taken kunnen op een datum beginnen of after (na) een andere taak.

mermaidgantt
  title Documentatiesprint
  dateFormat YYYY-MM-DD
  section Schrijven
  Opzet          :done,   a1, 2026-10-01, 2d
  Eerste versie  :active, a2, after a1, 4d
  section Review
  Peer review    :        a3, after a2, 3d
  Publiceren     :milestone, after a3, 0d

Toestandsdiagrammen

Toestandsdiagrammen beschrijven hoe iets tussen toestanden beweegt — een bestelling, een document, een UI-component.

mermaidstateDiagram-v2
  [*] --> Concept
  Concept --> Review : indienen
  Review --> Concept : wijzigingen gevraagd
  Review --> Gepubliceerd : goedkeuren
  Gepubliceerd --> [*]

Taartdiagrammen

Voor een snel beeld van aandelen in een geheel gebruikt een taartdiagram één regel per punt:

mermaidpie title Waar de tijd voor documentatie heen gaat
  "Schrijven" : 45
  "Opmaak" : 15
  "Diagrammen actueel houden" : 40

Mermaid ondersteunt ook klassendiagrammen, entity-relationshipdiagrammen, mindmaps, tijdlijnen, Git-grafieken, kwadrantdiagrammen en meer. De syntaxis van elk type staat beschreven op de officiële website van Mermaid.

Tips voor leesbare diagrammen

• Houd het klein. Een diagram met meer dan 15–20 knooppunten wordt moeilijk leesbaar. Splits het op in meerdere diagrammen, één per idee.
• Kies de richting bewust. LR past bij processen met weinig stappen; TD past bij hiërarchieën en lange stromen, vooral op smalle schermen.
• Gebruik korte ID’s en leesbare labels. Schrijf auth[Sessie controleren] in plaats van het label als ID te gebruiken — zo blijven verbindingen kort.
• Zet labels met speciale tekens tussen aanhalingstekens: A["Prijs: $5 (incl. btw)"].
• Voeg opmerkingen toe met %% aan het begin van een regel. Die worden bij het tekenen genegeerd.
• Bekijk het voorbeeld terwijl je typt. Eén ontbrekende pijl of haak breekt het hele diagram, dus een live voorbeeld scheelt veel giswerk. In Markdown Preview Editor wordt het diagram opnieuw getekend terwijl je bewerkt, en de knop Mermaid-diagram in de werkbalk van de geavanceerde editor voegt een startsjabloon in.

Documenten met diagrammen delen

Als je een document exporteert naar HTML of pdf, worden de diagrammen als afbeeldingen opgenomen, zodat de lezer Mermaid niet nodig heeft. Voor formules naast je diagrammen, zie wiskundige formules schrijven in Markdown, en voor al het andere — tabellen, takenlijsten, meldingen — houd je de Markdown cheat sheet bij de hand.