Sintaxe de tabelas Markdown no GitHub: 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 — pelo menos três hifens - 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:

• No mínimo 3 traços por coluna na linha separadora. Dois ou menos (--) falham silenciosamente — a maioria dos renderizadores GFM deixa de tratar aquilo como uma tabela
• 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
• 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, a linha separadora é quase sempre a culpada: poucos traços, contagem de colunas que não bate ou a falta de uma linha em branco antes da tabela.

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 precisa de pelo menos três hifens (---) por coluna
• 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), 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). O CommonMark 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.

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  .

Armadilhas comuns

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.

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