Czym jest Mermaid#
Mermaid to narzędzie do tworzenia diagramów przez zapis tekstowy. Autor wpisuje deklaracje elementów i połączeń, a parser oraz renderer zamieniają je na obraz. Źródło może być umieszczone w Markdown, dzięki czemu diagram da się przechowywać obok opisu, wersjonować i zmieniać w zwykłym edytorze.
Mermaid oferuje składnie dla kilku rodzajów grafów, w tym diagramów przepływu, sekwencji, klas, stanów, relacji encji i diagramów Gantta. Podobieństwo wizualne nie oznacza jednak automatycznie zgodności z UML. Część typów odpowiada diagramom UML, a inne są ogólnymi formami wizualizacji. Nawet diagram klas Mermaid jest reprezentacją o określonej składni i zakresie, nie pełnym repozytorium modelu UML.
Przykład diagramu przepływu#
Poniższy przykład pokazuje decyzję o wyniku płatności. W tym artykule blok PlantUML służy rendererowi serwisu do utworzenia ilustracji, natomiast Mermaid ma własną składnię tekstową pokazaną w dalszej części.
W przykładzie strzałki oznaczają kolejność, a warunek rozdziela ścieżki. Właściwy diagram Mermaid można zapisać w bloku mermaid w obsługującym go edytorze lub rendererze, na przykład w postaci flowchart TD z węzłami i połączeniami. Kod musi być przetwarzany przez środowisko, które rozpoznaje Mermaid; sam Markdown nie gwarantuje wygenerowania obrazu.
Jak przebiega praca#
Typowy proces obejmuje zapis bloku Mermaid w pliku Markdown, uruchomienie renderera w edytorze, dokumentacji lub pipeline, a następnie podgląd wyniku. W wielu środowiskach składnia jest automatycznie wykrywana. W innych trzeba włączyć rozszerzenie albo etap kompilacji. Zanim zespół przyjmie Mermaid, powinien sprawdzić, czy platforma dokumentacyjna obsługuje wymaganą wersję składni i eksport do potrzebnego formatu.
Kod należy utrzymywać w czytelnym porządku: deklarować węzły z opisowymi identyfikatorami, unikać nadmiernie długich etykiet, dzielić złożony przepływ na mniejsze diagramy i kontrolować kierunek układu. Automatyczne rozmieszczenie pozwala szybko uzyskać grafikę, ale nie gwarantuje dobrej kompozycji. Węzły mogą ułożyć się inaczej po zmianie tekstu lub wersji renderera.
Mermaid a UML#
Mermaid jest dobrym wyborem do lekkiej dokumentacji technicznej, kiedy najważniejszy jest szybki, tekstowy zapis i czytelny obraz. Nie należy jednak nazywać każdego diagramu Mermaid diagramem UML. Wybierz typ zgodny z pytaniem, które chcesz modelować, i sprawdź, czy dostępna notacja ma potrzebne elementy oraz semantykę.
W modelu UML istotne mogą być m.in. dokładne rodzaje relacji, widoczność, krotności, ograniczenia, stereotypy i powiązania między elementami. Obsługa tych aspektów w tekstowym języku diagramów może być ograniczona lub różnić się od specyfikacji UML. Mermaid nie powinien być traktowany jako zamiennik narzędzia CASE, jeśli wymagane jest centralne repozytorium modelu, śledzenie elementów między diagramami, walidacja modelu lub wymiana kompletnego modelu w standardzie XMI.
Zalety i ograniczenia#
Zapis tekstowy dobrze pasuje do repozytoriów Git i przeglądu zmian. Diagram można szybko poprawić, skopiować i osadzić w dokumentacji. Niski próg wejścia ułatwia tworzenie prostych szkiców, a generowanie odbywa się automatycznie w obsługującym je środowisku.
Ograniczenia wynikają z zakresu języka i renderera. Automatyczny układ jest wygodny, ale daje mniej ręcznej kontroli nad rozmieszczeniem. Składnia wymaga nauczenia się, a błędy w identyfikatorach lub znakach specjalnych mogą zatrzymać renderowanie. Wynik zależy od obsługi po stronie platformy, wersji biblioteki i konfiguracji eksportu. Diagram wygenerowany poprawnie składniowo może nadal być niepoprawny merytorycznie.
Kiedy wybrać Mermaid#
Wybierz Mermaid, gdy chcesz utrzymywać niewielkie diagramy bezpośrednio w dokumentacji, pracować w repozytorium tekstowym i nie potrzebujesz rozbudowanego modelu współdzielonego. Rozważ PlantUML, jeśli zależy ci na szerszym zakresie składni diagramów i rozbudowanych możliwościach stylizacji tekstowej. Wybierz edytor graficzny, gdy ważne jest swobodne rozmieszczenie, a narzędzie CASE, gdy potrzebujesz spójnego modelu z walidacją, śledzeniem lub inżynierią kodu.
Przed decyzją zrób próbę na rzeczywistym diagramie: sprawdź składnię, czytelność po eksporcie, obsługę w docelowej dokumentacji, różnice w wersjonowaniu i dostępność procesu renderowania w CI. Rozstrzygnij także, czy diagram ma być jedynie ilustracją, czy formalnym modelem UML.