Diagramas Mermaid
O VMark suporta diagramas Mermaid para criar fluxogramas, diagramas de sequência e outras visualizações diretamente em seus documentos Markdown.
Inserindo um Diagrama
Usando o Menu ou o Atalho
Escolha Inserir → Diagrama ou pressione Alt + Mod + Shift + D. O VMark insere um bloco de código mermaid com um fluxograma inicial para você editar. Se houver texto selecionado, a seleção passa a ser o código-fonte do diagrama.
Digitando um Bloco de Código
Digite um bloco de código delimitado com o identificador de linguagem mermaid:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Do something]
B -->|No| D[Do another thing]
```Modos de Edição
Modo Texto Rico (WYSIWYG)
No modo WYSIWYG, os diagramas Mermaid são renderizados inline. Dê um duplo clique em um diagrama para editar seu código-fonte; o cabeçalho de edição tem os botões Copiar, Cancelar e Salvar.
Modo Fonte com Prévia ao Vivo
No modo Fonte, um painel de prévia flutuante mostra o diagrama enquanto o cursor está dentro de um bloco de código mermaid. A prévia vem desativada por padrão — ative-a com Visualizar → Alternar pré-visualização de diagrama (Alt + Mod + P) ou pela paleta de comandos. Ela permanece ativa nessa janela até você desativá-la novamente.
| Recurso | Descrição |
|---|---|
| Prévia ao Vivo | Veja o diagrama renderizado enquanto digita (debounce de 200ms) |
| Arrastar para Mover | Arraste o cabeçalho para reposicionar a prévia |
| Redimensionar | Arraste qualquer borda ou canto para redimensionar |
| Zoom | Use os botões − e +, ou Cmd/Ctrl + scroll (10% a 300%) |
O painel de prévia lembra sua posição se você o mover, facilitando a organização do espaço de trabalho.
Tipos de Diagrama Suportados
O VMark suporta todos os tipos de diagrama Mermaid:
Fluxograma
```mermaid
graph LR
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
```Diagrama de Sequência
```mermaid
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
```Diagrama de Classes
```mermaid
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal : +int age
Animal : +swim()
```Diagrama de Estado
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Processing : Start
Processing --> Complete : Done
```Diagrama de Relacionamento de Entidades
```mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
```Gráfico de Gantt
```mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Research :a1, 2024-01-01, 30d
```Gráfico de Pizza
```mermaid
pie title Distribution
"Category A" : 40
"Category B" : 30
```Gráfico Git
```mermaid
gitGraph
commit
branch develop
commit
checkout main
merge develop
```Dicas
Erros de Sintaxe
Se seu diagrama tiver um erro de sintaxe:
- No modo WYSIWYG: o bloco de código mostra o código-fonte bruto
- No modo Fonte: a prévia mostra "Sintaxe mermaid inválida"
Consulte a documentação do Mermaid para a sintaxe correta.
Pan e Zoom
No modo WYSIWYG, diagramas renderizados suportam navegação interativa:
| Ação | Como |
|---|---|
| Pan | Clique e arraste o diagrama (uma rolagem simples rola o documento, não o diagrama) |
| Zoom | Segure Cmd (macOS) ou Ctrl (Windows/Linux) e role |
| Resetar | Clique no botão de reset que aparece ao passar o mouse (canto superior direito) |
Copiar Código-Fonte Mermaid
Ao editar um bloco de código mermaid no modo WYSIWYG, um botão de cópia aparece no cabeçalho de edição. Clique nele para copiar o código-fonte mermaid para a área de transferência.
Integração de Tema
Os diagramas Mermaid se adaptam automaticamente ao tema atual do VMark (White, Paper, Mint, Sepia ou Night).
Exportar como PNG
Passe o mouse sobre um diagrama mermaid renderizado no modo WYSIWYG para revelar um botão de exportação (canto superior direito, à esquerda do botão de reset). Clique nele para escolher um tema:
| Tema | Fundo |
|---|---|
| Claro | Fundo branco |
| Escuro | Fundo escuro |
O diagrama é exportado como um PNG de resolução 2x via diálogo de salvamento do sistema. A imagem exportada usa uma pilha de fontes de sistema concretas, para que o texto seja renderizado corretamente independentemente das fontes instaladas na máquina do visualizador.
Exportar como HTML/PDF
Ao exportar o documento completo para HTML ou PDF, os diagramas Mermaid são renderizados como imagens SVG para exibição nítida em qualquer resolução.
Corrigindo Diagramas Gerados por IA
O VMark usa Mermaid v12, que mantém o parser mais estrito (Langium) introduzido na v11. Ferramentas de IA (ChatGPT, Claude, Copilot, etc.) frequentemente geram sintaxe que funcionava em versões mais antigas do Mermaid, mas falha na v11 e posteriores. Aqui estão os problemas mais comuns e como corrigi-los.
1. Rótulos sem Aspas com Caracteres Especiais
O problema mais frequente. Se um rótulo de nó contiver parênteses, apóstrofos, dois-pontos ou aspas, ele deve ser encapsulado em aspas duplas.
<!-- Falha -->
```mermaid
flowchart TD
A[User's Dashboard] --> B[Step (optional)]
C[Status: Active] --> D[Say "Hello"]
```
<!-- Funciona -->
```mermaid
flowchart TD
A["User's Dashboard"] --> B["Step (optional)"]
C["Status: Active"] --> D["Say Hello"]
```Regra: Se um rótulo contiver qualquer um destes caracteres — ' ( ) : " ; # & — encapsule o rótulo inteiro em aspas duplas: ["assim"].
2. Ponto e Vírgula no Final
Modelos de IA às vezes adicionam ponto e vírgula no final das linhas. O Mermaid v11 e posteriores não os permitem.
<!-- Falha -->
```mermaid
flowchart TD
A --> B;
B --> C;
```
<!-- Funciona -->
```mermaid
flowchart TD
A --> B
B --> C
```3. Usando graph em Vez de flowchart
A palavra-chave graph é sintaxe legada. Alguns recursos mais novos só funcionam com flowchart. Prefira flowchart para todos os novos diagramas.
<!-- Pode falhar com sintaxe mais nova -->
```mermaid
graph TD
A --> B
```
<!-- Preferido -->
```mermaid
flowchart TD
A --> B
```4. Títulos de Subgráficos com Caracteres Especiais
Os títulos de subgráficos seguem as mesmas regras de citação que os rótulos de nós.
<!-- Falha -->
```mermaid
flowchart TD
subgraph Service Layer (Backend)
A --> B
end
```
<!-- Funciona -->
```mermaid
flowchart TD
subgraph "Service Layer (Backend)"
A --> B
end
```5. Lista de Verificação de Correção Rápida
Quando um diagrama gerado por IA mostrar "Sintaxe inválida":
- Coloque aspas em todos os rótulos que contenham caracteres especiais:
["Rótulo (com parênteses)"] - Remova ponto e vírgula no final de cada linha
- Substitua
graphporflowchartse usar recursos de sintaxe mais nova - Coloque aspas nos títulos de subgráficos que contêm caracteres especiais
- Teste no Mermaid Live Editor para identificar o erro exato
TIP
Ao pedir que uma IA gere diagramas Mermaid, adicione isso ao seu prompt: "Use sintaxe Mermaid v11. Sempre encapsule os rótulos de nós em aspas duplas se contiverem caracteres especiais. Não use ponto e vírgula no final."
Ensine Sua IA a Escrever Mermaid Válido
Em vez de corrigir diagramas manualmente toda vez, você pode instalar ferramentas que ensinam seu assistente de codificação IA a gerar sintaxe Mermaid v11 correta desde o início.
Skill Mermaid (Referência de Sintaxe)
Uma skill dá à sua IA acesso à documentação de sintaxe Mermaid atualizada para todos os 23 tipos de diagrama, para que ela gere código correto em vez de adivinhar.
Fonte: WH-2099/mermaid-skill
Claude Code
# Clonar a skill
git clone https://github.com/WH-2099/mermaid-skill.git /tmp/mermaid-skill
# Instalar globalmente (disponível em todos os projetos)
mkdir -p ~/.claude/skills/mermaid
cp -r /tmp/mermaid-skill/.claude/skills/mermaid/* ~/.claude/skills/mermaid/
# Ou instalar apenas por projeto
mkdir -p .claude/skills/mermaid
cp -r /tmp/mermaid-skill/.claude/skills/mermaid/* .claude/skills/mermaid/Após a instalação, use /mermaid <descrição> no Claude Code para gerar diagramas com sintaxe correta.
Codex (OpenAI)
# Mesmos arquivos, local diferente
mkdir -p ~/.codex/skills/mermaid
cp -r /tmp/mermaid-skill/.claude/skills/mermaid/* ~/.codex/skills/mermaid/Gemini CLI (Google)
O Gemini CLI lê skills de ~/.gemini/ ou por projeto .gemini/. Copie os arquivos de referência e adicione uma instrução ao seu GEMINI.md:
mkdir -p ~/.gemini/skills/mermaid
cp -r /tmp/mermaid-skill/.claude/skills/mermaid/references ~/.gemini/skills/mermaid/Em seguida, adicione ao seu GEMINI.md (global ~/.gemini/GEMINI.md ou por projeto):
## Mermaid Diagrams
When generating Mermaid diagrams, read the syntax reference in
~/.gemini/skills/mermaid/references/ for the diagram type you are
generating. Use Mermaid v11 syntax: always quote node labels containing
special characters, do not use trailing semicolons, prefer "flowchart"
over "graph".Servidor MCP Mermaid Validator (Verificação de Sintaxe)
Um servidor MCP permite que sua IA valide diagramas antes de apresentá-los a você. Ele detecta erros usando os mesmos parsers (Jison + Langium) que o Mermaid v11 usa internamente.
Fonte: fast-mermaid-validator-mcp
Claude Code
# Um comando — instala globalmente
claude mcp add -s user --transport stdio mermaid-validator \
-- npx -y @ai-of-mine/fast-mermaid-validator-mcp --mcp-stdioIsso registra um servidor MCP mermaid-validator que fornece três ferramentas:
| Ferramenta | Objetivo |
|---|---|
validate_mermaid | Verificar a sintaxe de um único diagrama |
validate_file | Validar diagramas dentro de arquivos Markdown |
get_examples | Obter diagramas de exemplo para todos os 28 tipos suportados |
Codex (OpenAI)
codex mcp add --transport stdio mermaid-validator \
-- npx -y @ai-of-mine/fast-mermaid-validator-mcp --mcp-stdioClaude Desktop
Adicione ao seu claude_desktop_config.json (Configurações > Desenvolvedor > Editar Config):
{
"mcpServers": {
"mermaid-validator": {
"command": "npx",
"args": ["-y", "@ai-of-mine/fast-mermaid-validator-mcp", "--mcp-stdio"]
}
}
}Gemini CLI (Google)
Adicione ao seu ~/.gemini/settings.json (ou por projeto .gemini/settings.json):
{
"mcpServers": {
"mermaid-validator": {
"command": "npx",
"args": ["-y", "@ai-of-mine/fast-mermaid-validator-mcp", "--mcp-stdio"]
}
}
}Pré-requisitos
Ambas as ferramentas requerem Node.js (v18 ou posterior) instalado na sua máquina. O servidor MCP é baixado automaticamente via npx no primeiro uso.
Aprendendo a Sintaxe Mermaid
O VMark renderiza a sintaxe Mermaid padrão. Para dominar a criação de diagramas, consulte a documentação oficial do Mermaid:
Documentação Oficial
| Tipo de Diagrama | Link da Documentação |
|---|---|
| Fluxograma | Sintaxe de Fluxograma |
| Diagrama de Sequência | Sintaxe de Diagrama de Sequência |
| Diagrama de Classes | Sintaxe de Diagrama de Classes |
| Diagrama de Estado | Sintaxe de Diagrama de Estado |
| Relacionamento de Entidades | Sintaxe de Diagrama ER |
| Gráfico de Gantt | Sintaxe de Gantt |
| Gráfico de Pizza | Sintaxe de Gráfico de Pizza |
| Gráfico Git | Sintaxe de Gráfico Git |
Ferramentas de Prática
- Mermaid Live Editor — Playground interativo para testar e visualizar diagramas antes de colá-los no VMark
- Documentação Mermaid — Referência completa com exemplos para todos os tipos de diagrama
TIP
O Live Editor é ótimo para experimentar com diagramas complexos. Uma vez que seu diagrama esteja correto, copie o código para o VMark.