Documentação Markdown com Mermaid
Documentação Markdown com Mermaid: guia prático com demo copiável, checklist de revisão e notas de publicação para Markdown com Mermaid incorporado.

O problema real que isto resolve
Documentação Markdown com Mermaid é útil quando o diagrama não é apenas uma imagem, mas uma parte mantida da documentação. A fonte precisa continuar legível, a prévia deve revelar erros e a exportação precisa funcionar em README, wiki ou blog.
Use este fluxo para README, notas de API, RFCs e artigos de ajuda. A ideia é criar um ciclo curto de edição, prévia e revisão antes de publicar.

Um demo pequeno para colar primeiro
Não comece com todo o conteúdo de produção. Use primeiro um trecho pequeno para validar sintaxe, rótulos e layout.
Quando a primeira prévia funcionar, adicione nomes reais de serviços, campos, atores ou dependências.
# Checkout flow
The API creates an order, then asks the payment service to confirm it.
```mermaid
sequenceDiagram
participant User
participant Store
participant Payment
User->>Store: POST /orders
Store->>Payment: Create payment intent
Payment-->>Store: Confirmed
Store-->>User: Order receipt
```Como revisar a prévia
Revise como se fosse um colega lendo a página. Ela responde uma pergunta clara? A fonte pode ser alterada depois?
Se o conteúdo veio de IA, confira nomes, direção, agrupamento e relações ausentes.
Erros comuns
O erro mais comum é tentar explicar tudo em um único diagrama. Separe fluxo de requisição, dados, infraestrutura e saída de publicação.
Outro erro é exportar apenas uma imagem. Guarde o texto-fonte junto do SVG ou PNG.
Checklist antes de publicar
Antes de publicar, confira nitidez, rótulos longos e se há um trecho reproduzível no artigo.
A página fica melhor quando mostra entrada, prévia e decisão tomada depois da revisão.