Sintaxe de tabelas em Markdown: pipes, hifens e alinhamento

Resposta rápida

As tabelas em Markdown usam o caractere pipe | e hifens -. Nada mais é necessário.

| Name | Email | Role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

Se digitar pipes na mão não for exatamente a sua ideia de diversão, cole um CSV em CSV para Markdown e obtenha uma tabela formatada na hora. O restante deste artigo percorre a sintaxe em detalhes.

Sintaxe básica — pipes e hifens

Uma tabela Markdown tem três partes:

1. Linha de cabeçalho — nomes das colunas separados por pipes |
2. Linha separadora — hifens - (por convenção, três por coluna), separando o cabeçalho dos dados
3. Linhas de dados — valores das células separados por pipes

| Item | Value |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

Os pipes no início e no fim da linha são opcionais, mas recomendados para a legibilidade. As larguras das colunas não precisam estar alinhadas no código-fonte; o renderizador cuida disso.

Anatomia do pipe e da linha separadora

O caractere pipe | separa as colunas. A linha separadora — também chamada de separador de cabeçalho ou linha de hifens — é formada por hifens - (frequentemente chamados de traços) e informa ao renderizador onde o cabeçalho termina e os dados começam.

Algumas regras que vale conhecer sobre pipes e traços:

• Três traços por coluna (---) é a convenção, não uma regra do parser. A especificação GFM não define um mínimo, e -- ou até um único - é renderizado como tabela nos renderizadores GFM (verificado com marked 18.0.5 e remark-gfm 4.0.1). Use três traços pela legibilidade, não porque menos vá falhar
• O que realmente quebra uma tabela é uma linha separadora cuja quantidade de colunas difere da linha de cabeçalho. A especificação GFM é explícita: se as quantidades não baterem, a tabela simplesmente não é reconhecida. Mais abaixo isso é medido caso a caso
• Os pipes no início e no fim da linha são opcionais, mas recomendados para a legibilidade. | A | B | e A | B renderizam da mesma forma — com uma exceção medida: se além disso você deixar um único traço na linha separadora, GitHub e remark-gfm leem a linha como lista e a tabela não aparece
• Os dois-pontos de alinhamento (:---, :---:, ---:) só vão na linha separadora, nunca nas linhas de dados
• A linha de cabeçalho é obrigatória no GFM. A especificação central do CommonMark não tem tabelas, então tabelas sem cabeçalho só existem em extensões personalizadas

Se um renderizador ignorar a sua tabela, verifique primeiro a quantidade de colunas: uma linha separadora que não bate com a linha de cabeçalho impede totalmente o reconhecimento da tabela. A outra causa comum é a falta de uma linha em branco antes da tabela — a quantidade de traços quase nunca é o problema.

Alinhamento de colunas — esquerda, centro, direita

Adicione dois-pontos : na linha separadora para controlar o alinhamento:

| Product | Qty | Price |
| :--- | :---: | ---: |
| Apples | 3 | 1.20 |
| Oranges | 10 | 0.80 |

Alinhar à direita as colunas numéricas mantém os dígitos alinhados e torna a tabela mais fácil de ler.

Suporte ao GFM (GitHub Flavored Markdown)

GitHub, GitLab, Zenn, Qiita, Notion, Obsidian e a maioria das plataformas voltadas a desenvolvedores suportam a sintaxe de tabelas do GFM. Tudo o que foi mostrado acima funciona como está nessas plataformas.

Algumas coisas que vale lembrar sobre as tabelas do GFM:

• A linha de cabeçalho é obrigatória. Você não pode criar uma tabela sem cabeçalho no GFM
• A linha separadora usa hifens (---) — três por coluna por convenção, embora a especificação permita menos
• A formatação inline (`code`, links, texto riscado) funciona dentro das células
• Alguns parsers exigem uma linha em branco antes e depois da tabela para reconhecê-la

Suporte a tabelas com pipe por plataforma

Os três elementos básicos de uma tabela — tabelas com pipe |, alinhamento com dois-pontos na linha separadora (:---) e <br> para uma quebra de linha dentro da célula — têm suporte desigual entre as plataformas. A tabela abaixo resume o comportamento de cada plataforma, com as notas por plataforma logo em seguida:

Notas sobre a tabela:

• O GitHub segue a especificação do GitHub Flavored Markdown — Tabelas (extensão)Abre em uma nova aba, que define as tabelas com pipe e o alinhamento com dois-pontos na linha delimitadora. As células são analisadas como conteúdo inline, então HTML bruto inline como <br> é permitido, e o GitHub o renderiza como uma quebra de linha dentro da célula.
• O GitLab Flavored Markdown documenta a mesma sintaxe de tabelas com pipe e de alinhamento, e sua documentação observa explicitamente que você pode usar uma tag <br> para forçar várias linhas dentro de uma célula.
• O Obsidian suporta tabelas com pipe e alinhamento com dois-pontos em sua sintaxe de tabelas documentada e, na prática, renderiza uma tag <br> como uma quebra de linha dentro da célula.
• O Notion pode importar ou colar tabelas com pipe, mas as converte em seus próprios blocos de tabela em vez de renderizar GFM. As tabelas do Notion não têm alinhamento por coluna, então os dois-pontos de alinhamento (:---) não têm efeito visível, e um <br> dentro da célula não é renderizado como quebra de linha.

As regras exatas estão na especificação do GitHub Flavored Markdown — Tabelas (extensão)Abre em uma nova aba. O CommonMarkAbre em uma nova aba puro não define a sintaxe de tabelas, então as tabelas são tecnicamente uma extensão do GFM. Renderizadores que seguem o CommonMark estrito (sem extensões) não as renderizam como tabelas. Para o conjunto completo de diferenças entre CommonMark e GFM, veja CommonMark vs GFM; para uma referência rápida da sintaxe de tabelas do GFM — alinhamento, escape, quebras de linha — veja o guia rápido de tabelas GFM.

Comportamento real da linha separadora — 4 renderizadores medidos (GitHub / marked / remark-gfm / CommonMark)

A extensão de tabelas do GFM define a linha separadora apenas como células "whose only content are hyphens (-), and optionally, a leading or trailing colon (:)" (cujo único conteúdo são traços e, opcionalmente, dois-pontos no início ou no fim). Um número mínimo de traços não aparece em lugar nenhum da especificação. A documentação do próprio GitHub diz que cada coluna precisa de pelo menos três, mas a especificação não fixa essa regra e o renderizador do GitHub aceita um só: o próprio exemplo de alinhamento da especificação usa :-: com um único traço.

Para fixar essa afirmação, passamos o mesmo conjunto de casos limite pelo renderizador de produção do GitHub (via Markdown API), marked, remark-gfm e uma cadeia CommonMark estrita sem extensões. O script de reprodução está em scripts/benchmarks/markdown-table-parsers/ no repositório. Medido em 2026-07-15 com marked 18.0.5, remark-gfm 4.0.1 e remark-parse 11.0.0:

Três achados que valem a pena guardar:

• A quantidade de traços nunca decide se a tabela é renderizada. Um traço se comporta exatamente como três no GitHub, no marked e no remark-gfm — três traços são uma convenção de legibilidade, não um requisito
• A única diferença real entre parsers está na penúltima linha: se você omite os pipes externos e usa um único traço, a linha separadora começa com - , que GitHub e remark-gfm leem como marcador de lista; o marked continua vendo uma tabela. Se omitir os pipes externos, deixe pelo menos dois traços
• O que quebra a tabela de forma confiável em todos os casos é uma linha separadora cuja quantidade de colunas não bate com o cabeçalho. A tabela simplesmente não é reconhecida e vira parágrafo, sem nenhuma mensagem de erro

O script de reprodução e os dados brutos estão no repositório do site, em scripts/benchmarks/markdown-table-parsers/.

Escapando pipes e caracteres especiais

Um | literal dentro de uma célula colide com o separador de colunas e quebra a tabela. Há duas formas de escrevê-lo com segurança:

| Command | Meaning |
| --- | --- |
| cmd1 \| cmd2 | backslash escape |
| cmd1 | cmd2 | HTML entity |

• \| (escape com barra invertida) funciona no GitHub, GitLab, Notion, Obsidian, Zenn, Qiita e na maioria dos renderizadores GFM
• | (entidade numérica HTML) é uma alternativa confiável quando um renderizador lida mal com a forma de barra invertida, e sobrevive melhor ao copiar e colar entre editores do que \|

Para exibir uma barra invertida literal em uma célula, escreva \\. Para inserir um espaço não separável, use  .

Fora das tabelas vale a mesma regra da barra invertida quando caracteres como * e # viram formatação por conta própria. Os caracteres de escape do Markdown listam todos os símbolos escapáveis e quais realmente funcionam em cada renderizador.

Envolver o pipe em crases também não o protege, embora alguns guias descrevam as crases como inerentemente seguras diante da sintaxe de tabelas. A divisão de células acontece antes de os elementos inline serem interpretados, então um pipe dentro de crases ainda precisa do escape com barra invertida:

| a | b |
| --- | --- |
| `x | y` | z |

Ao passar essa linha pela API de Markdown do GitHub, pelo marked 18.0.5 e pelo remark-gfm 4.0.1, os três renderizadores dividem a célula de código: a saída tem apenas duas células <td>, `x e y`, com as crases sem par aparecendo como caracteres literais, e o terceiro valor z é descartado silenciosamente (medido em 2026-08-29, passos de reprodução em scripts/benchmarks/markdown-table-parsers/). O escape com barra invertida continua funcionando dentro de crases — o caso `a \| b` do mesmo benchmark permanece intacto nos três renderizadores, então \| também é a correção aqui. Tabelas Markdown que não renderizam — resolva por sintoma percorre esse padrão junto com outras causas de divisão de células.

Armadilhas comuns

Se uma tabela é exibida como pipes literais ou é cortada no meio, a causa costuma ser um dos padrões abaixo. Para um diagnóstico baseado em sintomas, veja Tabelas Markdown que não renderizam — resolva por sintoma.

Quebras de linha dentro das células

A especificação de tabelas Markdown não suporta quebras de linha dentro de uma célula. Se você precisa de uma quebra visível, escreva uma tag HTML <br> diretamente, embora nem todas as plataformas a renderizem.

Células vazias

Deixe um espaço (ou nada) entre dois pipes. Um espaço é preferível para a legibilidade:

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

Contagens de colunas que não batem

Se uma linha de dados tiver menos colunas que o cabeçalho, a maioria dos parsers preenche com células vazias. Se tiver mais, as extras são descartadas silenciosamente. Manter a contagem de colunas consistente evita surpresas.

Grandes conjuntos de dados — gere a partir de CSV

Escrever à mão uma tabela de cinco linhas é tranquilo. Passando de 20 linhas, ou com muitas colunas, isso fica trabalhoso e propenso a erros. Copie os dados do Excel ou de uma planilha como CSV, cole em CSV para Markdown, e a ferramenta cuida do alinhamento dos pipes e do escape para você.

Para um passo a passo, veja Como converter CSV em uma tabela Markdown. Se você precisa transformar a tabela Markdown resultante em HTML, veja o guia de conversão de Markdown para HTML. Para extrair uma tabela Markdown de um HTML existente — uma página web copiada, uma exportação do Notion ou um dump de CMS — veja o guia de HTML para Markdown. Se você quer apenas as tabelas, incluindo células com barras verticais e quebras de linha, veja como converter uma tabela HTML em Markdown.

Perguntas frequentes

Posso criar uma tabela Markdown sem cabeçalho?

Não no GFM. A linha de cabeçalho e a linha separadora são ambas obrigatórias. Se você não precisa de cabeçalhos visíveis, ainda assim tem que incluí-los — use texto de espaço reservado ou células de cabeçalho vazias.

Posso colocar links ou imagens dentro de uma célula?

Sim. Markdown inline como [text](url) e ![alt](image-url) funciona dentro das células. Tenha em mente que células largas tornam o código-fonte difícil de ler, então os links costumam ser o limite prático.

Posso controlar a largura das colunas?

O Markdown não tem sintaxe para largura de coluna. Os renderizadores dimensionam as colunas com base no conteúdo. Para um controle preciso, recorra a uma <table> HTML.

Conclusão

A sintaxe de tabelas Markdown é simples: pipes para as colunas, hifens para o separador, dois-pontos para o alinhamento. Uma vez que você conhece essas três peças, pode montar qualquer tabela.

Quando os dados ficam grandes, pule o trabalho manual. Cole um CSV em CSV para Markdown e obtenha uma tabela limpa e com escape correto em segundos.

Artigos relacionados

• Guia rápido de tabelas GFM — referência rápida para alinhamento, escape e quebras de linha
• Tabelas para README do GitHub a partir de CSV e JSON — caso de uso prático em README
• CommonMark vs GFM — contexto mais amplo da especificação, incluindo tabelas
• Tabelas Markdown que não renderizam — resolva por sintoma — diagnóstico baseado em sintomas quando uma tabela falha
• Converter tabela HTML em Markdown — converta uma tabela HTML copiada ou exportada em uma tabela de pipes