Gráfico de Gantt em Mermaid: sintaxe, armadilhas e ida e volta para um editor de verdade

A sintaxe de uma só passada

Um bloco gantt abre com a palavra gantt e algumas linhas de cabeçalho; depois vêm os títulos de section com as linhas de tarefa embaixo. A indentação é convenção, não gramática — o Mermaid não se importa, mas quem lê o diff se importa muito.

Uma linha de tarefa é um nome, dois-pontos e então campos separados por vírgula:

Nome da tarefa :tag, id, início, duração

• Tags — qualquer uma entre done, active, crit e milestone, em qualquer ordem, e dá para empilhar mais de uma. Opcionais.
• id — uma palavra simples, sem espaço nem pontuação, necessária apenas se algo mais precisar se referir a esta tarefa.
• início — uma data, ou after algumId, ou omitido para continuar a partir da tarefa de cima.
• duração — 5d, 2w, ou uma segunda data absoluta.

Linhas de cabeçalho que vale conhecer: dateFormat (como as datas do seu arquivo estão escritas), excludes weekends, title e axisFormat (como o eixo é rotulado, em códigos no estilo strftime). Os campos são classificados pelo formato, e não estritamente pela posição — é por isso que :done, aud, 2026-03-02, 5d e :aud, done, 2026-03-02, 5d funcionam igualmente bem.

Um exemplo completo para colar num README

Um bloco válido e inteiro, para trabalho de verdade: a migração de um gateway de cobrança para o Pix Automático. Ele usa seções, datas absolutas, correntes de after, todas as tags, um marco e fins de semana excluídos. Cole num bloco cercado mermaid em qualquer arquivo Markdown do GitHub e ele renderiza.

gantt
    title Migração para o Pix Automático
    dateFormat YYYY-MM-DD
    axisFormat %d/%m
    excludes weekends

    section Descoberta
    Auditoria dos fluxos atuais :done, aud, 2026-03-02, 5d
    Especificação OpenAPI       :done, esp, after aud, 4d
    Revisão da especificação    :active, rev, after esp, 2d

    section Construção
    Serviço de autenticação     :crit, auth, after rev, 10d
    Endpoints de cobrança       :cob, after auth, 12d
    Regerar o SDK do cliente    :sdk, after cob, 3d

    section Virada
    Homologação com o PSP       :hom, after sdk, 5d
    Beta público                :milestone, beta, 2026-05-04, 0d
    Descontinuar a v1           :desc, after beta, 2w

Referência da linha de tarefa

Cada campo e modificador, o que ele faz e como aparece na prática.

Quatro coisas que vão te pegar

1. As durações incluem o dia de início. 5d a partir de segunda, dia 5, vai até sexta, dia 9, e não até o dia 10. Um erro de um dia aqui desloca todas as tarefas do arquivo e mesmo assim ele renderiza perfeitamente — que é o pior modo de falha possível, porque nada parece quebrado.

2. after junto com excludes weekends é onde moram os bugs de verdade. Se uma antecessora termina numa sexta, a sucessora começa na segunda — não no sábado. Qualquer ferramenta que resolva o after somando um dia de calendário vai colocar tarefas em fins de semana num arquivo que os proíbe explicitamente, e todas as datas seguintes derivam a partir dali. A nossa fazia isso, por pouco tempo. A correção passa a aritmética pelo calendário útil, para que a importação concorde com o que o Mermaid desenha, e o teste que protege isso afirma a propriedade em vez de datas específicas: nenhum início ou término derivado pode cair num dia excluído. Datas que você digitou à mão ficam onde você as pôs, fim de semana ou não — mover em silêncio a data explícita de um autor é o tipo errado de ajuda.

3. Não existe escape. Os dois-pontos iniciam a lista de campos e a vírgula separa campos, então uma tarefa chamada Fase 2: projeto, revisão vira uma tarefa "Fase 2" com campos sem sentido. Mantenha dois-pontos, vírgulas e ponto e vírgula fora dos nomes; na exportação nós trocamos esses caracteres por espaço em vez de emitir uma linha que não vai ser interpretada.

4. Uma duração ilegível vira zero em silêncio. Escreva 3dd e você recebe uma barra de comprimento zero em vez de um erro. Depois de uma edição em massa, procure tarefas invisíveis.

Os limites de um formato de diagrama

O gantt do Mermaid é uma linguagem de desenho, não um motor de cronograma, e a diferença aparece no instante em que você quer que o gráfico responda a uma pergunta em vez de ilustrar uma resposta já conhecida.

• Sem recursos. Não há campo para quem faz o serviço, nem custo, nem esforço, nem unidade. Não dá para superalocar alguém no Mermaid porque o Mermaid não sabe que alguém existe.
• Sem folga e sem caminho crítico calculado. crit é uma cor que você aplica na mão. Nada percorre o grafo de precedências, calcula datas cedo e tarde ou diz qual cadeia comanda a data de entrega. Um diagrama com todas as barras marcadas como crit é tão válido quanto um sem nenhuma.
• Sem linha de base. Não há onde registrar o que o plano dizia no mês passado, então não existe desvio para mostrar nem atraso para medir.
• Apenas término-início. after é FS com defasagem zero. Início-início, término-término, início-término e qualquer defasagem ou antecipação não têm onde caber. Planos reais estão cheios de "começar o teste três dias depois que o desenvolvimento começar" — no Mermaid isso vira uma data fixa, e a ligação some.
• Sem percentual de avanço. Uma tarefa com 40% e outra com 90% são as duas simplesmente "active".
• Seções planas. Sem grupos aninhados, então uma estrutura analítica com mais de um nível achata na entrada.

Nada disso faz dele um formato ruim. Faz dele um formato de publicação: ótimo para mostrar um cronograma, inútil para derivar um. É exatamente por isso que a ida e volta importa.

Editar visualmente e colar o texto de volta

Muitas ferramentas renderizam Mermaid. O que faltava era o caminho inverso — arrastar barras e recuperar a sintaxe.

1. Cole o diagrama em ✨ Colar no Gantt, ou use 📂 Abrir para carregar um arquivo .mmd ou um .md com bloco cercado. A detecção é pelo conteúdo, não pela extensão.
2. Confira o aviso de importação: ele diz quantas tarefas entraram e o que foi adivinhado no caminho.
3. Arraste, ligue e reprograme como em qualquer outro gráfico. O excludes weekends liga o Calendário de trabalho, de modo que as datas geradas concordam com o arquivo de origem.
4. Ative Reprogramar se quiser que as precedências acomodem tudo sozinhas ao mover uma barra.
5. Ligue Caminho crítico para ver a cadeia que o Mermaid nunca calculou.
6. Vá em ⬇ Exportar ▸ 🧜 Mermaid gantt (texto) e escolha Copiar para a área de transferência ou Baixar .mmd.
7. Cole de volta no seu README e faça o commit do diff.

A ida e volta perde informação de um jeito conhecido e sem surpresas. O avanço mapeia 100% para done e de 1% a 99% para active na saída; active volta como 50% na entrada — um palpite sobre o qual você é avisado, em vez de descobrir num relatório de status. As ligações que não conseguem ser escritas como after — qualquer uma com defasagem, e qualquer SS, FF ou SF — viram datas absolutas, que continuam corretas mesmo deixando de ser fáceis de manter.

Uma assimetria deliberada, e não um defeito: crit é escrito na exportação e nunca lido na importação. Na saída ele é derivado — o editor calculou o caminho crítico a partir do grafo de precedências, então a tag é verdadeira no momento em que é escrita. Na entrada, ele é uma palavra que alguém digitou num arquivo que pode estar semanas desatualizado, e confiar nela permitiria que um diagrama velho pintasse de vermelho uma cadeia que não é crítica. Então ele é escrito e depois ignorado: o caminho crítico que você vê depois de uma importação foi recalculado, não afirmado.

Vale lembrar como esse recálculo funciona aqui: o caminho crítico é "como posicionado". Uma precedência só consegue empurrar uma tarefa para a frente, nunca puxá-la para trás — então uma barra que você arrastou para uma data mais tardia fica onde você a colocou, e a criticidade é calculada em cima do desenho real e não de um plano ideal que ninguém aprovou.

Há também um efeito colateral simpático para quem usa um LLM para rascunhar cronogramas: peça a sintaxe gantt do Mermaid, cole a resposta e você tem um gráfico editável de verdade, com caminho crítico calculado — sem chave de API e sem servidor no meio.

Perguntas frequentes

Modelos que usam isso

• Gestão de projetos

Leia também

• Precedências: FS, SS, FF, SF
• O caminho crítico
• O que é um gráfico de Gantt?
• Voltar aos guias

Este artigo também está disponível em inglês.