Szybki start i karta cheat sheet dla diagramów Mermaid dla programistów
Diagramy jako kod, bez zbędnych komplikacji.
Mermaid to narzędzie do tworzenia diagramów oparte na tekście, przeznaczone dla osób, które wolą pisać diagramy niż przeciągać kwadraty po płótnie. Wykorzystuje składnię podobną do Markdownu do opisu schematów blokowych, diagramów sekwencji, diagramów klas, maszyn stanów, osi czasu, diagramów Gantta, diagramów relacji encji i wielu innych.
Dla technicznego bloga Mermaid jest bardzo dobrym domyślnym wyborem. Diagramy znajdują się obok artykułu, można je przeglądać w Git, a ich aktualizacja po zmianach w systemie jest łatwa. Statyczne diagramy obrazkowe wyglądają dobrze, dopóki nie nastąpi pierwsza zmiana architektury. Diagramy Mermaid nie są idealne, ale starzeją się znacznie lepiej.
Ten przewodnik to praktyczny szybki start i karta ściągowa Mermaid dla programistów, autorów dokumentacji technicznej oraz właścicieli stron opartych na Hugo. Jest częścią centrum Narzędzia do dokumentacji w 2026 roku: Markdown, LaTeX, PDF i przepływy pracy drukowania.
Czym jest Mermaid?
Mermaid to składnia diagramów jako kodu. Piszesz mały blok tekstu, a Mermaid renderuje go jako diagram.
Podstawowy diagram Mermaid wygląda następująco:
ten kod:
```mermaid
flowchart TD
A[Napisz Markdown] --> B[Dodaj blok Mermaid]
B --> C[Renderuj stronę]
C --> D[Opublikuj diagram]
```
Tworzy diagram:
Główna koncepcja jest prosta: źródłem diagramu jest zwykły tekst. Dzięki temu jest on przeszukiwalny, możliwy do przeglądu, przenośny i łatwy do utrzymania wraz z dokumentacją, którą objaśnia.
Dlaczego używać Mermaid w technicznym blogu?
Mermaid jest przydatny, gdy Twój artykuł wymaga czegoś więcej niż prozy, ale mniej niż pełnoprawnego narzędzia projektowego.
Używaj Mermaid, gdy chcesz wyjaśnić:
- Przepływy żądań i odpowiedzi
- Potoki wdrażania
- Zależności usług
- Przejścia stanów
- Relacje w bazie danych
- Ścieżki użytkowników
- Kroki budowania
- Logikę decyzyjną
- Harmonogramy projektów
Nie używałbym Mermaidu do każdej grafiki. Zrzuty ekranu, odręczne szkice architektury i dopracowane diagramy marketingowe nadal mają swoje miejsce. Ale dla dokumentacji inżynierskiej Mermaid jest często najbardziej łatwym w utrzymaniu rozwiązaniem.
Szybki start z Mermaid
Podstawowe użycie w Markdown
W Markdownie użyj ogrodzonego bloku kodu z mermaid jako językiem:
```mermaid
flowchart LR
A[Start] --> B[Proces]
B --> C[Koniec]
```
Wiele platform rozumie ten format bezpośrednio. mermaid jest jednym z specjalnych identyfikatorów języków — obok diff, geojson i innych — które pewne renderery traktują jako typ bloku pierwszoklasowego, a nie tylko jako zwykłe kolorowanie składni. Aby poznać pełen przegląd składni bloków ogrodzonych i obsługiwanych identyfikatorów języków, zobacz Przewodnik po blokach kodu Markdown. W przypadku Hugo renderowanie zależy od motywu lub konfiguracji strony. O tym później.
Testuj diagramy przed publikacją
Najłatwiejszy przepływ pracy to:
- Napisz diagram w pliku Markdown.
- Wklej go do interaktywnego edytora Mermaid lub podglądu lokalnego.
- Napraw błędy składniowe.
- Zatwierdź źródło Markdown.
- Sprawdź ostatecznie wyrenderowaną stronę.
Unika to klasycznego problemu, w którym diagram działa w jednym rendererze, ale psuje się w innym ze względu na drobną szczegółowość składniową.
Składnia schematów blokowych
Schematy blokowe są najczęstszy typem diagramów Mermaid. Używaj ich do przepływów pracy, algorytmów, dróg decyzyjnych i kroków systemowych.
Podstawowy schemat blokowy
ten kod:
```mermaid
flowchart TD
A[Użytkownik otwiera witrynę] --> B{Czy użytkownik jest zalogowany?}
B -->|Tak| C[Pokaż panel]
B -->|Nie| D[Pokaż stronę logowania]
```
Tworzy diagram:
Kierunki schematów blokowych
Schematy blokowe Mermaid obsługują kilka kierunków:
TD - od góry do dołu
TB - od góry do dołu
BT - od dołu do góry
LR - od lewej do prawej
RL - od prawej do lewej
Przykład:
ten kod:
```mermaid
flowchart LR
Przeglądarka --> CDN
CDN --> SerwerWWW
SerwerWWW --> BazaDanych
```
Tworzy diagram:
Dla artykułów blogowych LR (od lewej do prawej) jest często łatwiejszy do odczytu w diagramach architektury. Dla procesów krok po kroku TD (od góry do dołu) jest zwykle lepszy.
Popularne kształty węzłów
ten kod:
```mermaid
flowchart TD
A[Prostokąt]
B(Obramowany prostokąt)
C{Decyzja}
D((Kółko))
E[(Baza danych)]
F[[Podprocedura]]
```
Tworzy diagram:
Strzałki w schematach blokowych
ten kod:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Etykieta --> F
```
Tworzy diagram:
Podgrafy
Używaj podgrafów do grupowania powiązanych części systemu.
ten kod:
```mermaid
flowchart LR
subgraph Klient
Przeglądarka
end
subgraph Backend
API
Worker
end
subgraph Przechowywanie
DB[(PostgreSQL)]
Cache[(Redis)]
end
Przeglądarka --> API
API --> DB
API --> Cache
API --> Worker
```
Tworzy diagram:
Podgrafy są potężne, ale używaj ich ostrożnie. Diagram z sześcioma podgrafami i dwudziestoma strzałkami to zwykle sygnał, że artykuł potrzebuje dwóch mniejszych diagramów.
Składnia diagramów sekwencji
Diagramy sekwencji pokazują komunikację między aktorami lub usługami w czasie.
ten kod:
```mermaid
sequenceDiagram
participant Użytkownik
participant Aplikacja
participant API
participant DB
Użytkownik->>Aplikacja: Kliknij logowanie
Aplikacja->>API: POST /login
API->>DB: Zweryfikuj dane uwierzytelniające
DB-->>API: Rekord użytkownika
API-->>Aplikacja: Token dostępu
Aplikacja-->>Użytkownik: Pokaż panel
```
Tworzy diagram:
Popularne strzałki sekwencji
-> pełna linia bez strzałki
--> linia przerywana bez strzałki
->> pełna linia ze strzałką
-->> linia przerywana ze strzałką
-x pełna linia z krzyżykiem
--x linia przerywana z krzyżykiem
Paski aktywacji
Paski aktywacji wyraźniej pokazują, kiedy uczestnik wykonuje pracę.
ten kod:
```mermaid
sequenceDiagram
participant Klient
participant Serwer
Klient->>Serwer: Żądaj danych
activate Serwer
Serwer-->>Klient: Odpowiedź
deactivate Serwer
```
Tworzy diagram:
Alternatywy i warunki
ten kod:
```mermaid
sequenceDiagram
participant Użytkownik
participant API
participant Płatność
Użytkownik->>API: Prześlij zamówienie
alt Płatność udana
API->>Płatność: Obciąż kartę
Płatność-->>API: Zatwierdzone
API-->>Użytkownik: Zamówienie potwierdzone
else Płatność nieudana
Płatność-->>API: Odrzucone
API-->>Użytkownik: Pokaż błąd
end
```
Tworzy diagram:
Diagramy sekwencji są doskonałe dla artykułów o API. Pokazują nie tylko, jakie komponenty istnieją, ale też jak się ze sobą komunikują.
Składnia diagramów klas
Diagramy klas są przydatne dla modeli domenowych i relacji obiektowych.
ten kod:
```mermaid
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
```
Tworzy diagram:
Relacje klas
<|-- dziedziczenie
*-- kompozycja
o-- agregacja
--> asocjacja
-- link
..> zależność
..|> realizacja
Przykład:
ten kod:
```mermaid
classDiagram
Zwierzę <|-- Pies
Zwierzę <|-- Kot
Użytkownik "1" --> "*" Zamówienie
Zamówienie *-- PozycjaZamówienia
```
Tworzy diagram:
Diagramy klas mogą szybko stać się chaotyczne. W poście blogowym wol preferuj mały fragment domeny niż pełny model aplikacji.
Składnia diagramów stanów
Diagramy stanów wyjaśniają, jak coś zmienia się w czasie.
ten kod:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Published: approve
Review --> Draft: request changes
Published --> Archived: archive
Archived --> [*]
```
Tworzy diagram:
Używaj diagramów stanów do:
- Cykli życia zamówień
- Stanów wdrażania
- Przepływów uwierzytelniania
- Statusu zadań w tle
- Przepływów publikacji treści
Diagramy stanów są niedoceniane. Często wyjaśniają logikę biznesową lepiej niż długi akapit.
Składnia diagramów relacji encji
Diagramy relacji encji są przydatne dla modeli baz danych.
ten kod:
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
```
Tworzy diagram:
Markery relacji ER
|| dokładnie jeden
o| zero lub jeden
}| jeden lub więcej
}o zero lub więcej
Diagramy ER są najlepsze, gdy wyjaśniają relacje, a nie każdy kolumnę. Zachowaj szczegóły implementacyjne w migracjach lub dokumentacji schematu.
Składnia diagramów Gantta
Diagramy Gantta są przydatne do harmonogramów projektów.
ten kod:
```mermaid
gantt
title Plan migracji dokumentacji
dateFormat YYYY-MM-DD
section Planowanie
Audyt aktualnej dokumentacji :a1, 2026-06-01, 5d
Zdefiniuj strukturę :a2, after a1, 3d
section Pisanie
Przepisz przewodniki :b1, after a2, 10d
Przegląd i publikacja :b2, after b1, 4d
```
Tworzy diagram:
Diagramy Gantta są pomocne w wewnętrznych postach planistycznych, ale mogą szybko się starzeć. Używaj ich, gdy sam harmonogram jest punktem głównym.
Składnia osi czasu
Osie czasu są dobre do historii wydań, raportów incydentów i streszczeń projektów.
ten kod:
```mermaid
timeline
title Evolucja API
2024 : REST API uruchomione
2025 : Dodano Webhooks
2026 : Wprowadzono strumieniowanie zdarzeń
```
Tworzy diagram:
Używaj osi czasu, gdy kolejność ma większe znaczenie niż zależności. Jeśli zależy Ci na sekwencji zdarzeń, a nie na tym, jak są one przyczynowo połączone, oś czasu utrzymuje fokus w odpowiednim miejscu i jest łatwa do szybkiego odczytania.
Składnia wykresów kołowych
Wykresy kołowe są obsługiwane, ale bądź ostrożny. Są łatwe do odczytania, gdy jest tylko kilka kategorii, a wartości są wyraźnie różne.
ten kod:
```mermaid
pie title Czas budowania według etapu
"Instalacja zależności" : 35
"Uruchomienie testów" : 45
"Budowanie zasobów" : 20
```
Tworzy diagram:
Rada od autora: jeśli wartości są zbliżone lub jest więcej niż pięć kategorii, użyj tabeli. Dobrze sformatowana tabela komunikuje dokładne liczby bardziej uczciwie niż wykres kołowy, gdzie wycinki wyglądają niemal identycznie.
Składnia grafów Git
Grafy Git mogą wyjaśniać strategie gałęzi i przepływy wydawnicze.
ten kod:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Tworzy diagram:
Jest to przydatne w artykułach o przepływach pracy Git, rozwoju opartym na gałęzi głównej, gałęziach wydawniczych i poprawkach awaryjnych. Jeśli potrzebujesz szybkiego odniesienia do poleceń dotyczących gałęzi, Ściągawka GIT obejmuje najczęstsze z nich wraz z przepływami pracy merge i rebase.
Ściągawka Mermaid
Typy diagramów
flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey
Podstawy schematów blokowych
flowchart TD
A[Tekst] --> B[Tekst]
A -->|Etykieta| B
A -.-> B
A ==> B
A --- B
Kształty w schematach blokowych
A[Prostokąt]
A(Obramowany)
A{Decyzja}
A((Kółko))
A[(Baza danych)]
A[[Podprocedura]]
A>Flaga]
Podstawy diagramów sekwencji
sequenceDiagram
participant A
participant B
A->>B: Wiadomość
B-->>A: Odpowiedź
activate B
deactivate B
Bloki sekwencji
alt warunek
else inny warunek
end
opt opcjonalny krok
end
loop dla każdego elementu
end
par zadanie równoległe
and kolejne zadanie
end
Podstawy diagramów klas
classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order
Podstawy diagramów stanów
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]
Podstawy diagramów ER
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
Komentarze
Mermaid obsługuje komentarze z %%.
ten kod:
```mermaid
flowchart TD
%% To jest komentarz
A --> B
```
Tworzy diagram:
Używanie Mermaid w Hugo
Zawartość Hugo jest zwykle pisana w Markdownie, więc Mermaid naturalnie pasuje do technicznego bloga opartego na Hugo. Dokładna konfiguracja zależy od Twojego motywu i konfiguracji renderowania Markdown.
Wzór autorstwa jest nadal ten sam:
```mermaid
flowchart LR
Markdown --> Hugo
Hugo --> HTML
HTML --> Przeglądarka
```
Jeśli Twój motyw Hugo już obsługuje Mermaid, może to się renderować bez dodatkowej pracy. Jeśli nie, zwykle potrzebujesz render hook, shortcode, partialu lub konfiguracji motywu, która ładuje Mermaid na stronach zawierających diagramy Mermaid.
Praktyczna konfiguracja Hugo powinna dążyć do tych zasad:
- Trzymaj źródło Mermaid w zwykłych artykułach Markdown.
- Ładuj Mermaid tylko na stronach, które go potrzebują.
- Unikaj globalnego JavaScriptu, jeśli większość stron nie używa diagramów.
- Testuj diagramy podczas podglądu lokalnego.
- Zachowaj źródło diagramu czytelne w Git.
Dla technicznego bloga ogrodzone bloki kodu są zwykle lepsze niż niestandardowe shortcodes, ponieważ są bardziej przenośne. Jeśli później przeniesisz zawartość na GitHub, inny generator statycznych stron lub platformę dokumentacji, standardowe ogrodzone bloki Mermaid są łatwiejsze do ponownego wykorzystania.
Najlepsze praktyki Mermaid
Trzymaj diagramy małe
Diagram powinien wyjaśniać artykuł, a go nie zastępować. Jeśli czytelnicy muszą przybliżać obraz, diagram jest prawdopodobnie za duży.
Dobre diagramy zwykle mają:
- Jedną ideę
- Jasny kierunek
- Krótkie etykiety
- Mało przecinających się linii
- Spójne nazewnictwo
Preferuj wiele małych diagramów
Zamiast jednego ogromnego diagramu systemu, użyj kilku skupionych diagramów:
- Przepływ żądań
- Topologia wdrażania
- Model danych
- Cykl życia stanu
- Ścieżka awarii
Jest to lepsze dla czytelników i lepsze dla ekranów mobilnych.
Używaj stabilnych nazw
Używaj nazw pasujących do Twojego kodu, API lub dokumentacji. Nie nazywaj tego samego elementu API, Backend i Serwer w różnych diagramach, chyba że są to naprawdę różne koncepcje.
Oznaczaj ważne strzałki
Strzałki bez etykiet są w porządku dla prostych schematów blokowych. W diagramach systemowych etykiety często mają znaczenie.
ten kod:
```mermaid
flowchart LR
Web -->|Żądanie HTTPS| API
API -->|Zapytanie SQL| DB
API -->|Publikuj zdarzenie| Kolejka
```
Tworzy diagram:
Unikaj kunsztownej składni
Mermaid potrafi wiele rzeczy. Nie oznacza to, że każdy artykuł potrzebuje wszystkiego. Wol preferuj składnię, którą przyszły opiekun może zrozumieć szybko.
Cytuj etykiety, gdy to konieczne
Jeśli etykieta zawiera znaki, które mylą Mermaid, otocz ją cudzysłowem.
ten kod:
```mermaid
flowchart TD
A["Użytkownik klika /checkout"] --> B["POST /api/orders"]
```
Tworzy diagram:
To mała nawyka, która zapobiega irytującym błędom renderowania.
Zastanów się nad trybem ciemnym
Wiele stron Hugo obsługuje tryb ciemny. Upewnij się, że motyw Mermaid lub CSS strony utrzymuje diagramy czytelne zarówno w wyglądzie jasnym, jak i ciemnym.
Częste błędy Mermaid
Błąd 1: Za dużo szczegółów
Złe diagramy Mermaid często próbują pokazać każdy przypadek krańcowy. Sprawia to, że są one technicznie kompletne, ale praktycznie nieczytelne. Rozwiązanie jest prawie zawsze takie samo: podziel diagram na dwa lub trzy mniejsze, z których każdy pokrywa jedną kwestię, aby czytelnicy mogli śledzić logikę bez konieczności śledzenia tuzina przecinających się strzałek.
Błąd 2: Długie etykiety
Długie etykiety tworzą szerokie pola i brzyde układy.
Zamiast tego kodu:
```mermaid
flowchart TD
A[Użytkownik przesyła formularz rejestracyjny ze swoim adresem e-mail i hasłem]
```
Tworzy diagram:
Wol preferuj ten kod:
```mermaid
flowchart TD
A[Prześlij formularz rejestracyjny]
```
Tworzy diagram:
Wyjaśnij szczegóły w akapicie poniżej diagramu.
Błąd 3: Niejasny kierunek
Wybierz kierunek i trzymaj się go. Większość diagramów procesowych powinna używać TD. Większość diagramów architektonicznych jest łatwiejsza z LR.
Błąd 4: Traktowanie Mermaid jako narzędzia projektowego
Mermaid to nie Figma. Nie jest przeznaczony do diagramów idealnie dokładnych pikselowo, a próba wymuszenia tej roli zakończy się tylko frustracją. Jego siłą jest łatwość utrzymania, a nie wizualna doskonałość — i ten kompromis jest intencjonalny.
Wskazówki SEO dla Mermaid w technicznych blogach
Diagramy Mermaid mogą czynić techniczne artykuły bardziej użytecznymi, ale wyszukiwarki nadal potrzebują tekstu. Nie polegaj tylko na diagramach.
Dla przyjaznych dla SEO artykułów z Mermaid:
- Używaj opisowych nagłówków H2 i H3.
- Wyjaśniaj każdy diagram w pobliskim tekście.
- Dołączaj ważne słowa kluczowe w zwykłej prozie.
- Zachowaj przykłady kodu gotowe do skopiowania.
- Dodaj wyjaśnienie typu alt pod skomplikowanymi diagramami.
- Używaj zwięzłego tytułu i opisu w front matter.
- Unikaj ukrywania całego znaczenia wewnątrz wyrenderowanego SVG.
Diagram Mermaid powinien wspierać artykuł. Nie powinien być jedynym miejscem, gdzie istnieje ważna informacja.
Przykłady Mermaid do skopiowania
Przepływ żądań API
ten kod:
```mermaid
sequenceDiagram
participant Klient
participant API
participant Auth
participant DB
Klient->>API: GET /account
API->>Auth: Zweryfikuj token
Auth-->>API: Token ważny
API->>DB: Załaduj konto
DB-->>API: Dane konta
API-->>Klient: 200 OK
```
Tworzy diagram:
Potok CI
ten kod:
```mermaid
flowchart TD
A[Push commit] --> B[Instaluj zależności]
B --> C[Uruchom lint]
C --> D[Uruchom testy]
D --> E[Buduj stronę]
E --> F[Wdrożenie]
```
Tworzy diagram:
Ten wzór naturalnie mapuje się na rzeczywistą konfigurację CI. Aby poznać składnię krok po kroku przepływów pracy GitHub Actions, Ściągawka GitHub Actions jest przydatnym towarzyszem, gdy chcesz przekształcić powyższy diagram w działający potok.
Przepływ publikacji
ten kod:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
```
Tworzy diagram:
Prosty model danych
ten kod:
```mermaid
erDiagram
AUTOR ||--o{ POST : writes
POST ||--o{ KOMENTARZ : receives
AUTOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
KOMENTARZ {
string id
string body
}
```
Tworzy diagram:
Kiedy nie używać Mermaid
Nie używaj Mermaid, gdy:
- Diagram wymaga precyzyjnego układu wizualnego.
- Design musi idealnie pasować do systemu marki.
- Grafika jest głównie dekoracyjna.
- Diagram ma za dużo węzłów, aby można go było czytać.
- Zrzut ekranu wyjaśniłby pointę lepiej.
- Zawartość rzadko się zmienia i potrzebuje więcej dopracowania niż łatwości utrzymania.
Mermaid jest doskonały do żywej dokumentacji technicznej. Jest mniej dobry do dzieł sztuki prezentacyjnej. Dla diagramów jakości dokumentu w kontekstach druku lub PDF, LaTeX oferuje pakiety takie jak TikZ i pgfplots, które dają Ci znacznie większą kontrolę nad układem — Ściągawka LaTeX obejmuje wstawianie diagramów wraz z resztą zestawu narzędzi LaTeX.
Podsumowanie
Mermaid to jedno z najlepszych narzędzi do technicznego blogowania, ponieważ szanuje sposób, w jaki programiści już pracują: pliki tekstowe, Markdown, Git, code review i powtarzalne budowania. Dla wszystkiego wokół diagramów — nagłówki, listy, tabele, bloki kodu — Ściągawka Markdown jest towarzyszącym przewodnikiem szybkiego odniesienia do trzymania obok tego przewodnika.
Najlepsze diagramy Mermaid nie są najbardziej skomplikowanymi. Są to diagramy, które czynią koncepcję oczywistą i pozostają łatwe do edycji sześć miesięcy później.
Używaj Mermaid do diagramów, które powinny żyć wraz z Twoją dokumentacją. Trzymaj je małe, trzymaj je czytelne i traktuj je jako część kodu źródłowego Twojego artykułu.
