Diagramas Mermaid em Markdown: fluxogramas, diagramas de sequência e mais

Diagramas explicam processos, arquiteturas e cronogramas melhor do que parágrafos de texto. Mas desenhá-los em um editor gráfico significa exportar imagens, guardá-las ao lado da documentação e redesenhar tudo quando algo muda.

O Mermaid resolve isso: você descreve o diagrama em poucas linhas de texto dentro do arquivo Markdown, e o visualizador o desenha. O diagrama fica no mesmo arquivo, aparece nos diffs e é atualizado tão facilmente quanto uma frase. GitHub, GitLab, Obsidian, muitos geradores de documentação e o Markdown Preview Editor renderizam Mermaid sem configuração.

Como adicionar um diagrama Mermaid

Crie um bloco de código e defina a linguagem como mermaid:

markdown```mermaid
flowchart LR
  A[Escrever] --> B[Visualizar]
  B --> C{Pronto?}
  C -- sim --> D[Exportar]
  C -- não --> A
```

O visualizador transforma isso em:

A primeira linha indica o tipo de diagrama. Tudo o que vem depois descreve os nós e as conexões.

Fluxogramas

Fluxogramas são o tipo de diagrama mais usado. A direção vem depois da palavra-chave: TD ou TB (de cima para baixo), BT, LR (da esquerda para a direita) ou RL.

mermaidflowchart TD
  start([Início]) --> input[/Ler o arquivo/]
  input --> valid{É válido?}
  valid -- Sim --> save[(Salvar no banco de dados)]
  valid -- Não --> error[Mostrar um erro]
  error --> input

Os delimitadores em volta do rótulo definem o formato do nó:

Conexões: --> é uma seta, --- uma linha sem seta, -.-> uma seta pontilhada e ==> uma seta grossa. Adicione um rótulo com -- text --> ou -->|text|.

Agrupe nós relacionados com subgraph:

mermaidflowchart LR
  subgraph Navegador
    editor[Editor] --> preview[Visualização]
  end
  preview --> export[HTML / PDF]

Diagramas de sequência

Diagramas de sequência mostram como os participantes trocam mensagens ao longo do tempo — ideais para APIs, fluxos de autenticação e jornadas do usuário.

mermaidsequenceDiagram
  participant U as Usuário
  participant A as App
  participant S as Servidor
  U->>A: Clica em "Entrar"
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Mostra o painel
  Note over A,S: O token expira após 1 hora

->> é uma seta contínua (uma requisição), -->> uma seta tracejada (uma resposta). Note over, Note left of e Note right of adicionam comentários. Use os blocos loop, alt/else e opt para mostrar repetições e ramificações.

Gráficos de Gantt

Um gráfico de Gantt transforma uma lista de tarefas em uma linha do tempo. As tarefas podem começar em uma data ou after (depois de) outra tarefa.

mermaidgantt
  title Sprint de documentação
  dateFormat YYYY-MM-DD
  section Escrita
  Estrutura         :done,   a1, 2026-10-01, 2d
  Primeiro rascunho :active, a2, after a1, 4d
  section Revisão
  Revisão por pares :        a3, after a2, 3d
  Publicação        :milestone, after a3, 0d

Diagramas de estado

Diagramas de estado descrevem como algo passa de um estado para outro — um pedido, um documento, um componente de interface.

mermaidstateDiagram-v2
  [*] --> Rascunho
  Rascunho --> Revisão : enviar
  Revisão --> Rascunho : alterações solicitadas
  Revisão --> Publicado : aprovar
  Publicado --> [*]

Gráficos de pizza

Para uma visão rápida de proporções, um gráfico de pizza usa uma linha por fatia:

mermaidpie title Para onde vai o tempo da documentação
  "Escrever" : 45
  "Formatar" : 15
  "Manter os diagramas atualizados" : 40

O Mermaid também suporta diagramas de classes, diagramas entidade-relacionamento, mapas mentais, linhas do tempo, gráficos do Git, gráficos de quadrantes e mais. A sintaxe de cada um está documentada no site oficial do Mermaid.

Dicas para diagramas legíveis

• Mantenha-os pequenos. Um diagrama com mais de 15–20 nós fica difícil de ler. Divida-o em vários diagramas, um por ideia.
• Escolha a direção com intenção. LR combina com processos de poucas etapas; TD combina com hierarquias e fluxos longos, principalmente em telas estreitas.
• Use IDs curtos e rótulos legíveis. Escreva auth[Verificar a sessão] em vez de usar o rótulo como ID — isso mantém as conexões curtas.
• Coloque entre aspas os rótulos com caracteres especiais: A["Preço: $5 (com impostos)"].
• Adicione comentários com %% no início da linha. Eles são ignorados no desenho.
• Visualize enquanto digita. Uma seta ou um colchete faltando quebra o diagrama inteiro, então uma visualização ao vivo evita muita adivinhação. No Markdown Preview Editor, o diagrama é redesenhado enquanto você edita, e o botão Diagrama Mermaid na barra do Editor avançado insere um modelo inicial.

Compartilhar documentos com diagramas

Ao exportar um documento para HTML ou PDF, os diagramas são incluídos como imagens, então o leitor não precisa ter o Mermaid instalado. Para fórmulas ao lado dos seus diagramas, veja como escrever fórmulas matemáticas em Markdown e, para todo o resto — tabelas, listas de tarefas, avisos —, tenha sempre à mão o guia rápido de Markdown.