Snelle start en hulpmiddelen voor Mermaid-diagrammen voor ontwikkelaars

Mermaid is een tekstgebaseerd tool voor het maken van diagrammen, bedoeld voor mensen die liever diagrammen schrijven dan vakjes op een canvas slepen. Het gebruikt een Markdown-achtige syntaxis om flowcharts, sequentiediagrammen, klassendiagrammen, statemachinediagrammen, tijdlijnen, Gantt-diagrammen, entiteitsrelatiediagrammen en meer te beschrijven.

Voor een technische blog is Mermaid een zeer goede standaardoptie. De diagrammen leven naast het artikel, ze kunnen worden beoordeeld in Git en ze zijn eenvoudig bij te werken wanneer het systeem verandert. Statische afbeeldingsdiagrammen zien er mooi uit tot het eerste architectuurwijziging. Mermaid-diagrammen zijn niet perfect, maar ze verouderen veel beter.

Deze handleiding is een praktische Mermaid quickstart en cheatsheet voor ontwikkelaars, technische schrijvers en eigenaars van Hugo-sites. Het maakt deel uit van de Documentatietools in 2026: Markdown, LaTeX, PDF & Printworkflow-hub.

Wat is Mermaid?

Mermaid is een diagram-as-code syntaxis. Je schrijft een klein tekstblok en Mermaid rendert het als een diagram.

Een basis Mermaid-diagram ziet er zo uit:

deze code:

```mermaid
flowchart TD
    A[Markdown schrijven] --> B[Mermaid-blok toevoegen]
    B --> C[Pagina renderen]
    C --> D[Diagram publiceren]
```

Levert het volgende diagram op:

Het belangrijke idee is eenvoudig: de bron van het diagram is platte tekst. Dit maakt het doorzoekbaar, reviewbaar, draagbaar en eenvoudig te behouden samen met de documentatie die het uitlegt.

Waarom Mermaid gebruiken in een technische blog?

Mermaid is nuttig wanneer je artikel meer nodig heeft dan proza, maar minder dan een volwaardig ontwerptool.

Gebruik Mermaid wanneer je wilt uitleggen:

• Verzoek- en responsstromen
• Implementatiepijplijnen
• Afhankelijkheden tussen services
• Toestandsovergangen
• Databaserelaties
• Gebruikersreizen
• Bouwstappen
• Beslislogica
• Projecttijdlijnen

Ik zou Mermaid niet gebruiken voor elke visuele weergave. Screenshots, handgetekende architectuurschetsen en opgepoetste marketingdiagrammen hebben nog steeds hun plaats. Maar voor engineeringdocumentatie is Mermaid vaak het meest onderhoudbare optie.

Mermaid Quickstart

Basis Markdown-gebruik

In Markdown gebruik je een omheind codeblok met mermaid als taal:

```mermaid
flowchart LR
    A[Start] --> B[Verwerken]
    B --> C[Klaar]
```

Veel platforms begrijpen dit formaat direct. mermaid is een van de speciale taalidentificatiecodes — naast diff, geojson en anderen — die bepaalde renderers behandelen als een eersteklas blokkentype in plaats van gewone syntaxis-highlighting. Voor een volledige uitsplitsing van de syntaxis voor omheinde blokken en ondersteunde taalidentificatiecodes, zie de Gids voor Markdown Codeblokken. Voor Hugo hangt het renderen af van je thema of siteconfiguratie. Daarin komen we later terug.

Test diagrammen voordat je publiceert

De eenvoudigste workflow is:

1. Schrijf het diagram in je Markdown-bestand.
2. Plak het in een Mermaid-live editor of lokale preview.
3. Fixeer syntaxisfouten.
4. Commit de Markdown-bron.
5. Controleer de final gerenderde pagina.

Dit voorkomt het klassieke probleem waarbij een diagram werkt in de ene renderer maar faalt in een andere vanwege een klein syntaxisdetail.

Flowchart Syntaxis

Flowcharts zijn het meest voorkomende type Mermaid-diagram. Gebruik ze voor workflows, algoritmen, beslisbomen en systeemstappen.

Basis Flowchart

deze code:

```mermaid
flowchart TD
    A[Gebruiker opent website] --> B{Is gebruiker ingelogd?}
    B -->|Ja| C[Toon dashboard]
    B -->|Nee| D[Toon inlogpagina]
```

Levert het volgende diagram op:

Flowchart Richtingen

Mermaid-flowcharts ondersteunen verschillende richtingen:

TD - boven naar beneden
TB - boven naar beneden
BT - onder naar boven
LR - links naar rechts
RL - rechts naar links

Voorbeeld:

deze code:

```mermaid
flowchart LR
    Browser --> CDN
    CDN --> WebServer
    WebServer --> Database
```

Levert het volgende diagram op:

Voor blogartikelen is LR vaak gemakkelijker te lezen voor architectuurdiagrammen. Voor stap-voor-stap processen is TD meestal beter.

Veelvoorkomende Knotvormen

deze code:

```mermaid
flowchart TD
    A[Rectangel]
    B(Afgerond rectangle)
    C{Beslissing}
    D((Cirkel))
    E[(Database)]
    F[[Subroutine]]
```

Levert het volgende diagram op:

Flowchart Pijlen

deze code:

```mermaid
flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -- Label --> F
```

Levert het volgende diagram op:

Subgrafieken

Gebruik subgrafieken om gerelateerde delen van een systeem te groeperen.

deze code:

```mermaid
flowchart LR
    subgraph Client
        Browser
    end

    subgraph Backend
        API
        Worker
    end

    subgraph Opslag
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    Browser --> API
    API --> DB
    API --> Cache
    API --> Worker
```

Levert het volgende diagram op:

Subgrafieken zijn krachtig, maar gebruik ze met zorg. Een diagram met zes subgrafieken en twintig pijlen is meestal een teken dat het artikel twee kleinere diagrammen nodig heeft.

Sequentiediagram Syntaxis

Sequentiediagrammen tonen communicatie tussen actoren of services door de tijd heen.

deze code:

```mermaid
sequenceDiagram
    participant Gebruiker
    participant App
    participant API
    participant DB

    Gebruiker->>App: Klik op inloggen
    App->>API: POST /login
    API->>DB: Geverifieer referenties
    DB-->>API: Gebruikersrecord
    API-->>App: Toegangstoken
    App-->>Gebruiker: Toon dashboard
```

Levert het volgende diagram op:

Veelvoorkomende Sequentiepijlen

->      solide lijn zonder pijl
-->     gestippelde lijn zonder pijl
->>     solide lijn met pijl
-->>    gestippelde lijn met pijl
-x      solide lijn met kruis
--x     gestippelde lijn met kruis

Activatiebalken

Activatiebalken maken duidelijker wanneer een participant werk verricht.

deze code:

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Verzoek data
    activate Server
    Server-->>Client: Respons
    deactivate Server
```

Levert het volgende diagram op:

Alternatieven en Voorwaarden

deze code:

```mermaid
sequenceDiagram
    participant Gebruiker
    participant API
    participant Betaling

    Gebruiker->>API: Order indienen

    alt Betaling slaagt
        API->>Betaling: Laad kaart op
        Betaling-->>API: Goedgekeurd
        API-->>Gebruiker: Order bevestigd
    else Betaling faalt
        Betaling-->>API: Afgekeurd
        API-->>Gebruiker: Toon fout
    end
```

Levert het volgende diagram op:

Sequentiediagrammen zijn uitstekend voor API-artikelen. Ze tonen niet alleen welke componenten bestaan, maar ook hoe ze met elkaar communiceren.

Klassendiagram Syntaxis

Klassendiagrammen zijn nuttig voor domeinmodellen en objectrelaties.

deze code:

```mermaid
classDiagram
    class Gebruiker {
        +string id
        +string email
        +login()
        +logout()
    }

    class Order {
        +string id
        +float totaal
        +indienen()
    }

    Gebruiker "1" --> "*" Order
```

Levert het volgende diagram op:

Klasrelaties

<|-- erfenis
*-- compositie
o-- aggregatie
--> associatie
-- link
..> afhankelijkheid
..|> realisatie

Voorbeeld:

deze code:

```mermaid
classDiagram
    Dier <|-- Hond
    Dier <|-- Kat
    Gebruiker "1" --> "*" Order
    Order *-- OrderItem
```

Levert het volgende diagram op:

Klassendiagrammen kunnen snel overladen worden. Gebruik in een blogpost bij voorkeur een klein domeinslice in plaats van een volledig applicatiemodel.

Stadiendiagram Syntaxis

Stadiendiagrammen leggen uit hoe iets verandert door de tijd heen.

deze code:

```mermaid
stateDiagram-v2
    [*] --> Concept
    Concept --> Review: indienen
    Review --> Gepubliceerd: goedkeuren
    Review --> Concept: wijzigingen verzoeken
    Gepubliceerd --> Gearchiveerd: archiveren
    Gearchiveerd --> [*]
```

Levert het volgende diagram op:

Gebruik stadiendiagrammen voor:

• Orderlevenscycli
• Implementatiestatussen
• Authenticatiestromen
• Status van achtergrondtaken
• Contentpubliceringsworkflows

Stadiendiagrammen zijn onderschat. Ze verklaren bedrijfslogica vaak beter dan een lang paragraaf.

Entiteitsrelatiediagram Syntaxis

Entiteitsrelatiediagrammen zijn nuttig voor databasemodellen.

deze code:

```mermaid
erDiagram
    GEBRUIKER ||--o{ ORDER : plaatst
    ORDER ||--|{ ORDER_ITEM : bevat
    PRODUCT ||--o{ ORDER_ITEM : verschijnt_in

    GEBRUIKER {
        string id
        string email
    }

    ORDER {
        string id
        datetime aangemaakt_op
    }

    PRODUCT {
        string id
        string naam
    }
```

Levert het volgende diagram op:

ER Relatiemarkeringen

||  precies één
o|  nul of één
}|  één of meer
}o  nul of meer

ER-diagrammen zijn het beste wanneer ze relaties uitleggen, niet elke kolom. Houd implementatiedetails in migraties of schemadocumentatie.

Gantt Diagram Syntaxis

Gantt-diagrammen zijn nuttig voor projecttijdlijnen.

deze code:

```mermaid
gantt
    title Documentatiemigratieplan
    dateFormat  YYYY-MM-DD

    section Planning
    Audit huidige docs      :a1, 2026-06-01, 5d
    Definieer structuur     :a2, after a1, 3d

    section Schrijven
    Herschrijf gidsen       :b1, after a2, 10d
    Review en publiceer     :b2, after b1, 4d
```

Levert het volgende diagram op:

Gantt-diagrammen zijn handig in interne planningposts, maar ze kunnen snel verouderen. Gebruik ze wanneer de tijdlijn zelf het punt is.

Tijdlijn Syntaxis

Tijdlijnen zijn goed voor releasegeschiedenissen, incidentbeschrijvingen en projectsummaries.

deze code:

```mermaid
timeline
    title API Evolutie
    2024 : REST API gelanceerd
    2025 : Webhooks toegevoegd
    2026 : Event streaming geïntroduceerd
```

Levert het volgende diagram op:

Gebruik een tijdlijn wanneer de volgorde belangrijker is dan afhankelijkheid. Als wat je belangrijk vindt de reeks gebeurtenissen is in plaats van hoe ze causaal verbonden zijn, houdt een tijdlijn de focus waar hij hoort en blijft hij in één oogopslag leesbaar.

Cirkeldiagram Syntaxis

Cirkeldiagrammen worden ondersteund, maar wees voorzichtig. Ze zijn eenvoudig te lezen wanneer er slechts enkele categorieën zijn en de waarden duidelijk verschillen.

deze code:

```mermaid
pie title Bouwtijd per Stap
    "Install dependencies" : 35
    "Run tests" : 45
    "Build assets" : 20
```

Levert het volgende diagram op:

Advies met een mening: als de waarden dicht bij elkaar liggen of er meer dan vijf categorieën zijn, gebruik dan een tabel. Een goed opgemaakte tabel communiceert precieze nummers eerlijker dan een cirkeldiagram waar de stukken er bijna identiek uitzien.

Git Graph Syntaxis

Git-grafieken kunnen vertakingsstrategieën en releasestromen uitleggen.

deze code:

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit
```

Levert het volgende diagram op:

Dit is nuttig voor artikelen over Git-workflows, trunk-gebaseerde ontwikkeling, releasebranches en hotfixes. Als je een snelle referentie nodig hebt voor de onderliggende vertakingscommando’s, dekt de GIT Cheatsheet de meest voorkomenden, samen met merge- en rebase-workflows.

Mermaid Cheatsheet

Diagramtypes

flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey

Flowchart Basis

flowchart TD
A[Text] --> B[Text]
A -->|Label| B
A -.-> B
A ==> B
A --- B

Flowchart Vormen

A[Rectangle]
A(Rounded)
A{Decision}
A((Circle))
A[(Database)]
A[[Subroutine]]
A>Flag]

Sequentiediagram Basis

sequenceDiagram
participant A
participant B
A->>B: Message
B-->>A: Reply
activate B
deactivate B

Sequentieblokken

alt condition
else other condition
end

opt optional step
end

loop each item
end

par parallel task
and another task
end

Klassendiagram Basis

classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order

Stadiendiagram Basis

stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]

ER Diagram Basis

erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains

Opmerkingen

Mermaid ondersteunt opmerkingen met %%.

deze code:

```mermaid
flowchart TD
    %% Dit is een opmerking
    A --> B
```

Levert het volgende diagram op:

Mermaid Gebruiken in Hugo

Hugo-content wordt meestal geschreven in Markdown, dus Mermaid past natuurlijk in een op Hugo gebaseerde technische blog. De exacte opstelling hangt af van je thema en Markdown-renderconfiguratie.

Het gangbare schrijfpatroon blijft hetzelfde:

```mermaid
flowchart LR
    Markdown --> Hugo
    Hugo --> HTML
    HTML --> Browser
```

Als je Hugo-thema al Mermaid ondersteunt, kan dit zonder extra werk renderen. Als dat niet zo is, heb je meestal een renderhook, shortcode, partial of themaconfiguratie nodig die Mermaid laadt op pagina’s die Mermaid-diagrammen bevatten.

Een praktische Hugo-opstelling moet streven naar deze regels:

• Houd Mermaid-bron binnen normale Markdown-artikelen.
• Laad Mermaid alleen op pagina’s die het nodig hebben.
• Vermijd globaal JavaScript als de meeste pagina’s geen diagrammen gebruiken.
• Test diagrammen tijdens lokale preview.
• Houd de diagrambron leesbaar in Git.

Voor een technische blog zijn omheinde codeblokken meestal beter dan aangepaste shortcodes omdat ze draagbaarder zijn. Als je later content verplaatst naar GitHub, een andere statische sitegenerator of een documentatieplatform, zijn standaard omheinde Mermaid-blokken eenvoudiger her te gebruiken.

Mermaid Best Practices

Houd diagrammen klein

Een diagram zou het artikel moeten verduidelijken, niet vervangen. Als lezers moeten inzoomen, is het diagram waarschijnlijk te groot.

Goede diagrammen hebben meestal:

• Één idee
• Duidelijke richting
• Korte labels
• Weinig kruisende lijnen
• Consistente benaming

Geef de voorkeur aan meerdere kleine diagrammen

Gebruik in plaats van één enorm systeemdiagram verschillende gerichte diagrammen:

• Verzoeksstromen
• Implementatietopologie
• Datamodel
• Stadienlevenscyclus
• Foutpad

Dit is beter voor lezers en beter voor mobielschermen.

Gebruik stabiele namen

Gebruik namen die overeenkomen met je code, API of documentatie. Noem niet hetzelfde ding API, Backend en Server in verschillende diagrammen tenzij het echt verschillende concepten zijn.

Label belangrijke pijlen

Ongeleerde pijlen zijn prima voor eenvoudige flowcharts. In systeemdiagrammen zijn labels vaak belangrijk.

deze code:

```mermaid
flowchart LR
    Web -->|HTTPS verzoek| API
    API -->|SQL query| DB
    API -->|publiceer gebeurtenis| Queue
```

Levert het volgende diagram op:

Vermijd slimme syntaxis

Mermaid kan veel dingen. Dat betekent niet dat elk artikel ze nodig heeft. Geef de voorkeur aan syntaxis die een toekomstige onderhouder snel kan begrijpen.

Gebruik quotes voor labels wanneer nodig

Als een label tekens bevat die Mermaid verwarren, omring het dan met quotes.

deze code:

```mermaid
flowchart TD
    A["Gebruiker klikt op /checkout"] --> B["POST /api/orders"]
```

Levert het volgende diagram op:

Dit is een kleine gewoonte die irritante renderfouten voorkomt.

Denk na over Dark Mode

Veel Hugo-sites ondersteunen dark mode. Zorg ervoor dat je Mermaid-thema of site-CSS diagrammen leesbaar houdt in zowel licht als donker uiterlijk.

Veelgemaakte Mermaid Fouten

Fout 1: Te veel detail

Slechte Mermaid-diagrammen proberen vaak elke uitzonderingscase te tonen. Dit maakt ze technisch compleet en praktisch onleesbaar. De oplossing is bijna altijd hetzelfde: splits het diagram in twee of drie kleinere, elk bedekkend één aspect, zodat lezers de logica kunnen volgen zonder een dozijn kruisende pijlen te moeten traceren.

Fout 2: Lange labels

Lange labels creëren brede vakjes en lelijke layouts.

In plaats van deze code:

```mermaid
flowchart TD
    A[De gebruiker dient het registratieformulier in met hun e-mailadres en wachtwoord]
```

Levert het volgende diagram op:

Geef de voorkeur aan deze code:

```mermaid
flowchart TD
    A[Registratieformulier indienen]
```

Levert het volgende diagram op:

Leg details uit in de alinea onder het diagram.

Fout 3: Onheldere richting

Kies een richting en blijf daaraan vasthouden. De meeste procesdiagrammen zouden TD moeten gebruiken. De meeste architectuurdiagrammen zijn makkelijker met LR.

Fout 4: Mermaid behandelen als ontwerptool

Mermaid is geen Figma. Het is niet bedoeld voor pixel-perfect diagrammen, en het proberen dat rol te forceren leidt alleen tot frustratie. Zijn kracht ligt in onderhoudbaarheid, niet in visuele perfectie — en die afweging is opzettelijk.

Mermaid SEO Tips voor Technische Blogs

Mermaid-diagrammen kunnen technische artikelen nuttiger maken, maar zoekmachines hebben nog steeds tekst nodig. Verwacht niet alleen op diagrammen.

Voor SEO-vriendelijke Mermaid-artikelen:

• Gebruik beschrijvende H2- en H3-koppen.
• Leg elk diagram uit in nabijgelegen tekst.
• Neem de belangrijke trefwoorden op in normale proza.
• Houd codevoorbeelden kopieerbaar.
• Voeg een alt-stijl uitleg toe onder complexe diagrammen.
• Gebruik een beknopte front matter titel en beschrijving.
• Vermijd het verbergen van alle betekenis binnen de gerenderde SVG.

Een Mermaid-diagram zou het artikel moeten ondersteunen. Het mag niet de enige plaats zijn waar belangrijke informatie bestaat.

Copy-Paste Mermaid Voorbeelden

API Verzoeksstroom

deze code:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: GET /account
    API->>Auth: Valideer token
    Auth-->>API: Token geldig
    API->>DB: Laad account
    DB-->>API: Accountdata
    API-->>Client: 200 OK
```

Levert het volgende diagram op:

CI Pijplijn

deze code:

```mermaid
flowchart TD
    A[Push commit] --> B[Install dependencies]
    B --> C[Run lint]
    C --> D[Run tests]
    D --> E[Build site]
    E --> F[Deploy]
```

Levert het volgende diagram op:

Dit patroon kaatst natuurlijk af op een echte CI-configuratie. Voor de stap-voor-stap syntaxis van GitHub Actions-workflows is de GitHub Actions Cheatsheet een handige compagnon wanneer je het bovenstaande diagram wilt omzetten in een werkende pijplijn.

Publiceringsworkflow

deze code:

```mermaid
stateDiagram-v2
    [*] --> Concept
    Concept --> Bewerken
    Bewerken --> Review
    Review --> Gepubliceerd
    Review --> Bewerken
    Gepubliceerd --> [*]
```

Levert het volgende diagram op:

Eenvoudig Datamodel

deze code:

```mermaid
erDiagram
    AUTEUR ||--o{ POST : schrijft
    POST ||--o{ COMMENT : ontvangt

    AUTEUR {
        string id
        string naam
    }

    POST {
        string id
        string titel
        datetime gepubliceerd_op
    }

    COMMENT {
        string id
        string body
    }
```

Levert het volgende diagram op:

Wanneer Mermaid Niet Gebruiken

Gebruik Mermaid niet wanneer:

• Het diagram een precieze visuele lay-out nodig heeft.
• Het ontwerp exact moet overeenkomen met een merkstelsel.
• De visuele weergave voornamelijk decoratief is.
• Het diagram te veel knooppunten heeft om te lezen.
• Een screenshot het punt beter zou uitleggen.
• De content zelden verandert en meer opmaak nodig heeft dan onderhoudbaarheid.

Mermaid is uitstekend voor levende technische documentatie. Het is minder goed voor presentatie-kwaliteit kunstwerken. Voor document-kwaliteit diagrammen in print- of PDF-contexten biedt LaTeX pakketten zoals TikZ en pgfplots die je veel meer lay-outcontrole geven — de LaTeX Cheat Sheet dekt diagramopname samen met de rest van de LaTeX-toolkit.

Eindgedachten

Mermaid is een van de beste tools voor technisch blogggen omdat het respecteert hoe ontwikkelaars al werken: tekstbestanden, Markdown, Git, code review en reproduceerbare builds. Voor alles rondom de diagrammen — koppen, lijsten, tabellen, codeblokken — is de Markdown Cheatsheet de snelle-referentie compagnon om naast deze gids te bewaren.

De beste Mermaid-diagrammen zijn niet de meest complexe. Het zijn de diagrammen die een concept duidelijk maken en zes maanden later nog eenvoudig te bewerken zijn.

Gebruik Mermaid voor de diagrammen die moeten leven met je documentatie. Houd ze klein, houd ze leesbaar en behandel ze als onderdeel van de broncode van je artikel.