Diagramas Mermaid em Markdown: exporte para PDF

Um diagrama costuma explicar um processo melhor do que três parágrafos, mas desenhá-lo em um programa gráfico significa exportar uma imagem, colá-la e refazê-la toda vez que algo muda. Com o Mermaid, você descreve o diagrama em poucas linhas de texto dentro do seu Markdown e o editor o desenha. Este guia traz exemplos prontos para copiar dos tipos de diagrama mais úteis e explica o que acontece com eles quando você exporta um PDF.

Por que desenhar diagramas com texto

O Mermaid é uma biblioteca de código aberto que transforma uma descrição curta em texto em um diagrama. Isso tem vantagens práticas:

• Alterações levam segundos. Renomear uma etapa ou adicionar um caminho é mudar uma linha, e o layout é recalculado sozinho.
• O diagrama fica dentro do documento, então não há um arquivo de imagem para manter atualizado, e as mudanças são fáceis de revisar no controle de versão.
• Funciona em vários lugares. GitHub, GitLab e Obsidian exibem os mesmos blocos, então uma única fonte serve para um README, para suas notas e para um PDF.

Em troca, você abre mão de parte do controle: o Mermaid decide onde cada caixa fica. Para documentação e anotações, costuma valer a pena.

Seu primeiro diagrama

No editor de Markdown para PDF, um diagrama é um bloco de código delimitado cuja linguagem é mermaid. A primeira linha indica o tipo de diagrama e o resto o descreve:

```mermaid
flowchart LR
  A[Markdown] --> B[Pré-visualização] --> C[PDF]
```

A pré-visualização redesenha o diagrama enquanto você digita. O primeiro diagrama de um documento pode levar um instante para aparecer, porque o editor só carrega a biblioteca Mermaid quando ela é necessária. Escreva mermaid em minúsculas: um bloco marcado como Mermaid aparece como código comum.

Exemplos para copiar

Todos funcionam do jeito que estão. Cole um e troque os rótulos pelos seus.

Fluxograma: processos e decisões

```mermaid
flowchart TD
  A[Solicitação recebida] --> B{Aprovada?}
  B -->|Sim| C[Pedir as peças]
  B -->|Não| D[Responder com os motivos]
  C --> E[Agendar o serviço]
```

TD significa de cima para baixo e LR, da esquerda para a direita. Colchetes desenham uma caixa, chaves um losango de decisão, e |texto| coloca um rótulo em uma seta.

Diagrama de sequência: quem fala com quem

```mermaid
sequenceDiagram
  participant C as Cliente
  participant L as Loja
  participant G as Gateway de pagamento
  C->>L: Faz o pedido
  L->>G: Cobra o cartão
  G-->>L: Pagamento confirmado
  L-->>C: Confirmação do pedido
  Note over L,G: Até 3 novas tentativas
```

Setas contínuas (->>) costumam indicar pedidos e as tracejadas (-->>), respostas. Toda mensagem precisa de dois-pontos antes do texto.

Gráfico de Gantt: um plano de projeto

```mermaid
---
config:
  gantt:
    useWidth: 640
---
gantt
  title Relançamento do site
  dateFormat YYYY-MM-DD
  section Design
  Wireframes     :a1, 2026-11-02, 10d
  Design visual  :a2, after a1, 8d
  section Desenvolvimento
  Implementação  :b1, after a2, 15d
  Testes         :b2, after b1, 5d
```

Cada tarefa tem um identificador, um início (uma data ou after seguido de outra tarefa) e uma duração. O cabeçalho config entre as linhas --- fixa a largura do gráfico, por motivos explicados mais abaixo.

Linha do tempo: marcos

```mermaid
timeline
  title Histórico do projeto
  2023 : Ideia e primeiro protótipo
  2024 : Beta com 20 clientes
       : Primeiro plano pago
  2025 : Versão 2.0
```

Diagrama entidade-relacionamento: modelos de dados

```mermaid
erDiagram
  CLIENTE ||--o{ PEDIDO : faz
  PEDIDO ||--|{ ITEM_PEDIDO : "contém"
  PRODUTO ||--o{ ITEM_PEDIDO : "aparece em"
  CLIENTE {
    int id
    string nome
    string email
  }
```

|| significa exatamente um, o{ zero ou mais e |{ um ou mais. Para modelagem orientada a objetos, classDiagram funciona de forma parecida.

Gráfico de pizza e mapa mental

```mermaid
pie title Tempo por fase
  "Pesquisa" : 20
  "Design" : 30
  "Desenvolvimento" : 40
  "Testes" : 10
```

```mermaid
mindmap
  root((Viagem a Lisboa))
    Transporte
      Voos
      Transfer do aeroporto
    Hospedagem
      Hotel
      Bairro
    Orçamento
```

Os valores do gráfico de pizza não precisam somar 100. Em um mapa mental, a hierarquia é definida só pela indentação, então mantenha-a uniforme.

O Mermaid também desenha diagramas de estados, jornadas do usuário, grafos do Git, gráficos XY e quadros Kanban. O editor usa o Mermaid 12, e a documentação oficial (em inglês) explica todos os tipos.

Como os diagramas ficam no papel

Tamanho e largura da página

As páginas são impressas em retrato, e a coluna de texto tem cerca de 17 cm de largura em A4 com margens normais. Um diagrama que cabe é impresso no tamanho natural, centralizado e nunca ampliado. Um mais largo é reduzido até a largura da coluna, e o texto encolhe junto:

• Um fluxograma da esquerda para a direita com mais de três ou quatro caixas em linha já fica largo demais. Trocar LR por TD costuma ser a melhor solução.
• Cada participante de um diagrama de sequência acrescenta cerca de 5 cm; com cinco ou seis, os rótulos ficam pequenos.
• Linhas do tempo crescem para os lados a cada período, então use textos curtos nos eventos.

A opção Tamanho da fonte do painel Estilo não afeta os rótulos dos diagramas; eles só diminuem quando o diagrama é reduzido. Por outro lado, a maioria dos tipos usa a fonte do texto do seu tema, então eles combinam com o resto do documento.

Gráficos de Gantt precisam de largura fixa

O Mermaid dá aos gráficos de Gantt a largura da janela do navegador, não a da página. Em uma tela larga, o gráfico sai muito largo e depois é reduzido para caber, com texto pequeno demais para ler. A opção useWidth do exemplo acima fixa a largura; 640 corresponde à coluna em A4 ou Carta com margens normais.

Quebras de página com diagramas grandes

O editor tenta manter cada diagrama em uma única página. Se um diagrama não cabe no espaço que sobra, ele passa para a página seguinte, o que pode deixar um vazio e separá-lo do título. Dois hábitos ajudam:

• Coloque <!-- pagebreak --> sozinho em uma linha antes do título de uma seção com um diagrama grande, para que os dois comecem juntos a página seguinte.
• Mantenha cada diagrama menor que uma página. Um mais alto não consegue ficar inteiro: o navegador o corta onde a página termina, às vezes no meio de uma caixa. É melhor dividi-lo, por exemplo em um diagrama por fase.

Cores, temas e modo escuro

Os diagramas usam o tema neutral do Mermaid: caixas cinza-claro, texto escuro e linhas cinza, que imprimem bem até em preto e branco. Eles não seguem as cores escolhidas no painel Estilo, e o modo escuro não os afeta: a página da pré-visualização é sempre branca e o PDF é sempre impresso em cores claras. Para mudar o estilo de um único diagrama, adicione um cabeçalho de configuração ao bloco:

```mermaid
---
config:
  theme: forest
---
flowchart LR
  A[Rascunho] --> B[Revisão] --> C[Publicação]
```

default, forest e base acrescentam cor, e neutral volta ao visual padrão. Evite dark para impressão: as caixas pretas e setas claras foram pensadas para fundo escuro e, no papel, gastam muita tinta.

Vetor ou imagem?

Com Baixar PDF e Salvar como PDF na janela de impressão, os diagramas continuam sendo gráficos vetoriais: as linhas ficam nítidas em qualquer zoom e os rótulos são texto de verdade, que você pode selecionar e pesquisar. (No Chrome, caixas com sombra suave são incorporadas como imagens de alta resolução, o que você não vai perceber no papel.) Já Mais → PDF rápido (imagem) transforma cada página em uma imagem: nada pode ser selecionado, o resultado fica menos nítido e os rótulos dos diagramas podem cair em uma fonte genérica. Mais → Baixar .html também mantém os diagramas como gráficos vetoriais.

Quando um diagrama não aparece

Se o Mermaid não consegue ler um bloco, o diagrama é substituído por um texto vermelho que começa com Mermaid:. Erros de sintaxe mostram o número da linha dentro do diagrama e uma marca onde a leitura parou; o resto do documento continua sendo exibido. Corrija antes de exportar, porque o PDF contém exatamente o que a pré-visualização mostra. As causas mais comuns:

• “No diagram type detected”: a primeira linha está faltando ou com erro de digitação (flowchar, sequencediagram). As palavras-chave diferenciam maiúsculas de minúsculas.
• Parênteses ou colchetes dentro de um rótulo, como em A[Enviar fatura (PDF)], geram um erro que termina em got 'PS'. Coloque o rótulo entre aspas: A["Enviar fatura (PDF)"].
• Um nó chamado end quebra fluxogramas, porque end é uma palavra-chave. Escreva End ou use-a só como rótulo: Fim[end].
• Uma mensagem de sequência sem dois-pontos (Ana->>Bruno Olá) gera Expecting 'TXT', got 'NEWLINE'.
• “Invalid date” em um gráfico de Gantt: uma data não existe ou não segue a linha dateFormat.
• Aspas tipográficas (“ ”) coladas de um processador de texto não contam como aspas. Use aspas retas no código do diagrama.

Ainda sem solução? Apague linhas a partir do fim do bloco até o diagrama reaparecer; a última linha removida é a culpada.

Dicas para diagramas legíveis no papel

• Rótulos curtos. De duas a cinco palavras por caixa. As caixas dos fluxogramas quebram textos longos sozinhas; para escolher onde a linha quebra, use <br>: A["Primeira linha<br>segunda linha"].
• Menos de 15 caixas. Divida um processo grande em uma visão geral e um ou dois diagramas de detalhe.
• Apresente cada diagrama com uma frase dizendo o que observar.
• Deixe os rótulos carregarem o significado, não só a cor: o PDF pode ser impresso em preto e branco.
• Use %% para comentários. Essas linhas ficam no código, mas não são desenhadas.
• Confira a pré-visualização com o tema final. O Mermaid mede os rótulos antes de aplicar a fonte do documento, então, com as fontes serifadas e mais largas de Classic e Editorial, um rótulo curto de seta pode perder a última letra. Se isso acontecer, mude para um tema sem serifa, como Modern ou Clean.

Tudo, diagramas incluídos, é gerado no seu navegador; nada é enviado. Para o resto da sintaxe, consulte o guia de Markdown. Se os seus diagramas estão no Obsidian, o guia para exportar notas do Obsidian e do Notion para PDF mostra o resto da sintaxe que vale ajustar.