mermaid markdown diagrams flowchart documentation

Mermaid no Markdown: crie fluxogramas, diagramas de sequência e muito mais

Aprenda a sintaxe Mermaid para Markdown com fluxograma pronto para cópia, sequência, classe, Gantt, mapa mental e exemplos de diagrama ER, além de orientação para visualização, exportação, compatibilidade e acessibilidade.

W
WordToMD Equipa
·

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:

  • TD significa de cima para baixo.
  • LR significa 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.
  • participant declara um sistema ou serviço.
  • actor declara uma função humana ou externa.
  • autonumber rotula 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:

  1. Abre o Visualização de diagrama Mermaid.
  2. Cole apenas a definição do diagrama, sem a cerca externa do código.
  3. Renderize o diagrama.
  4. Leia qualquer erro de sintaxe e corrija a área referenciada.
  5. Copie o cercado Markdown gerado.
  6. Baixe o SVG quando o destino precisar de um ativo estático.
  7. 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:

PlataformaAbordagem documentada atualNota importante
GitHubUse uma cerca mermaid blockGitHub 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 MarkdownGitLab documenta sua versão Mermaid suportada;instalações autogerenciadas podem ser diferentes
ObsidianUse uma cerca mermaid bloco em uma notaO renderizador e os recursos suportados do Obsidian podem mudar entre as versões
Material para MkDocsConfigurar um fence personalizado MermaidA integração do tema nativo requer documentação pymdownx.superfences configuration
Analisador genérico MarkdownGeralmente exibe apenas códigoA 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:

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.