Comece aqui — a ordem do diagnóstico
Quando uma tabela Markdown quebra, nenhum parser explica o motivo. Se a tabela não é reconhecida, ela vira silenciosamente um parágrafo comum. Se o limite de uma célula é interpretado errado, você recebe colunas deslocadas sem nenhum aviso. Sem mensagem de erro, a única saída é eliminar causas em ordem.
São cinco verificações, ordenadas pela confiabilidade com que cada uma quebra tabelas e pelo custo de conferir:
- A linha separadora tem o mesmo número de colunas da linha de cabeçalho? (A divergência é a única condição de sintaxe que impede o reconhecimento da tabela no nível da especificação)
- Existe um pipe
|sem escape dentro de alguma célula — inclusive dentro de código entre crases? - Existe uma linha em branco antes da tabela?
- Seu renderizador suporta tabelas GFM?
- É um problema de ambiente, e não de sintaxe (tipo de célula no Jupyter, o CSS da plataforma)?
O atalho mais rápido para dividir o problema ao meio é colar uma tabela mínima:
| A | B |
| --- | --- |
| 1 | 2 |
Se essas três linhas não renderizam como tabela, o problema é o renderizador ou o ambiente, não a sua tabela (pule para a segunda metade do sintoma 1). Se renderizam, o problema está em como a sua tabela foi escrita — siga do sintoma 1 em diante.
Para ver como um parser GFM realmente interpreta a sua tabela, cole-a no Markdown para HTML. Ele mostra o HTML produzido por um parser GFM baseado no marked, tudo no seu navegador: se aparecer uma tag <table> na saída, o parse funcionou. Nada do que você cola é enviado para lugar algum. Vale lembrar que isso verifica o parse da família GFM; não reproduz exatamente o Notion, a wiki da sua empresa nem a plataforma onde você publica.
Este artigo é só sobre solução de problemas. Para aprender a sintaxe do zero, veja a sintaxe de tabelas em Markdown.
Sintoma 1: a tabela aparece como texto simples
Suas linhas separadas por pipes aparecem como um parágrafo comum. Isso significa que o parser nunca as reconheceu como tabela.
Linha separadora e cabeçalho com números de colunas diferentes
Esta é a única condição de sintaxe que anula o reconhecimento da tabela de forma confiável. A especificação do GFM é explícita: se o número de colunas da linha separadora não bate com o cabeçalho, o bloco não é tratado como tabela. Não há erro — ele simplesmente cai para parágrafo.
Eis um exemplo quebrado. O cabeçalho tem três colunas, mas a linha separadora só tem duas:
| Nome | E-mail | Papel |
| --- | --- |
| Mika | mika@example.com | admin |
Iguale a linha separadora ao cabeçalho e a tabela renderiza:
| Nome | E-mail | Papel |
| --- | --- | --- |
| Mika | mika@example.com | admin |
Você só precisa contar duas linhas: o cabeçalho e a separadora. Linhas de dados com células a mais ou a menos não quebram o reconhecimento (tratamos disso no sintoma 2).
Falta uma linha em branco antes da tabela
Alguns parsers se recusam a reconhecer uma tabela que começa logo depois de um parágrafo, sem linha em branco no meio. Nos meus testes (originais 2026-06-12, reconfirmados em 2026-06-23 com o script de reprodução em scripts/benchmarks/markdown-table-parsers/), o renderizador de produção do GitHub (via Markdown API), o marked 18.0.5 e o remark-gfm 4.0.1 reconheceram a tabela sem a linha em branco — mas outras implementações e plataformas não reconhecem. Adicionar uma linha em branco é a correção mais barata que existe, então confira logo depois das colunas.
"Precisa de pelo menos três traços" é quase um mito
Artigos bem ranqueados costumam afirmar que cada coluna da linha separadora exige três ou mais traços. A especificação do GFM não define mínimo nenhum. Verifiquei que um único traço por coluna (| - | - |) renderiza como tabela no renderizador de produção do GitHub, no marked 18.0.1 e no remark-gfm 4.0.1.
O que confunde é o desacordo em três frentes: a documentação do GitHub fala em três ou mais, a especificação não impõe regra e a implementação aceita um. Trate os três traços como convenção de legibilidade. Mexer na quantidade de traços para consertar uma tabela quebrada é perda de tempo — confira primeiro as colunas e as linhas em branco. A matriz completa de testes com quatro parsers está na sintaxe de tabelas em Markdown.
A única exceção real é combinar pipes externos omitidos com um único traço, que aparece no sintoma 4.
Seu renderizador não suporta tabelas GFM
Tabelas não fazem parte do núcleo do Markdown. O CommonMarkAbre em uma nova aba puro não define sintaxe de tabela nenhuma — tabelas são uma extensão do GFM. Um renderizador CommonMark estrito, sem extensões, nunca vai renderizar a sua tabela, por mais correta que esteja. O contexto completo está em CommonMark vs GFM.
Problemas de ambiente fora da sintaxe também entram aqui. No Jupyter Notebook, por exemplo, uma célula deixada como Code não renderiza Markdown de jeito nenhum. Se o teste da tabela mínima falhou, procure nessa família de causas.
Sintoma 2: colunas deslocadas ou célula que se divide sozinha
A tabela renderiza, mas as colunas caem no lugar errado, ou uma célula vira duas.
Um pipe sem escape dentro de uma célula
O pipe | é o separador de colunas, então escrevê-lo como conteúdo divide a coluna ali mesmo. A tabela a seguir queria mostrar "cmd1 | cmd2" como exemplo de comando na primeira coluna — em vez disso, "cmd1" e "cmd2" caem em células separadas, e "encadeado com pipe", que excede as duas colunas do cabeçalho, é descartado em silêncio:
| Comando | Significado |
| --- | --- |
| cmd1 | cmd2 | encadeado com pipe |
Troque o pipe por \| (escape com barra invertida) ou | (entidade HTML numérica) e ele fica em uma célula só:
| Comando | Significado |
| --- | --- |
| cmd1 \| cmd2 | encadeado com pipe |
Código entre crases também não protege o pipe
Por mais contraintuitivo que pareça, envolver o pipe em crases não ajuda. A divisão de células acontece antes de os elementos inline serem interpretados:
| Comando | Significado |
| --- | --- |
| `a | b` | era para ser código |
Essa linha se divide nas duas células `a e b` no renderizador de produção do GitHub, no marked e no remark-gfm (testado em 2026-06-12). As crases nunca formam par e aparecem como caracteres literais.
A correção é usar o escape com barra invertida dentro do código também:
- Escreva
`a \| b`— o\|funciona inclusive dentro das crases. Verificado: renderiza como o códigoa | bno GitHub, no marked e no remark-gfm |não funciona dentro de código entre crases. Ali as referências de caracteres não são expandidas, então os seis caracteres|aparecem como estão- Resumindo: em texto normal de célula funcionam tanto
\|quanto|; dentro de crases, só\|
Linhas de dados com células a mais ou a menos viram deslocamento
Uma linha de dados com número de células diferente do cabeçalho não quebra a tabela — ela aparece como desalinhamento visual. Nos meus testes, linhas com células faltando são completadas com células vazias, e as células excedentes são descartadas em silêncio. Se o valor da última coluna parece sumir, procure um pipe extra (uma coluna a mais) naquela linha.
Escapar pipes na mão e policiar o número de colunas em uma tabela grande cansa rápido. Se os dados vivem em CSV ou planilha, cole no CSV para Markdown e receba uma tabela com colunas consistentes e pipes já escapados.
Sintoma 3: uma quebra de linha dentro da célula destrói a tabela
A sintaxe de tabelas Markdown não tem quebra de linha dentro de célula. Apertar Enter no meio de uma célula inicia uma nova linha da tabela — ou encerra a tabela de vez.
A alternativa é uma tag HTML <br> direto na célula:
| Item | Notas |
| --- | --- |
| Configuração A | primeira linha<br>segunda linha |
Repare que <br> não é sintaxe de Markdown — é uma saída via HTML cru. Renderizadores que desativam ou sanitizam HTML vão ignorá-lo. Nesses ambientes, o realista é dividir a frase ou dividir a linha. A referência completa de escapes e quebras de linha está na cheatsheet de tabelas GFM.
Sintoma 4: funciona no GitHub, quebra em outro lugar
O mesmo Markdown pode ser interpretado de formas diferentes por parsers diferentes. A divergência mais clara que medi é a combinação de pipes externos omitidos com um único traço:
A | B
- | -
1 | 2
A linha separadora começa com - (hífen mais espaço), então os parsers divergem sobre ser ou não um marcador de lista. GitHub e remark-gfm leem como lista e não renderizam tabela; o marked renderiza uma tabela (testado em 2026-06-12). Se você omite os pipes externos, use pelo menos dois traços — ou mantenha os pipes externos e o problema nem aparece.
"Na minha prévia funciona, mas quebra onde eu publico" quase sempre se resume a uma diferença de parser como essa, ou à falta de suporte a GFM do sintoma 1. Para descobrir o que a plataforma de destino aceita, combine o teste da tabela mínima com a checagem do HTML de saída no Markdown para HTML. Para as diferenças plataforma a plataforma — o Notion ignorando os dois-pontos de alinhamento e o <br>, por exemplo — veja a tabela de plataformas na sintaxe de tabelas em Markdown.
Quando reconstruir vence consertar
Contar pipes em uma tabela quebrada de 30 linhas raramente vale a pena. Se os dados de origem existem como CSV, Excel ou planilha, regenerar a tabela leva menos de um minuto:
- Copie os dados como CSV (um intervalo copiado do Excel ou do Google Sheets também serve)
- Cole no CSV para Markdown
- Copie a tabela Markdown gerada por cima da tabela quebrada
Consistência de colunas, escape de pipes e linha separadora ficam por conta da ferramenta. A conversão roda inteiramente no seu navegador e os dados não são enviados a lugar nenhum — o que importa quando a tabela contém dados internos. Para o passo a passo completo, veja como converter CSV em tabela Markdown; para transformar a tabela corrigida em HTML, o guia de Markdown para HTML.
Fechamento — leve a ordem com você
Quando a tabela aparece como texto simples: confira o número de colunas de cabeçalho e separadora, depois a linha em branco antes da tabela, depois se o renderizador suporta GFM. Quando as colunas deslocam: procure pipes sem escape nas células (escape com \|, inclusive dentro de crases) e linhas de dados com colunas extras. A quantidade de traços não é a culpada, exceto no caso-limite dos pipes externos omitidos.
Para diagnosticar, conferir o HTML de saída no Markdown para HTML é o atalho; para consertar, regenerar com o CSV para Markdown é o caminho seguro. Os dois rodam inteiramente no seu navegador.
Artigos relacionados
- Sintaxe de tabelas em Markdown — fundamentos de sintaxe e a matriz de testes com quatro parsers
- Cheatsheet de tabelas GFM — referência de alinhamento, escapes e quebras de linha
- CommonMark vs GFM — por que tabelas são uma extensão
- Como converter CSV em tabela Markdown — a rota de regeneração em detalhe
- Guia de Markdown para HTML — como funciona a conversão por trás da checagem de renderização