Diagramy Mermaid w Markdown: schematy blokowe, diagramy sekwencji i nie tylko

Diagramy tłumaczą procesy, architekturę i harmonogramy lepiej niż akapity tekstu. Jednak rysowanie ich w programie graficznym oznacza eksportowanie obrazów, przechowywanie ich obok dokumentacji i rysowanie wszystkiego od nowa przy każdej zmianie.

Mermaid rozwiązuje ten problem: opisujesz diagram w kilku linijkach tekstu w pliku Markdown, a podgląd go rysuje. Diagram znajduje się w tym samym pliku, widać go w porównaniach zmian (diff) i aktualizuje się go tak łatwo jak zdanie. GitHub, GitLab, Obsidian, wiele generatorów dokumentacji i Markdown Preview Editor renderują Mermaid od razu, bez dodatkowej konfiguracji.

Jak dodać diagram Mermaid

Utwórz blok kodu i ustaw jego język na mermaid:

markdown```mermaid
flowchart LR
  A[Pisz] --> B[Podgląd]
  B --> C{Gotowe?}
  C -- tak --> D[Eksport]
  C -- nie --> A
```

Podgląd zamienia to w:

Pierwszy wiersz określa typ diagramu. Wszystko, co następuje po nim, opisuje węzły i połączenia.

Schematy blokowe

Schematy blokowe (flowchart) to najczęściej używany typ diagramu. Kierunek podaje się po słowie kluczowym: TD lub TB (z góry na dół), BT, LR (od lewej do prawej) lub RL.

mermaidflowchart TD
  start([Start]) --> input[/Odczytaj plik/]
  input --> valid{Czy jest poprawny?}
  valid -- Tak --> save[(Zapisz w bazie danych)]
  valid -- Nie --> error[Pokaż błąd]
  error --> input

Nawiasy wokół etykiety określają kształt węzła:

Połączenia: --> to strzałka, --- linia bez strzałki, -.-> strzałka kropkowana, a ==> pogrubiona. Etykietę dodasz za pomocą -- text --> lub -->|text|.

Powiązane węzły zgrupujesz za pomocą subgraph:

mermaidflowchart LR
  subgraph Przeglądarka
    editor[Edytor] --> preview[Podgląd]
  end
  preview --> export[HTML / PDF]

Diagramy sekwencji

Diagramy sekwencji pokazują, jak uczestnicy wymieniają komunikaty w czasie — idealne do opisu API, procesów uwierzytelniania i ścieżek użytkownika.

mermaidsequenceDiagram
  participant U as Użytkownik
  participant A as Aplikacja
  participant S as Serwer
  U->>A: Klika „Zaloguj się”
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Pokazuje panel
  Note over A,S: Token wygasa po 1 godzinie

->> to ciągła strzałka (żądanie), -->> przerywana (odpowiedź). Note over, Note left of i Note right of dodają komentarze. Bloki loop, alt/else i opt pokazują powtórzenia i rozgałęzienia.

Wykresy Gantta

Wykres Gantta zamienia listę zadań w oś czasu. Zadania mogą zaczynać się w określonym dniu lub after (po) innym zadaniu.

mermaidgantt
  title Sprint dokumentacyjny
  dateFormat YYYY-MM-DD
  section Pisanie
  Konspekt        :done,   a1, 2026-10-01, 2d
  Pierwszy szkic  :active, a2, after a1, 4d
  section Recenzja
  Recenzja zespołu :       a3, after a2, 3d
  Publikacja      :milestone, after a3, 0d

Diagramy stanów

Diagramy stanów opisują, jak coś przechodzi między stanami — zamówienie, dokument, komponent interfejsu.

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : wysłanie
  Review --> Draft : prośba o zmiany
  Review --> Published : akceptacja
  Published --> [*]

Wykresy kołowe

Aby szybko pokazać udział w całości, wykres kołowy potrzebuje jednego wiersza na wycinek:

mermaidpie title Na co idzie czas pracy nad dokumentacją
  "Pisanie" : 45
  "Formatowanie" : 15
  "Aktualizowanie diagramów" : 40

Mermaid obsługuje też diagramy klas, diagramy encji i relacji, mapy myśli, osie czasu, grafy Git, wykresy kwadrantowe i nie tylko. Składnia każdego z nich jest opisana na oficjalnej stronie Mermaid.

Wskazówki dla czytelnych diagramów

• Nie przesadzaj z rozmiarem. Diagram z ponad 15–20 węzłami staje się trudny do odczytania. Podziel go na kilka diagramów, po jednym na każdą myśl.
• Wybieraj kierunek świadomie. LR pasuje do procesów z niewielką liczbą kroków; TD do hierarchii i długich przepływów, zwłaszcza na wąskich ekranach.
• Używaj krótkich identyfikatorów i czytelnych etykiet. Pisz auth[Sprawdź sesję], zamiast używać etykiety jako identyfikatora — dzięki temu połączenia są krótkie.
• Etykiety ze znakami specjalnymi umieszczaj w cudzysłowie: A["Cena: $5 (z podatkiem)"].
• Dodawaj komentarze za pomocą %% na początku wiersza. Są pomijane podczas rysowania.
• Oglądaj podgląd podczas pisania. Brakująca strzałka lub nawias psuje cały diagram, więc podgląd na żywo oszczędza sporo zgadywania. W Markdown Preview Editor diagram jest rysowany na nowo podczas edycji, a przycisk Diagram Mermaid w rzędzie Edytor zaawansowany wstawia szablon startowy.

Udostępnianie dokumentów z diagramami

Gdy eksportujesz dokument do HTML lub PDF, diagramy są dołączane jako obrazy, więc czytelnik nie potrzebuje zainstalowanego Mermaid. Jeśli obok diagramów potrzebujesz wzorów, zobacz, jak pisać wzory matematyczne w Markdown, a do wszystkiego innego — tabel, list zadań, ramek — miej pod ręką ściągawkę Markdown.