Guia completo de diagramas Mermaid

O que é Mermaid?

Por que usar Mermaid?

• Controle de versão: diagramas são arquivos de texto, então podem ser rastreados no Git junto com seu código
• Atualizações rápidas: altere algumas linhas de texto em vez de redesenhar diagramas inteiros
• Consistência: o Mermaid cuida automaticamente do layout e do estilo, garantindo diagramas consistentes
• Sem ferramentas de design: não é necessário Visio, Lucidchart ou outras ferramentas caras
• Documentação como código: mantenha os diagramas no mesmo repositório da sua documentação
• Multiplataforma: funciona em navegadores e Node.js e se integra a muitas plataformas
• Gratuito e open source: sem custos de licença, comunidade ativa
• Múltiplos tipos de diagramas: suporta fluxogramas, diagramas de sequência, diagramas de classes e mais

Tipos de diagramas suportados

O Mermaid suporta uma ampla variedade de tipos de diagramas para diferentes necessidades de documentação:

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

Primeiros passos com Mermaid

Boas práticas

• Mantenha os diagramas focados em um único conceito ou fluxo de trabalho
• Use rótulos significativos que descrevam a lógica de negócio real
• Divida diagramas complexos em diagramas menores e interconectados
• Adicione comentários usando %% para explicar seções complexas
• Use convenções de nomenclatura consistentes em seus diagramas
• Teste seus diagramas no ambiente de destino antes de finalizá-los
• Inclua dicas de direção (TD, LR) para controlar o layout quando necessário
• Use subgraphs para agrupar nós relacionados em fluxogramas
• Use opções de estilo com moderação para manter a legibilidade
• Versione os arquivos de origem dos diagramas junto com seu código

Casos de uso comuns

Recursos adicionais

• Documentação oficial do Mermaid
• Repositório do Mermaid no GitHub
• Referência de sintaxe do Mermaid