Diagramas técnicos muitas vezes ficam obsoletos porque editá-los requer encontrar o arquivo de design original, abrir um aplicativo separado e exportar outra imagem.Mermaid adota uma abordagem diferente: o diagrama é definido como texto e armazenado ao lado da documentação.
Para adicionar Mermaid a Markdown, coloque a definição do diagrama dentro de um bloco de código protegido com o mermaid identificador de idioma.Use o Visualização de diagrama Mermaid para renderizar a sintaxe localmente, corrigir erros, copiar o fence Markdown completo ou baixar um SVG.
Este guia começa com um pequeno fluxograma e se baseia em diagramas de sequência, classe, Gantt, mapa mental e entidade-relacionamento.
Mermaid em 30 segundos
Um bloco Mermaid básico se parece com isto:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
A cerca de abertura informa a um renderizador compatível que o conteúdo tem sintaxe Mermaid. flowchart LR seleciona um fluxograma organizado da esquerda para a direita.As linhas restantes definem nós e conexões.
Se o destino não suportar Mermaid, os leitores normalmente verão um bloco de código em vez de um diagrama.Esse substituto preserva a fonte, mas não substitui a verificação de compatibilidade antes da publicação.
Por que usar diagramas baseados em texto?
Mermaid é especialmente útil quando um diagrama:
- pertence à documentação com controle de versão;
- muda junto com código ou procedimentos;
- precisa de diferenças significativas de pull-request;
- usa formas e relacionamentos padrão;
- deve ser editável sem um arquivo de design proprietário;
- deve ser regenerado em temas claros e escuros.
É menos adequado para ilustrações detalhadas, layout com pixels perfeitos, anotações à mão livre ou design visual que exija posicionamento manual preciso.Nesses casos, use uma ferramenta de desenho e exporte um SVG ou imagem acessível.
Exemplo 1: Um fluxograma
Os fluxogramas descrevem um processo, decisão ou regra de roteamento.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Sintaxe da chave:
TDsignifica de cima para baixo.LRsignifica da esquerda para a direita.[Text]cria um nó de processo retangular.{Text}cria um nó de decisão.-->cria uma conexão direcional.-->|Label|adiciona texto a uma conexão.
Use IDs de nó curtos e estáveis, como A or validate.Mantenha a etiqueta visível entre colchetes para que a alteração do texto não exija a alteração de todas as conexões.
Adicionar um subgráfico
Etapas relacionadas ao grupo de subgráficos:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Use subgráficos quando o agrupamento comunicar propriedade, limites do sistema ou fases.Não adicione uma caixa apenas para decoração.
Exemplo 2: Um Diagrama de Sequência
Os diagramas de sequência mostram as interações em ordem de tempo.Eles funcionam bem para chamadas API, autenticação, fluxos de trabalho de navegador e sistemas orientados a eventos.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Setas comuns:
->>envia uma mensagem sólida.-->>envia uma resposta tracejada.participantdeclara um sistema ou serviço.actordeclara uma função humana ou externa.autonumberrotula as interações em ordem.
Concentre-se em um cenário.Um diagrama de sequência que tenta mostrar todas as alternativas e todas as funções internas torna-se mais difícil de entender do que o código.
Mostrar um caminho alternativo
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Utilização alt, elsee end para ramificações significativas.Se o ramo exigir várias páginas de explicação, link para a prosa abaixo do diagrama.
Exemplo 3: Um Diagrama de Classes
Diagramas de classes descrevem tipos, propriedades, operações, herança e relacionamentos.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
Este exemplo afirma que MarkdownDocument herda de Document.Use diagramas de classes para um modelo conceitual, não como uma substituição automática da documentação de referência completa API.
Bons diagramas de classes omitem detalhes que não ajudam o leitor a compreender o projeto.Mostrar todos os campos privados pode transformar o diagrama em uma versão menos pesquisável do código-fonte.
Exemplo 4: Um gráfico de Gantt
Os gráficos de Gantt mostram as tarefas ao longo do tempo.Eles são úteis para planos de lançamento, migrações e projetos de documentação.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Mantenha as datas explícitas e use IDs de tarefas quando uma tarefa depender de outra.Lembre-se de que um diagrama armazenado na documentação não será atualizado quando o cronograma real do projeto for alterado.Atribua propriedade para mantê-lo atualizado.
Exemplo 5: Um mapa mental
Os mapas mentais organizam ideias em torno de um tópico central.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Os mapas mentais são mais eficazes durante o planejamento ou como uma visão geral de alto nível.Eles são menos úteis para relacionamentos precisos porque a estrutura em árvore pode implicar hierarquia onde os conceitos reais se sobrepõem.
Exemplo 6: Um Diagrama Entidade-Relacionamento
Diagramas ER descrevem entidades de dados e seus relacionamentos.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Use um diagrama ER para explicar o modelo e um esquema ou arquivo de migração para definir a implementação.Um diagrama pode omitir índices, restrições e campos que não são relevantes para a explicação atual.
Visualização Mermaid Antes da publicação
Escrever diagramas diretamente em um documento Markdown longo torna difícil isolar erros de sintaxe.Um loop de visualização focado é mais rápido:
- Abre o Visualização de diagrama Mermaid.
- Cole apenas a definição do diagrama, sem a cerca externa do código.
- Renderize o diagrama.
- Leia qualquer erro de sintaxe e corrija a área referenciada.
- Copie o cercado Markdown gerado.
- Baixe o SVG quando o destino precisar de um ativo estático.
- Teste o Markdown final em sua plataforma real.
A visualização é renderizada em seu navegador com uma configuração de segurança rigorosa.Os retornos de chamada do diagrama e outros comportamentos interativos podem ser desativados mesmo que outra instalação do Mermaid os permita.Esse comportamento conservador é apropriado para uma ferramenta de visualização geral.
Erros comuns Mermaid
O tipo de diagrama está faltando
Incorrecto:
A --> B
Correcto:
flowchart LR
A --> B
A primeira linha identifica a gramática do diagrama.
A pontuação em um rótulo interrompe a análise
Cite rótulos complexos:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Isto é particularmente útil para parênteses, pontuação e rótulos que se assemelham à sintaxe.
Um Word reservado é usado inesperadamente
Mermaid gramáticas possuem palavras-chave.A documentação oficial do fluxograma alerta especificamente que letras minúsculas end pode quebrar um fluxograma.Coloque-o em maiúscula ou coloque o texto visível dentro de um rótulo de nó entre aspas:
flowchart LR
Start --> Finish["End"]
O limite de código está incorreto
O identificador do idioma pertence imediatamente após os crases de abertura:
```mermaid
flowchart LR
A --> B
```
Não recue a cerca completa, a menos que a sintaxe Markdown circundante assim o exija.
Funciona em uma plataforma, mas não em outra
Mermaid evolui e as plataformas podem usar diferentes renderizadores, versões, configurações de segurança e tipos de diagramas habilitados.Um recurso de sintaxe suportado pela versão mais recente Mermaid pode falhar em uma plataforma que usa outra implementação ou versão mais antiga.
Prefira sintaxe amplamente suportada para documentos que se movem entre plataformas.Teste formas avançadas, temas, diretivas e tipos de diagramas mais recentes em todos os destinos necessários.
Compatibilidade de plataforma
A compatibilidade deve ser testada em vez de presumida:
| Plataforma | Abordagem documentada atual | Nota importante |
|---|---|---|
| GitHub | Use uma cerca mermaid block | GitHub documentos renderizados em Markdown arquivos, problemas, discussões, pull requests e wikis |
| GitLab (em inglês) | Use um bloco de código Mermaid no GitLab Flavored Markdown | GitLab documenta sua versão Mermaid suportada;instalações autogerenciadas podem ser diferentes |
| Obsidian | Use uma cerca mermaid bloco em uma nota | O renderizador e os recursos suportados do Obsidian podem mudar entre as versões |
| Material para MkDocs | Configurar um fence personalizado Mermaid | A integração do tema nativo requer documentação pymdownx.superfences configuration |
| Analisador genérico Markdown | Geralmente exibe apenas código | A renderização Mermaid geralmente requer uma integração JavaScript ou um plugin de construção |
Verifique a documentação oficial atual antes de confiar em um recurso mais recente:
- GitHub: Criação de diagramas
- GitLab com sabor Markdown
- Obsidian: Sintaxe de formatação avançada
- Material para MkDocs: Diagramas
- Mermaid referência de sintaxe
Para um site de documentação que você controla, fixe a versão de dependência Mermaid e teste as atualizações.Caso contrário, uma pequena alteração na sintaxe poderá alterar os diagramas em todo o site.
Mermaid e Acessibilidade
Um SVG renderizado não comunica automaticamente seu significado a todos os leitores.Trate o diagrama como um resumo visual e forneça uma explicação equivalente em prosa próxima.
Para o fluxograma de conversão anterior, adicione texto como:
O usuário seleciona um arquivo DOCX.Os arquivos válidos são convertidos localmente e exibidos para revisão;arquivos inválidos produzem um erro.O usuário pode então copiar ou baixar o Markdown revisado.
Práticas de acessibilidade:
- apresente o que o diagrama explica;
- resume a conclusão após diagramas complexos;
- não codifica o significado apenas com a cor;
- use rótulos legíveis em vez de abreviações internas;
- mantém contraste suficiente em temas claros e escuros;
- evite diagramas que exijam interação precisa do mouse;
- fornecer uma alternativa em texto ou tabela para informações essenciais;
- exporte SVG com cuidado quando o arquivo estático precisar ter um nome acessível.
O código-fonte é útil para os autores, mas não é necessariamente uma boa alternativa de texto para os leitores.
Projetando diagramas que permaneçam legíveis
Mantenha um propósito por diagrama
Um diagrama deve responder a uma pergunta como “O que acontece após uma solicitação com falha?”ou “Qual serviço possui cada armazenamento de dados?”Se tentar explicar todo o sistema, divida-o.
Prefira rótulos curtos
Coloque explicações detalhadas em prosa.Etiquetas longas forçam nós estreitos, quebra de linha desajeitada e diagramas grandes em telas móveis.
Use a direção intencionalmente
O fluxo da esquerda para a direita funciona bem para processos curtos e caminhos de solicitação.O fluxo de cima para baixo geralmente se adapta melhor a telas estreitas.Visualize ambos antes de confirmar.
Limitar o estilo visual
As cores personalizadas podem entrar em conflito com o modo escuro ou temas de plataforma.Comece com os padrões do renderizador.Adicione estilos somente quando eles comunicarem significado e permanecerem legíveis em todos os temas necessários.
Mantenha a fonte perto de sua explicação
Armazene o bloco Mermaid no mesmo arquivo Markdown quando possível.Isso faz com que a prosa e o diagrama mudem juntos em uma revisão.
Mermaid vs uma imagem estática
Escolha Mermaid quando:
- o diagrama muda frequentemente;
- diferenças de origem são valiosas;
- o layout usa tipos de diagramas padrão;
- a plataforma de publicação renderiza Mermaid de forma confiável.
Escolha SVG ou PNG quando:
- o projeto requer layout manual preciso;
- o destino não renderiza Mermaid;
- a aparência exata deve permanecer fixa;
- o compartilhamento externo requer um ativo independente.
Um híbrido útil é manter a fonte Mermaid e exportar um SVG para destinos que não podem renderizá-lo.Mantenha a fonte ao lado do ativo exportado e documente como regenerá-lo.
Utilização Markdown para imagem para conteúdo Markdown renderizado compartilhável ou baixe SVG diretamente do Visualização de diagrama Mermaid quando o próprio diagrama é o ativo.
FAQ
Mermaid faz parte da norma Markdown?
Não. Uma cerca mermaid é uma extensão reconhecida por aplicativos e sistemas de construção compatíveis.Um analisador Markdown básico pode renderizá-lo como código comum.
GitHub renderiza diagramas Mermaid?
Sim.A documentação do GitHub descreve a renderização do Mermaid em arquivos Markdown e diversas superfícies de colaboração.Teste a sintaxe mais recente porque GitHub controla o renderizador implantado e as configurações de segurança.
Posso usar Mermaid em Obsidian?
Documentos de ajuda oficiais de Obsidian Blocos de diagramas cercados estilo Mermaid em notas.O suporte a recursos pode mudar com o renderizador do aplicativo, portanto, verifique os tipos de diagramas complexos ou recentemente introduzidos na sua versão instalada.
O Mermaid pode substituir a documentação de arquitetura?
Não. Um diagrama é uma visão de um sistema.Combine-o com decisões, propriedade, restrições, comportamento de falha e links para interfaces ou esquemas autorizados.
Por que meu diagrama é renderizado de forma diferente no modo escuro?
As plataformas podem aplicar diferentes temas Mermaid, variáveis CSS, fontes e planos de fundo.Evite cores codificadas até testar ambos os temas.
Devo enviar arquivos SVG exportados?
Confirme um SVG quando o destino da publicação precisar de um ativo estático ou o resultado renderizado precisar permanecer estável.Mantenha também a fonte Mermaid e um processo de regeneração documentado para evitar desvios entre as duas versões.
Mermaid é seguro para diagramas confidenciais?
A confidencialidade depende do editor e do fluxo de trabalho da publicação.A visualização do WordToMD renderiza o diagrama em seu navegador, mas a publicação do Markdown ou SVG em um repositório ou site segue os controles de acesso desse destino.
Conclusão
Mermaid torna os diagramas fáceis de manter porque a fonte convive com o Markdown.Comece com um pequeno bloco cercado, escolha o tipo de diagrama que corresponde à pergunta, visualize a sintaxe e teste-a no renderizador final.Use prosa para explicar o significado essencial e exporte SVG quando um destino precisar de um ativo estático.
Experimente os exemplos no Visualização de diagrama Mermaid, edite a documentação envolvente no Markdown Editore mantenha o diagrama focado o suficiente para que um futuro colaborador possa entendê-lo e atualizá-lo sem redesenhar a página inteira.