Kompletny przewodnik po diagramach Mermaid

Czym jest Mermaid?

Dlaczego warto używać Mermaid?

• Kontrola wersji: diagramy to pliki tekstowe, więc można je śledzić w Git razem z kodem
• Szybkie aktualizacje: zmień kilka linii tekstu zamiast przerysowywać całe diagramy
• Spójność: Mermaid automatycznie zajmuje się układem i stylem, zapewniając spójne diagramy
• Brak narzędzi graficznych: nie potrzebujesz Visio, Lucidchart ani innych drogich narzędzi
• Dokumentacja jako kod: trzymaj diagramy w tym samym repozytorium co dokumentację
• Wieloplatformowość: działa w przeglądarkach i Node.js oraz integruje się z wieloma platformami
• Darmowe i open source: brak kosztów licencji, aktywna społeczność
• Wiele typów diagramów: obsługuje schematy blokowe, diagramy sekwencji, klas i inne

Obsługiwane typy diagramów

Mermaid obsługuje szeroką gamę typów diagramów, aby sprostać różnym potrzebom dokumentacji:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id
        string name
        string email
    }

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Pierwsze kroki z Mermaid

Dobre praktyki

• Skupiaj diagramy na jednym koncepcie lub przepływie pracy
• Używaj znaczących etykiet opisujących rzeczywistą logikę biznesową
• Dziel złożone diagramy na mniejsze, połączone ze sobą diagramy
• Dodawaj komentarze z użyciem %%, aby wyjaśniać złożone sekcje
• Stosuj spójne konwencje nazewnictwa w diagramach
• Testuj diagramy w środowisku docelowym przed ich finalizacją
• Dodawaj wskazówki kierunku (TD, LR), aby kontrolować układ, gdy to potrzebne
• Używaj subgraphów do grupowania powiązanych węzłów w schematach blokowych
• Używaj opcji stylu oszczędnie, aby zachować czytelność
• Wersjonuj pliki źródłowe diagramów razem z kodem

Typowe zastosowania

Dodatkowe zasoby

• Oficjalna dokumentacja Mermaid
• Repozytorium Mermaid na GitHub
• Referencja składni Mermaid