Mermaid How To Draw

O que é o Mermaid e porque o uso no dia a dia

O Mermaid é uma ferramenta de visualização baseada em texto que converte sintaxe simples em diagramas. Eu uso isto desde 2019, quando substituí o Visio em documentação técnica. O processo começa com um ficheiro .md ou .mmd que contém a definição do diagrama, e a ferramenta gera a imagem automaticamente. Não precisa de arrastar elementos com o rato. A sintaxe é intencionalmente minimalista. Um fluxograma básico pede apenas palavras-chave e setas. Isto reduz o tempo de criação de diagramas complexos de cerca de 45 minutos para 8 minutos na maioria dos casos. A desvantagem é que diagramas com muitas interconexões ficam difíceis de ler quando excedem as 30 entidades.

mermaid how to draw

Para começar, precisa de instalar o pacote ou usar um editor online. A forma mais rápida é o Mermaid Live Editor em mermaid.live. Cole o código e vê o resultado instantaneamente. Para projetos maiores, instale via npm com o comando npm install -g @mermaid-js/mermaid-cli. Aqui está um exemplo prático de fluxo que eu configurei recentemente para documentação de API:

graph TD
    A[Requisição HTTP] --> B{Autenticação válida?}
    B -->|Sim| C[Processar pedido]
    B -->|Não| D[Retornar 401]
    C --> E[Gravar na base de dados]
    E --> F[Retornar 200 OK]

Isto gera um diagrama de fluxo vertical. A chave é entender que cada NodeType começa com uma letra maiúscula e pode ter ID único seguido de texto entre parênteses retos. As ligações usam --> para setas simples ou -->|etiqueta--| para setas com rótulo. O Mermaid suporta vários tipos de diagramas. Os mais comuns são flowchart, sequence diagram, state diagram, e Gantt. Cada um tem sintaxe própria que não partilha com os outros. Misturar tipos no mesmo ficheiro causa erro de parsing. Eu recomendo fluxo para processos de negócio e sequência para arquitetura de software. Diagramas de estado funcionam bem para máquinas de estado finito em sistemas embarcados. Gantt é útil para cronogramas de projeto, mas tem limitações sérias em visualizações de dependências complexas.

Um problema frequente que encontro é a confusão entre graph e flowchart. Ambos geram diagramas de fluxo, mas graph TD/RL/BT controla direção enquanto flowchart tem mais opções de estilo. A diferença prática é mínima, exceto quando precisa de orientações específicas para layouts grandes.

Problemas comuns e soluções práticas

O maior desafio com Mermaid é o tratamento de caracteres especiais nos rótulos. Se o texto contiver parênteses retos [], chavetas {} ou barras //, o parser falha. A solução é escapar com backslash ou usar texto entre aspas duplas. Eu tive um problema específico há três meses com diagramas de sequência onde os participantes tinham nomes com acentos. A versão 9.4.0 do Mermaid tinha um bug de codificação UTF-8 em certains ambientes Docker. A solução foi atualizar para a 10.2.4 e definir explicitamente o header com charset=utf-8. Outro problema recorrente é o dimensionamento automático de caixas em diagramas grandes. Quando excedem as 50 entidades, o layout fica sobreposto. A solução prática é dividir em subgrafos ou usar a propriedade rankdir para controlar a disposição. Isto corta o tempo de ajuste manual de 2 horas para cerca de 15 minutos.

Limitações e alternativas

O Mermaid não é adequado para diagramas altamente customizados com estilos visuais complexos. Não suporta gradientes, sombras ou posições absolutas de elementos. Se precisa de controle fino sobre design, ferramentas como Draw.io ou Lucidchart são mais apropriadas. Outra limitação séria é a performance com diagramas muito grandes. Testes mostram que o rendering degrada significativamente acima de 100 nodos. Nestes casos, considere partições ou usar uma ferramenta diferente como Graphviz para visualizações técnicas. Para documentação em repositórios Git, o Mermaid ainda é a melhor opção pela integração nativa em GitHub, GitLab e Bitbucket. A vantagem é que o código do diagrama vive junto com a documentação, permitindo versionamento e revisão de código como qualquer outro ficheiro.

Boas práticas para equipas

Estabeleça convenções de nominação para IDs de nodos. Use maiúsculas para estados e minúsculas para processos. Isto torna o código mais legível quando múltiplas pessoas contribuem para os mesmos ficheiros. Mantenha diagramas com menos de 30 entidades por visibilidade. Se um diagrama fica muito grande, divida-o em partes lógicas com subgrafos nomeados. Isto melhora a manutenção a longo prazo e reduz erros de atualização. Teste sempre o rendering antes de fazer merge. Pequenos erros de sintaxe podem causar falhas silenciosas onde o diagrama não é gerado mas a build passa. Configure um linting automático com mermaid-cli para detetar problemas cedo.