Het maken van diagrammen was altijd al een van mijn minst favoriete onderdelen van documentatie. Ik verspilde uren aan het verplaatsen van vakjes en kwam toch uit met iets dat er amateuristisch uitzag. Dat veranderde toen ik Mermaid ontdekte. In dit bericht deel ik hoe ik Mermaid CLI gebruik om diagrammen te maken met alleen tekst, en hoe AI-tools dit proces volledig hebben getransformeerd en gestroomlijnd.

Wat is Mermaid?

Mermaid is een gratis, open-source tool die tekst omzet in diagrammen, een beetje zoals Markdown tekst omzet in opgemaakte inhoud. Het is volledig gratis onder de MIT-licentie, dus u kunt het voor werk of persoonlijke zaken gebruiken zonder u zorgen te maken over licentiekosten. Het kan worden gebruikt om allerlei soorten diagrammen te maken, zoals:

Stroomdiagrammen
Sequentiediagrammen
Klassendiagrammen
Entiteit-relatiediagrammen
Gantt-diagrammen
Cirkeldiagrammen
Gebruikersreisdiagrammen
Git-grafieken
Statusdiagrammen
En nog veel meer

Wat ik het leukst vind, is dat ik nooit meer vakjes hoef te slepen. Ik schrijf gewoon tekst en Mermaid maakt het diagram. Na jaren van worstelen met traditionele diagramtools voelt deze aanpak als een openbaring.

Aan de slag met Mermaid CLI

Ik begon Mermaid in de browser te gebruiken, maar de CLI (Command Line Interface) versie is waar de echte magie gebeurt. Hiermee kunt u uw tekstdiagrammen omzetten in daadwerkelijke afbeeldingsbestanden die u in documenten, presentaties of waar dan ook kunt plaatsen. En het is super eenvoudig te gebruiken.

De basissyntaxis voor het gebruik van Mermaid CLI is:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

Dit commando:

npx @mermaid-js/mermaid-cli: Voert de Mermaid CLI-tool uit zonder dat een globale installatie nodig is
-i diagram.mmd: Specificeert het invoerbestand met uw Mermaid-diagramdefinitie
-o diagram.png: Stelt de naam en het formaat van het uitvoerbestand in (in dit geval PNG)

U kunt ook SVG-bestanden genereren die schaalbaar zijn en perfect voor webgebruik:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

U kunt uw Mermaid-code ook snel online bekijken met tools zoals MermaidChart, wat geweldig is voor het testen en delen van diagrammen zonder iets te installeren.

Uw eerste Mermaid-diagram maken

Laten we beginnen met een eenvoudig stroomdiagram. Maak een bestand genaamd flowchart.mmd met deze inhoud:

flowchart TD
A[Start] --> B{Beslissing}
B -->|Ja| C[Proces 1]
B -->|Nee| D[Proces 2]
C --> E[Einde]
D --> E

Genereer nu een PNG-afbeelding van dit diagram:

npx @mermaid-js/mermaid-cli -i flowchart.mmd -o flowchart.png

Dit creëert een schoon, professioneel ogend stroomdiagram dat een eenvoudig beslissingsproces weergeeft, zoals dit:

Eenvoudig stroomdiagram dat een beslissingsproces weergeeft

U kunt deze zelfde aanpak gebruiken voor elk type diagram dat Mermaid ondersteunt.

Als u bijvoorbeeld een systeemarchitectuur moet visualiseren (zoals ik onlangs deed), kunt u zoiets maken:

flowchart TD
Client([Webbrowser]) --HTTP/HTTPS--> LB[Load Balancer]
LB --> API1[API Server 1]
LB --> API2[API Server 2]
API1 --> DB[(Database)]
API2 --> DB
API1 --> Cache[(Redis Cache)]
API2 --> Cache

Wat dit diagram oplevert:

Architectuurdiagram dat webservers, load balancer en database toont

Hoe AI Diagramcreatie een boost geeft

Hier wordt kunstmatige intelligentie een gamechanger. In plaats van handmatig Mermaid-diagrammen te schrijven, kunnen AI-tools zoals Cursor en Windsurf tekstbeschrijvingen analyseren en automatisch diagramdefinities voor u genereren.

Ik moest onlangs een architectuurdiagram maken voor een AWS + Drupal-project met een complexe architectuur. Zonder AI zou dit aanzienlijke tijd hebben gekost om alle componenten en verbindingen in kaart te brengen. In plaats daarvan heb ik de projectspecificaties aan de AI-assistent van Cursor gevoerd, gevraagd om de systeemcomponenten en hun relaties te extraheren, en kreeg ik Mermaid-code die me hielp het diagram efficiënter te maken.

Cursor's AI gebruiken om diagrammen te genereren

Cursor is een IDE met krachtige AI die zowel code als natuurlijke taal begrijpt. Het vermogen om technische beschrijvingen te interpreteren en om te zetten in gestructureerde Mermaid-syntaxis is opmerkelijk. Hier is mijn typische workflow:

Kopieer relevante tekst die het concept beschrijft dat u wilt visualiseren
Gebruik een prompt zoals: "Genereer een Mermaid-diagram op basis van deze beschrijving"
Cursor analyseert de tekst en genereert de juiste Mermaid-syntaxis
Sla de gegenereerde Mermaid-code op in een .mmd-bestand
Gebruik Mermaid CLI om het om te zetten naar een afbeelding

U kunt Cursor bijvoorbeeld prompten met instructies zoals:

"Maak een Mermaid-stroomdiagram dat een gebruikersregistratieproces weergeeft"
"Genereer een Mermaid-sequentiediagram voor deze API-verzoekstroom"
"Converteer deze projecttijdlijn naar een Mermaid Gantt-diagram"
"Maak een Mermaid-klassendiagram van deze domeinmodelbeschrijving"

Binnen enkele seconden heeft u een compleet Mermaid-diagram dat uw concept nauwkeurig weergeeft.

Verder gaan met Windsurf's AI

Windsurf (van Codeium) maakt gebruik van AI om diagramautomatisering nog verder te brengen. De AI-modellen kunnen volledige codebases of documentatiesets analyseren om scripts te maken die:

Tekstbestanden scannen op beschrijvingen die gevisualiseerd kunnen worden
Belangrijke elementen en relaties extraheren
Juiste Mermaid-syntaxis genereren op basis van het contenttype
Automatisch de Mermaid CLI uitvoeren om diagramafbeeldingen te maken
Deze diagrammen in uw documenten opnemen

Dit creëert een continue documentatieworkflow waarbij uw diagrammen synchroon blijven met uw geschreven inhoud. De AI kan detecteren wanneer uw code of documentatie significant genoeg verandert om diagramupdates te rechtvaardigen, waardoor het hele proces bijna handsfree wordt.

Geavanceerde Diagramtypen

Mermaid ondersteunt veel diagramtypen naast eenvoudige stroomdiagrammen. Hier zijn enkele nuttige voor architectuurdocumentatie:

Sequentiediagrammen

Perfect voor het illustreren van hoe componenten in de loop van de tijd interageren:

sequenceDiagram
participant Gebruiker
participant API
participant Database

Gebruiker->>API: GET /producten
API->>Database: Vraag producten op
Database-->>API: Retourneer resultaten
API-->>Gebruiker: JSON-antwoord

Wat dit sequentiediagram oplevert:

Sequentiediagram dat de API-verzoekstroom tussen Gebruiker, API en Database toont

Klassendiagrammen

Ideaal voor het tonen van objectgeoriënteerd ontwerp:

classDiagram
class Bestelling {
    +String id
    +Date aanmaakDatum
    +BestelStatus status
    +berekenTotaal()
}
class Klant {
    +String id
    +String naam
    +String email
    +plaatsBestelling()
}
Klant "1" -- "veel" Bestelling: plaatst

Wat dit klassendiagram oplevert:

Klassendiagram dat Klant- en Bestellingklassen met hun relatie toont

Entiteit-relatiediagrammen

Geweldig voor databaseontwerp:

erDiagram
KLANT ||--o{ BESTELLING : plaatst
BESTELLING ||--|{ REGEL_ITEM : bevat
KLANT }|..|{ AFLEVERADRES : gebruikt

Wat dit entiteit-relatiediagram oplevert:

Entiteit-relatiediagram dat klant-, bestel-, regelitem- en afleveradresrelaties toont

Praktische Voorbeelden

Mermaid CLI kan worden gebruikt voor diverse visualisatiebehoeften, waaronder systeemarchitectuurdocumentatie (zoals eerder vermeld), maar ook voor:

Projectplanning

Voor projectplanning kunt u een Gantt-diagram maken dat fasen en afhankelijkheden toont:

gantt
title Projecttijdlijn
dateFormat  YYYY-MM-DD
section Onderzoek
Vereisten verzamelen :a1, 2025-01-01, 10d
Marktonderzoek       :na a1, 7d
section Ontwikkeling
Frontend ontwikkeling  :b1, 2025-01-18, 14d
Backend ontwikkeling   :b2, 2025-01-18, 21d
section Testen
Integratietesten   :c1, na b1 b2, 7d
Gebruikersacceptatie       :c2, na c1, 7d

Wat deze tijdlijnvisualisatie oplevert:

Gantt-diagram dat de projecttijdlijn met ontwikkelingsfasen toont

Procesdocumentatie

Voor het documenteren van bedrijfsprocessen kan Mermaid duidelijke stroomdiagrammen maken:

flowchart TD
Start([Klantbestelling]) --> A{Voorraad beschikbaar?}
A -->|Ja| B[Verwerk betaling]
A -->|Nee| C[Backorderproces]
B --> D[Verzend product]
C --> E[Informeer klant]
D & E --> Einde([Voltooi bestelling])

Wat dit processtroomdiagram oplevert:

Processtroomdiagram dat een klantbestelworkflow toont

Toekomstige Mogelijkheden met AI en Automatisering

De combinatie van Mermaid CLI en AI-tools opent spannende mogelijkheden voor documentatieautomatisering. Ik zie een systeem voor me dat:

Documentatiebestanden monitort op wijzigingen
AI gebruikt om inhoud te identificeren die baat kan hebben bij visualisatie
Juiste Mermaid-syntaxis genereert op basis van de inhoud
Automatisch Mermaid CLI uitvoert om nieuwe diagramafbeeldingen te maken
De diagrammen intelligent in documenten insluit met de juiste context

Een dergelijke opstelling zou diagrammen synchroon houden met documentatie zonder handmatige tussenkomst. Hoewel ik dit systeem nog niet heb gebouwd, maken de huidige AI-tools en Mermaid CLI het volledig mogelijk.

Tips voor betere diagrammen

Gebruik betekenisvolle vormen: Mermaid biedt verschillende knooppuntvormen om verschillende soorten componenten (databases, services, externe systemen) te onderscheiden
Voeg kleur toe voor duidelijkheid: Gebruik kleuren om gerelateerde componenten te groeperen of belangrijke elementen te benadrukken
Houd het simpel: Vermijd overvolle diagrammen; maak meerdere gerichte diagrammen in plaats van één complex diagram
Gebruik subgrafieken: Groepeer gerelateerde componenten met subgrafieken om logische grenzen aan te geven
Voeg titels en beschrijvingen toe: Maak uw diagrammen zelfverklarend met duidelijke titels en korte beschrijvingen

Samenvatting

Mermaid biedt een praktische aanpak voor diagramcreatie die goed integreert met ontwikkelingsworkflows. Het tekstgebaseerde karakter van Mermaid-diagrammen maakt ze versiebeheer-vriendelijk en gemakkelijker te onderhouden dan traditionele diagramformaten.

In combinatie met AI-tools wordt het proces nog efficiënter. Deze tools kunnen helpen bij het genereren van diagramcode uit beschrijvingen, waardoor het toegankelijk wordt, zelfs voor mensen zonder diepgaande technische kennis.

Hier zijn enkele laatste gedachten over het gebruik van Mermaid:

Leercurve: De syntaxis is relatief eenvoudig te leren, vooral als u al bekend bent met markdown of andere tekstgebaseerde formaten.
Integratie: Mermaid-diagrammen werken op veel platforms, waaronder GitHub, Notion en andere documentatiesystemen.
Kosten: Als open-source tool met een MIT-licentie is Mermaid gratis te gebruiken voor elk doel.
Efficiëntie: Tekstgebaseerde diagramcreatie kan sneller zijn dan traditionele diagrammen zodra u bekend bent met de syntaxis.
Eenvoudige installatie: Het gebruik van npx om Mermaid CLI uit te voeren, elimineert installatieproblemen.

Als u uw documentatieproces wilt verbeteren, overweeg dan om Mermaid eens te proberen voor uw volgende project. De mogelijkheid om professionele diagrammen rechtstreeks uit tekstbeschrijvingen te maken, met de potentiële hulp van AI-tools, kan transformeren hoe u visualisatie in uw werk benadert.

Documentation

Automatisering van Diagramcreatie met Mermaid CLI en AI-tools