Generator diagramów Mermaid

Generator diagramów Mermaid — diagramy z czystego tekstu

Mermaid to język opisu diagramów w tekstowej formie. Wspierają go GitHub, GitLab, Notion, Obsidian i Mermaid Live Editor. Zamiast rysować, opisujesz relacje — a diagram generuje się sam.

Jak zapisać relacje?

• Flowchart: A -> B — strzałka od A do B.
• Sekwencja: A -> B: wiadomość — wywołanie z opisem.
• Nazwy mogą zawierać spacje, np. Pobierz dane -> Przetwórz.

Do czego używać?

Wskazówki

• Trzymaj nazwy węzłów krótkie i jednoznaczne.
• Dla flowchart wybierz kierunek TD (procesy) lub LR (osie czasu).
• W diagramie sekwencji najpierw zdefiniuj uczestników, potem wiadomości.
• Złożone diagramy lepiej rozbić na kilka prostszych.

Jak działa generator Mermaid — od tekstu do grafu

Generator nie rysuje niczego samodzielnie. Wklejasz tekst, a narzędzie czyta go linia po linii i traktuje każdą linię jako osobną instrukcję. Pierwsza linia mówi, jaki to typ diagramu i w którą stronę ma się rozrastać, a kolejne linie opisują relacje między nazwami. Nie ma tu współrzędnych, warstw ani rysowania — graf powstaje wyłącznie z par nazw połączonych strzałką.

Z tych par budowana jest struktura złożona z dwóch list: lista węzłów i lista krawędzi. Węzły to unikalne nazwy, a krawędzie to pary nazw z linii z relacjami. Jeśli ta sama nazwa pojawia się w kilku liniach, do grafu trafia jeden węzeł, a nie kilka — dlatego element powtarzany w środku diagramu i na jego początku jest tym samym elementem. Każda linia z relacją dodaje dokładnie jedną krawędź, a tekst wpisany w etykiecie po strzałce staje się opisem tej konkretnej krawędzi.

Dopiero potem wchodzi układ. Algorytm warstwowy rozstawia węzły w kolejnych warstwach zgodnie z zadeklarowanym kierunkiem i prowadzi między nimi linie, a renderer zamienia wynik na obraz SVG. Cały proces jest deterministyczny: ten sam kod daje za każdym razem ten sam diagram, a zmiana jednej linii zmienia układ grafu, nie tylko jego opis.

Przykład krok po kroku: flowchart z decyzją i pętlą

1. Wklej blok złożony z 6 linii: w pierwszej linii deklaracja flowchart TD, w pięciu kolejnych relacje — A -> B, B -> C, C -> D, D -> E oraz krawędź zwrotna D -> B.
2. Nazwij węzły po ludzku: Start, Pobierz dane, Przetwórz, Poprawne, Zapisz. Spacje w nazwach są dozwolone, więc nie musisz ich skracać do pojedynczych liter.
3. Policz węzły. W kodzie jest 5 różnych nazw, więc graf ma 5 węzłów — mimo że nazwy występują w liniach łącznie 10 razy.
4. Policz krawędzie. Pięć linii z relacjami daje 5 krawędzi, czyli dokładnie tyle, ile jest strzałek w tekście.
5. Dodaj etykiety do dwóch krawędzi wychodzących z węzła decyzyjnego: tak prowadzi do Zapisz, nie wraca do Przetwórz. Liczba krawędzi pozostaje bez zmian i wynosi 5, zmienia się tylko ich opis.
6. Wygeneruj diagram i sprawdź wynik. Powstały graf ma 5 węzłów i 5 krawędzi, z czego jedna tworzy cykl — jeśli rysunek jest zbyt zagęszczony, zmień kierunek na LR albo uprość warunek decyzyjny.

Składnia Mermaid — tabela referencyjna

Praktyczne wskazówki przy pisaniu kodu Mermaid

• Jedna deklaracja typu na blok — pierwsza linia określa cały diagram. Dodanie drugiej deklaracji w środku kodu rozbija spójność i najczęściej kończy się błędem renderowania.
• Pisz relacje w osobnych liniach — jedna linia, jedna krawędź. Dzięki temu łatwo policzysz węzły i strzałki oraz poprawisz pojedynczy fragment bez ruszania reszty.
• Uważaj na znaki zarezerwowane — nawiasy, średniki i dwukropki w nazwach mogą zostać odczytane jako element składni. Jeśli nazwa ich wymaga, uprość ją przed wklejeniem.
• Etykietuj tylko krawędzie decyzyjne — opis na każdej strzałce zagęszcza rysunek. Etykiety zostaw tam, gdzie faktycznie zmieniają sens przepływu.
• Trzymaj jeden blok kodu w jednym miejscu — jeśli diagram ma trafić do repozytorium, wklej go jako blok oznaczony mermaid i nie duplikuj tej samej treści w opisie obok.

Ograniczenia generatora Mermaid

• Błędy składni nie są naprawiane — narzędzie nie zgaduje intencji. Brak strzałki, niedomknięty nawias albo literówka w deklaracji kończą się brakiem diagramu lub komunikatem błędu, a nie automatyczną korektą.
• Układu nie ustawisz ręcznie — o pozycji węzłów, odległościach i rozmiarze decyduje algorytm oraz wybrany kierunek. Nie ma opcji przesuwania pojedynczego elementu ani wymuszania konkretnej warstwy.
• Logika procesu nie jest weryfikowana — diagram poprawny składniowo może opisywać proces, który w rzeczywistości nie ma sensu. Narzędzie sprawdza zapis, nie zgodność z rzeczywistym przebiegiem pracy.
• Duże grafy tracą czytelność — wraz z liczbą węzłów i krawędzi zwrotnych rysunek gęstnieje. Generator nie skraca etykiet, nie ukrywa węzłów ani nie dzieli diagramu na części.

Najczęstsze pytania