Sintaxe de Diagramas Mermaid: Exemplos para Markdown e Obsidian

Um diagrama Mermaid é uma representação visual gerada a partir de código em texto simples utilizando a biblioteca Mermaid JS. Criado por Knut Sveidqvist por volta de 2014, este projeto open source Mermaid cresceu para se tornar o padrão para diagramas baseados em texto em documentação de software. Em 2026, as principais plataformas, incluindo GitHub, GitLab e ferramentas de documentação, renderizam a sintaxe Mermaid nativamente.

Este guia explica a sintaxe Mermaid, os principais tipos de diagramas, a renderização em Markdown e Obsidian, opções de exportação e pontos de falha comuns.

Eis como se parece a sintaxe básica:

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

A abordagem de “diagramas como código” melhora a legibilidade e a manutenção através do controlo de versões e simplifica a colaboração entre equipas de engenharia. As secções seguintes cobrem tipos de diagramas comuns, a criação passo a passo e como exportar diagramas para partes interessadas que preferem imagens estáticas.

Guia Rápido de Sintaxe Mermaid

Diagrama	Palavra-chave de abertura	Uso típico
Fluxograma	flowchart TD ou flowchart LR	Processos e decisões
Sequência	sequenceDiagram	Pedidos, respostas e interações de serviços
Entidade-Relação	erDiagram	Entidades e relações de bases de dados
Estado	stateDiagram-v2	Mudanças de estado e ciclo de vida
Gantt	gantt	Marcos e cronogramas
Classe	classDiagram	Modelos de domínio e de objetos

Cada bloco Mermaid precisa de uma palavra-chave de abertura. Os IDs de nó devem permanecer curtos e estáveis; os rótulos visíveis podem conter texto legível mais longo.

O que é um diagrama Mermaid e por que deve usá-lo?

Um diagrama Mermaid é gerado a partir de uma sintaxe de texto leve interpretada pela biblioteca JavaScript Mermaid. Em vez de usar uma interface de arrastar e largar, escreve código de diagrama Mermaid que a biblioteca converte em gráficos SVG.

Como o código Mermaid se transforma em elementos visuais:

• graph TD; A –> B; renderiza como um fluxograma de cima para baixo

• blocos sequenceDiagram tornam-se diagramas de sequência mostrando fluxos de mensagens

• definições erDiagram produzem diagramas de entidade-relação

Principais benefícios dos diagramas em texto:

• Texto simples legível por qualquer pessoa

• Diffs amigáveis no Git que mostram exatamente o que mudou

• Revisões de código mais fáceis em pull requests

• Sem ficheiros proprietários de diagramas para gerir

Casos de uso concretos para 2026:

• Documentar um fluxo de autenticação de microserviços com diagramas de sequência

• Mapear pipelines de CI/CD desde o commit até à implantação em produção

• Planejar marcos de lançamento de produtos no Q2 de 2026 com gráficos de Gantt

Os diagramas Mermaid integram-se naturalmente com documentação baseada em Markdown, wikis internas e portais de desenvolvedores, simplificando os processos de documentação em toda a organização.

Principais tipos de diagramas Mermaid

O Mermaid suporta uma ampla variedade de tipos de gráficos. Esta secção fornece uma visão geral prática dos mais úteis em vez de uma referência exaustiva.

Principais tipos de diagramas:

Tipo	Palavra-chave	Ideal para
Fluxogramas	graph TD / flowchart LR	Fluxos de processos, árvores de decisão
Diagramas de sequência	sequenceDiagram	Chamadas de API, interações de serviços
Diagramas de classes	classDiagram	Modelos de objetos, design de domínio
Diagramas de estado	stateDiagram-v2	Estados do ciclo de vida, fluxos de trabalho
Diagramas entidade-relação	erDiagram	Design de esquema de banco de dados
Jornada do utilizador	journey	Mapeamento da experiência do cliente
Gráficos de Gantt	gantt	Cronogramas de projetos, roadmaps
Gráficos circulares	pie	Visualização de dados proporcionais
Gráficos Git	gitGraph	Estratégias de ramificação

Exemplos do mundo real:

• Diagramas de sequência para fluxos Frontend → API Gateway → Payment Service API

• Gráficos de Gantt para o roadmap de recursos do Q2 de 2026 com dependências

• Diagramas de estado para o ciclo de vida do pedido: Pendente → Pago → Enviado → Entregue

Fluxogramas, diagramas de sequência, diagramas ER e diagramas de estado são os mais comuns para equipas de software. Equipas de produto e operações geralmente preferem jornadas do utilizador, Gantt e gráficos circulares para processos de negócios e clientes.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

Como criar diagramas Mermaid

Criar fluxogramas rapidamente começa com a compreensão da estrutura básica. Pode criar diagramas utilizando qualquer editor de texto e a sintaxe Mermaid.

Processo passo a passo:

1. Comece com uma palavra-chave de diagrama (graph TD, sequenceDiagram, gantt)

2. Defina nós ou participantes com IDs e rótulos

3. Conecte elementos com setas ou relações

4. Adicione rótulos e agrupamentos conforme necessário

Eis um fluxograma de processo de login totalmente funcional:

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

Tipos de setas e rótulos:

• –> cria uma seta direcionada padrão

• –>|label| adiciona texto condicional às conexões

• — desenha uma linha sem ponta de seta

• -.-> produz uma seta pontilhada para relações indiretas

O Mermaid posiciona automaticamente os nós usando algoritmos de layout ELK. Concentre-se na estrutura lógica e na nomenclatura em vez do posicionamento manual — não há necessidade de escrever código extra para o posicionamento.

Onde pode usar diagramas Mermaid em 2026

Muitas plataformas populares agora suportam Mermaid nativamente ou através de extensões, facilitando o início imediato.

Principais ambientes:

• GitHub e GitLab: Renderização nativa no README.md, documentação, issues e wikis

• Geradores de sites estáticos: Docusaurus, MkDocs e Sphinx com extensões

• Portais internos de desenvolvedores: Backstage e aplicações React personalizadas

• Ferramentas de notas: Notion e Obsidian com suporte integrado a gráficos Mermaid

O Visual Studio Code e as IDEs JetBrains suportam pré-visualização ao vivo através de extensões, permitindo visualizar os diagramas à medida que digita. Isso ajuda a detetar erros de sintaxe antes de fazer commit das alterações.

Algumas plataformas como o Confluence Cloud exigem add-ons do marketplace. As equipas frequentemente armazenam diagramas externamente em repositórios de código enquanto mantêm as imagens exportadas ao lado para maior visibilidade.

Renderizar diagramas Mermaid em diferentes plataformas

A renderização transforma o texto Mermaid em elementos visuais SVG/HTML. O método depende de como o gráfico Mermaid funciona na sua plataforma de destino.

O padrão geral: coloque o código Mermaid em blocos de código delimitados com o identificador de linguagem mermaid. O GitHub, GitLab e geradores de documentação renderizam automaticamente esses blocos quando visualizados no navegador.

Para desenvolvimento local, extensões ou plugins fornecem pré-visualização ao vivo. Em documentações baseadas em Sphinx, ative a renderização através de extensões como sphinxcontrib-mermaid, que processam diagramas gerados durante a compilação.

Renderizar Mermaid em ficheiros Markdown

Para renderizar Mermaid em Markdown:

1. Use três crases para abrir um bloco de código

2. Especifique mermaid como o identificador de linguagem

3. Adicione a definição do diagrama no interior

4. Feche com três crases

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub, GitLab e sites de documentação modernos suportam este padrão diretamente

• Teste a renderização num ambiente de pré-visualização antes de fazer merge para produção

• O tema padrão do gráfico Mermaid funciona bem para a maioria das documentações

Renderizar Mermaid no Obsidian

O Obsidian renderiza Mermaid a partir de um bloco de código mermaid delimitado na Visualização de Leitura e na Pré-visualização ao Vivo. O suporte ao Mermaid é integrado, pelo que não precisa de um plugin da comunidade para um diagrama básico.

Se um diagrama não for renderizado:

1. Confirme se o bloco de abertura é exatamente ```mermaid.
2. Verifique se a primeira linha tem uma palavra-chave válida, como flowchart LR.
3. Substitua rótulos com pontuação excessiva por rótulos entre aspas, por exemplo A["Review: blocked?"].
4. Reduza o exemplo a dois nós e, em seguida, adicione linhas até encontrar a sintaxe problemática.
5. Verifique se a versão instalada do Obsidian suporta sintaxes Mermaid mais recentes que possa ter copiado.

Para outras extensões de Markdown específicas do Obsidian, consulte o guia de formatação do Obsidian.

Renderizar Mermaid em IDEs e ferramentas locais

O plugin do Visual Studio Code para Mermaid permite a pré-visualização ao vivo lado a lado enquanto edita os diagramas. Várias extensões oferecem realce de sintaxe e sugestões de correção para diagramas complexos.

As IDEs da JetBrains oferecem capacidades semelhantes através de plugins, incluindo frequentemente dicas de erro e opções de exportação. Um botão de reparação de diagramas em algumas ferramentas pode corrigir automaticamente problemas comuns de sintaxis.

Pré-visualizações locais ajudam a identificar erros antes do envio para repositórios Git. Padronize um conjunto recomendado de extensões na sua documentação de desenvolvimento.

Exportar e partilhar diagramas Mermaid

Embora as opções de edição baseadas em código funcionem bem para desenvolvedores, as partes interessadas muitas vezes preferem imagens estáticas para apresentações do Microsoft PowerPoint e relatórios.

Formatos de exportação comuns:

• PNG: Partilha rápida através de ferramentas de mensagem

• SVG: Gráficos escaláveis de alta qualidade para slides

• PDF: Pacotes de documentação imprimíveis

Os fluxos de trabalho de exportação variam de acordo com a ferramenta. Algumas incluem um botão de exportação integrado, enquanto outras exigem o Mermaid Chart Editor ou ferramentas online como o Mermaid Live Editor. Ferramentas de linha de comandos podem gerar imagens em lote a partir de múltiplos ficheiros como parte do CI/CD.

Mantenha sempre a fonte Mermaid original ao lado dos ficheiros exportados para que os diagramas permaneçam editáveis.

Converter diagramas Mermaid para formatos de imagem

Mini fluxo de trabalho usando um editor online:

1. Abra o Mermaid Live Editor no seu navegador

2. Cole o seu código Mermaid ou use diagramas de exemplo como modelos

3. Ajuste as definições de estilo do diagrama Mermaid

4. Configure múltiplos temas se necessário (opções de modo escuro e claro disponíveis)

5. Clique em “Download SVG” ou “Download PNG”

Garantir que os diagramas exportados utilizem fontes e cores consistentes alinhadas com as diretrizes da marca. Capturas de ecrã do GitHub serão rasterizadas e podem não ser escaláveis — utilize exportações SVG para apresentações sempre que possível.

Boas práticas e limitações dos diagramas Mermaid

O Mermaid é poderoso, mas funciona melhor com um escopo e uma estrutura bem pensados para as tarefas de diagramação.

Recomendações:

• Limite cada diagrama a um único conceito focado

• Use rótulos de nós descritivos e padrões de nomenclatura consistentes

• Agrupe passos relacionados com blocos subgráficos (subgraph)

• Mantenha diagramas complexos em ficheiros separados em vez de uma única suíte massiva

Limitações a considerar:

• Sistemas grandes e densos tornam-se difíceis de gerir como código

• O controlo de layout é aproximado — sem posicionamento de píxel perfeito

• O estilo é menos flexível do que em ferramentas de diagramação tradicionais ou quadros brancos

• Não é ideal para maquetes de IU ou diagramação puramente artística

Use o Mermaid para visões gerais de arquitetura e fluxos de trabalho. Mude para ferramentas especializadas quando forem necessários layouts com precisão de píxeis ou topologias de rede complexas. Um editor visual de diagramas ainda pode ser necessário para certos casos de uso.

Começar rapidamente com diagramas Mermaid

Lista de verificação para novos utilizadores:

1. Escolha um tipo de diagrama (geralmente fluxogramas para criar processos simples)

2. Instale uma extensão com suporte a editor visual ou assistente de IA ou abra o Mermaid Live Editor

3. Desenhe um processo real do seu projeto atual — o seu pipeline de implantação de 2026 funciona muito bem

4. Interaja e expanda à medida que aprende padrões de sintaxe de código

Recursos principais:

• Documentação oficial do Mermaid para referência completa de sintaxe

• Mermaid Live Editor para experimentar recursos de geração por IA integrados

• Extensões do VS Code com snippets de código e modelos

• Considere uma conta básica em plataformas de colaboração para recursos de equipa

Adicione uma secção “Diretrizes de diagramas” ao seu manual de engenharia cobrindo convenções de nomenclatura, tipos de diagramas preferidos e permissões. Algumas equipas descobrem que descrições em linguagem natural combinadas com ferramentas de chat de IA aceleram a criação de diagramas para qualquer nível técnico.

A adoção de diagramas Mermaid alinha a sua documentação com as mesmas práticas de revisão e automação usadas para o código-fonte. Seja um engenheiro de machine learning a documentar pipelines de modelos ou um gestor de projetos a mapear fluxos de trabalho, o Mermaid traz visuais controlados por versão para a sua equipa. Comece hoje mesmo com um diagrama.