Cheat Sheet de Tabelas Markdown do GitHub: Alinhamento, Células Vazias e Quebras de Linha

Resumo — cheat sheet de tabelas GFM

Uma tabela GFM é uma tabela separada por pipes definida pela especificação do GitHub Flavored Markdown — uma extensão do CommonMark que o CommonMark estrito não inclui.

• Uma tabela é formada por uma linha de cabeçalho, uma linha separadora (---, no mínimo três hífens por coluna) e linhas de dados, todas divididas por pipes |. É obrigatória uma linha em branco antes e depois da tabela.
• O alinhamento é definido por dois-pontos na linha separadora: :--- à esquerda, :---: ao centro, ---: à direita.
• Um pipe literal dentro de uma célula é \| (escape com contrabarra); | (entidade HTML) é a alternativa quando um renderizador não trata bem a forma com contrabarra.
• Uma quebra de linha visível dentro de uma célula é uma tag <br> literal. Funciona no GitHub e no GitLab; Obsidian, Notion e outros variam conforme o modo de edição ou o caminho de importação.
• Mesclagem de células, múltiplos parágrafos, blocos de código e outros elementos de bloco não são possíveis em tabelas GFM. Use uma <table> HTML quando precisar deles.
• Não quer digitar os pipes na mão? Cole o CSV em CSV to Markdown e obtenha uma tabela compatível com GFM instantaneamente.

Este é um cartão de consulta rápida para quem já sabe mais ou menos como escrever uma tabela Markdown. Se você quer aprender a montar uma do zero, comece por Tabelas em Markdown: sintaxe, alinhamento e exemplos para copiar e colar.

O que as tabelas GFM conseguem e não conseguem fazer

Quando você precisa de elementos de bloco ou células mescladas, escreva uma <table> HTML diretamente no seu Markdown (veja "O que as tabelas Markdown não conseguem fazer" abaixo).

Estrutura básica — o par mínimo

Uma tabela GFM tem três partes: uma linha de cabeçalho, uma linha separadora e linhas de dados. O separador precisa de pelo menos três hífens por coluna; os pipes no início e no fim são opcionais.

Sintaxe:

| Name | Role |
| --- | --- |
| Mika | admin |
| Noah | viewer |

Renderizada:

A menor tabela possível (uma linha de cabeçalho + uma linha de dados):

| key | value |
| --- | --- |
| name | FormatArc |

Cheat sheet de sintaxe de alinhamento

A posição dos dois-pontos na linha separadora define o alinhamento da coluna.

Sintaxe:

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

Renderizada:

Alinhar colunas numéricas à direita mantém os dígitos alinhados e mais fáceis de ler.

Formatação inline dentro das células

As células aceitam elementos inline. Blocos de código, listas e múltiplos parágrafos não são permitidos.

Imagens funcionam nas células, mas deixam a tabela alta e difícil de ler, então ícones pequenos são o limite prático.

Células vazias e em branco

Deixar uma célula vazia é permitido — não coloque nada entre os pipes e a célula é renderizada em branco.

Sintaxe:

| Name | Role | Note |
| --- | --- | --- |
| Mika | admin | |
| Noah | | viewer |

Renderizada:

Duas coisas confundem as pessoas:

• A quantidade de colunas ainda precisa bater. Uma célula vazia é | | — dois pipes sem nada entre eles — não um pipe que faltou. Se você remover um pipe, a linha fica com uma coluna a menos e a tabela desalinha.
• Quando a primeira célula de uma linha está vazia e você também omite o pipe inicial, alguns renderizadores perdem a primeira coluna da linha. Mantenha o | inicial (| | value |) ou, como alternativa, coloque um link vazio []() nessa primeira célula para que ela não seja tratada como ausente.

Uma célula vazia não é uma célula mesclada. O GFM não tem rowspan nem colspan, então uma célula em branco é apenas em branco — ela não se une visualmente à célula acima nem ao lado. Quando você precisa de mesclagem, mude para uma <table> HTML (veja abaixo).

Escapando pipes e caracteres especiais

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

Sintaxe:

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

Renderizada:

Para mostrar uma contrabarra literal, escreva \\; para um espaço não separável, use  . Se você monta tabelas a partir de CSV ou HTML, o escape de pipes é tratado automaticamente por CSV to Markdown e HTML to Markdown, então você nem precisa pensar nisso.

Quebras de linha dentro das células, por plataforma

A especificação de tabelas Markdown não suporta quebras de linha literais dentro de uma célula. Para uma quebra visível, escreva uma tag <br> literal — mas o suporte varia.

Se uma tabela precisa de quebras de linha confiáveis em muitas colunas, não force isso numa tabela GFM — use uma <table> HTML ou divida as colunas.

Por que as tabelas quebram — um checklist

Quando uma tabela é renderizada errada, verifique estes pontos de cima para baixo:

• Há uma linha em branco antes e depois da tabela? — Uma tabela colada à linha anterior pode não ser reconhecida (especialmente no GitHub)
• Há uma linha de cabeçalho? — O GFM exige uma. Se você não quer cabeçalhos visíveis, ainda precisa de uma linha de cabeçalho vazia mais o separador
• A linha separadora tem pelo menos três hífens por coluna? — -- não é renderizado como tabela em alguns renderizadores
• As linhas de cabeçalho, separadora e de dados têm a mesma quantidade de colunas (pipes)? — Linhas de dados curtas são preenchidas com células vazias; as longas têm as células extras descartadas
• Há um | não escapado dentro de uma célula? — Se houver, troque por \| ou |
• Alguma linha está indentada (quatro ou mais espaços iniciais)? — Ela pode ser confundida com um bloco de código
• Há um elemento de bloco (bloco de código, lista) dentro de uma célula? — Não é permitido em tabelas GFM

Gere tabelas a partir de CSV / HTML / JSON

Escrever uma tabela de cinco linhas na mão é tranquilo. Passando de 20 linhas, ou com muitas colunas, alinhar e escapar pipes fica sujeito a erros. Dependendo do seu formato de origem, uma ferramenta do FormatArc o transforma em uma tabela compatível com GFM em um único passo.

• A partir de CSV / uma planilha / Excel: cole em CSV to Markdown e execute. Para um passo a passo, veja Como converter CSV em uma tabela Markdown; para uso em README, veja Adicionando uma tabela a um README do GitHub.
• A partir de HTML existente (uma tabela de página web, uma exportação do Notion, um dump de CMS): cole o HTML em HTML to Markdown e os elementos <table> viram tabelas com pipes. Veja o guia de HTML to Markdown.
• A partir de JSON (uma resposta de API ou logs): passe por CSV. Monte um CSV em que as chaves de cada objeto sejam os nomes das colunas e os valores sejam as células das linhas, depois alimente CSV to Markdown. Veja a seção "Montando uma tabela a partir de dados JSON" em Adicionando uma tabela a um README do GitHub.
• Para colar a tabela Markdown resultante em um CMS que não suporta Markdown, ou em um e-mail HTML, converta-a com Markdown to HTML. Veja o guia de Markdown to HTML.

Tudo roda no seu navegador, então dados internos e listas de clientes nunca são enviados a um servidor. Sem cadastro, sem upload.

Se a tabela vai para um prompt de LLM, uma tabela Markdown custa muito menos tokens do que o HTML equivalente e é extraída com mais precisão. Veja Markdown vs HTML para LLMs para a comparação medida de tokens e precisão.

O que as tabelas Markdown não conseguem fazer — quando mudar para HTML

As tabelas GFM não conseguem expressar o que segue. Em vez disso, mude para uma <table> HTML pura dentro do seu Markdown:

• Células mescladas entre linhas ou colunas (rowspan / colspan)
• Listas com marcadores, múltiplos parágrafos ou blocos de código dentro de uma célula
• Larguras de coluna fixas em pixels ou porcentagens
• Um título ou outra tabela aninhada dentro de uma tabela

Note que o GitHub e plataformas semelhantes restringem o HTML dentro das tabelas por segurança: <br> passa, mas estilos inline como <span style="..."> são ignorados, então você não consegue mudar cores ou tamanhos de fonte por esse caminho.

CommonMark e tabelas

O CommonMark puro não define sintaxe de tabela. As tabelas com pipes são uma extensão do GFM, definida na seção Tables (extension) da especificação do GitHub Flavored Markdown. Um renderizador que implementa CommonMark estrito sem extensões vai exibir | col | como texto puro, não como tabela. A forma mais rápida de saber se sua ferramenta é compatível com GFM é escrever uma tabela simples e ver se ela é renderizada.

Perguntas frequentes

Qual é a menor tabela Markdown?

Três linhas: uma linha de cabeçalho, uma linha separadora e uma linha de dados. Escreva | key | value |, depois | --- | --- | abaixo e então | name | FormatArc |. A linha separadora precisa de pelo menos três hífens por coluna.

Como deixo uma célula vazia?

Não coloque nada entre os dois pipes: | value | |. A quantidade de colunas ainda precisa bater com o cabeçalho, então uma célula vazia é | |, não um pipe que faltou. Se a célula vazia for a primeira de uma linha, mantenha o pipe inicial (| | value |) — alguns renderizadores descartam a primeira coluna de uma linha quando faltam tanto o pipe inicial quanto a célula. Uma célula em branco não é uma célula mesclada; o GFM não tem rowspan nem colspan.

Devo usar \| ou |?

Use primeiro o escape com contrabarra \|. Ele é documentado pelo GitHub e funciona na maioria dos renderizadores GFM. Recorra a | apenas quando um renderizador não tratar bem \| ou quando copiar e colar entre editores quebrar a forma.

Posso mudar a cor do texto ou o tamanho da fonte dentro de uma célula?

Não apenas com tabelas GFM. O GitHub e plataformas semelhantes ignoram estilos inline como <span style="..."> dentro de tabelas, então mudanças de cor e tamanho não têm efeito. Se você precisa estilizar células, tire a tabela do GFM e use HTML, ou repense o layout.

Existe alguma orientação para larguras de coluna?

O Markdown não tem sintaxe de largura de coluna; os renderizadores dimensionam as colunas para caber no conteúdo. Como regra prática, se um README ou doc é lido tanto no desktop quanto no mobile, mantenha as tabelas em cinco ou seis colunas. Além disso, o GitHub adiciona rolagem horizontal e a tabela fica difícil de ler.

Posso mesclar células (rowspan / colspan)?

Não em tabelas GFM. Para células mescladas, escreva uma <table> HTML diretamente no seu Markdown — mas verifique a saída renderizada primeiro, já que o GitHub e outros restringem alguns atributos HTML.

Minha tabela aparece como | col | em vez de ser renderizada. Por quê?

As causas habituais: nenhuma linha em branco antes ou depois da tabela, menos de três hífens na linha separadora, nenhuma linha de cabeçalho, quantidades de colunas que não batem, ou um renderizador que não suporta a extensão de tabelas do GFM (CommonMark estrito). Percorra o checklist "Por que as tabelas quebram" acima, de cima para baixo.

Artigos relacionados

• Tabelas em Markdown: sintaxe, alinhamento e exemplos para copiar e colar — um tutorial passo a passo para montar uma tabela do zero
• Como converter CSV em uma tabela Markdown — conversão em um passo a partir de dados de Excel ou planilha
• Adicionando uma tabela a um README do GitHub — gere tabelas de README a partir de CSV / JSON
• Guia de conversão de Markdown para HTML — cole sua tabela em um CMS que não suporta Markdown
• Guia de HTML para Markdown — extraia tabelas de páginas web ou exportações do Notion