Tabelas em Markdown: sintaxe GFM, alinhamento e limites
Tabelas GFM com pipes, alinhamento e limites de células.
Uma tabela em Markdown é composta por uma linha de cabeçalho, uma linha delimitadora de hífens e as linhas de dados abaixo dela. A linha delimitadora é o que transforma os pipes em uma tabela no GFM e no Hugo.
Este guia faz parte de Ferramentas de Documentação em 2026: Markdown, LaTeX, PDF & Fluxos de Trabalho de Impressão. Os outros tipos de blocos estão na Folha de Dicas de Markdown.
As tabelas não fazem parte da sintaxe original do Markdown nem do CommonMark. Elas são a extensão de tabelas na especificação do GitHub Flavored Markdown. O Hugo 0.164 usa Goldmark com essa extensão ativada por padrão (markup.goldmark.extensions.table). Os exemplos abaixo estão delimitados (fenced) para que os pipes permaneçam literais, o que é o padrão em Blocos de código Markdown.
Sintaxe de tabela de pipes
Uma tabela tem três partes: uma linha de cabeçalho, uma linha delimitadora e zero ou mais linhas de dados. As células são separadas por |. Um pipe no início e no fim de uma linha é opcional. Os espaços ao lado de um pipe são removidos.
| Header 1 | Header 2 |
| --- | --- |
| Cell A1 | Cell B1 |
| Cell A2 | Cell B2 |
A documentação de escrita da GitHub afirma que cada célula delimitadora precisa de pelo menos três hífens, e que uma linha em branco antes da tabela é obrigatória para que a GitHub a renderize. A especificação GFM descreve a célula delimitadora como hífens, com dois-pontos opcionais em qualquer lado, e seus exemplos incluem uma célula de um único hífen. O Hugo 0.164 renderizou isso como uma tabela:
| A | B |
| - | - |
| 1 | 2 |
A mesma renderização do Hugo também transformou uma tabela em um <table> quando a linha anterior era um parágrafo e não havia linha em branco. Na GitHub, siga o delimitador de três hífens e a linha em branco. Neste site, um único hífen é suficiente e a linha em branco não é obrigatória.
|Too|Tight| com um delimitador |---|---| também foi renderizado. Os espaços ao lado dos pipes são removidos. Os espaços no primeiro exemplo mantêm um diff da fonte legível.
A linha de cabeçalho e a linha delimitadora devem ter o mesmo número de células. Se forem diferentes, o Hugo não reconhece a tabela. Isso permanece como texto comum, e os hífens então ficam sujeitos ao tipógrafo do Hugo:
| abc | def |
| --- |
| bar |
Uma linha de dados pode ser mais curta ou mais longa que o cabeçalho. Uma linha curta é preenchida com células vazias. Células além da contagem do cabeçalho são descartadas.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
A primeira dessas renderiza uma terceira célula em branco. A segunda renderiza apenas 1 e 2.
Uma linha sem pipes ainda está dentro da tabela até uma linha em branco. O Hugo 0.164 colocou um bar subsequente na tabela como uma linha com uma segunda célula vazia, correspondendo ao exemplo 202 do GFM. O próximo parágrafo começa após a linha em branco.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Alinhamento de colunas
O alinhamento é indicado por dois-pontos na linha delimitadora. --- sem dois-pontos é alinhamento à esquerda, o mesmo que :---.
| Left | Right | Center |
| :--- | ----: | :----: |
| text | 12.50 | yes |
| Esquerda | Direita | Centro |
|---|---|---|
| texto | 12.50 | sim |
Dois-pontos na linha de cabeçalho são caracteres naquela célula. Eles não definem o alinhamento. A linha delimitadora abaixo é a que o Hugo usou:
| :--- Left | Right ---: |
| :-------- | ---------- |
| Correct | Alignment |
Conteúdo de células
Inlines funcionam dentro de uma célula: ênfase, spans de código e links. Estruturas de bloco não funcionam. A especificação GFM afirma que elementos de nível de bloco não podem ser inseridos em uma tabela, então uma lista ou um bloco delimitado dentro de uma célula não é uma lista nem um delimitador.
| Feature | Status | Documentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Released* | [Docs](/api) |
| `Auth` | Beta | Coming soon |
Um pipe literal é \| ou |. O Hugo 0.164 renderizou ambos como |.
| Expression | Result |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Uma quebra de linha dentro de uma célula é um HTML <br>. Este site define markup.goldmark.renderer.unsafe para true, então essa tag é mantida. Um processador que remove HTML bruto concatenaria as duas metades.
Três hífens escritos como texto de célula são uma armadilha separada no Hugo. O tipógrafo reescreve --- em uma célula para um travessão (—). Um span de código mantém os hífens. \--- renderizou como -–.
| As text | As code |
| ------- | ------- |
| --- | `---` |
Células mescladas
O GFM não possui rowspan ou colspan. Quando uma célula deve cobrir duas linhas, a tabela é HTML. O renderer inseguro deste site deixa esse HTML na página:
<table>
<tr>
<td rowspan="2">Merged</td>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
</tr>
</table>
O escritor markdown+pipe_tables do Pandoc emite a sintaxe de pipe nesta página. Esse é o escritor usado ao converter documentos Word para Markdown. Tabelas em grade e outros layouts exclusivos do Pandoc são recursos de dialeto, cobertos em GFM vs CommonMark vs Pandoc Markdown.
Uma tabela de pipe larga rola ou transborda. As reduções portáveis são um layout transposto, várias tabelas menores, ou uma tabela HTML com seu próprio CSS. A sintaxe de pipe não tem legenda. O sumário do Hugo é construído a partir de cabeçalhos.
Verificações quando a tabela permanece como texto
Conte as células na linha de cabeçalho e na linha delimitadora. Se essas duas contagens forem diferentes, o bloco é um parágrafo. Uma linha de dados curta ainda é uma tabela, com uma célula vazia no final. A regra MD056 do markdownlint pede que todas as linhas correspondam a essa contagem, de qualquer maneira, porque uma linha curta parece uma célula em falta e uma célula extra é descartada.
Olhe para a linha delimitadora pelos dois-pontos. Um dois-pontos assentado no cabeçalho é texto, e a coluna permanece no alinhamento do delimitador.
Se --- dentro de uma célula aparecer como um único glifo de traço neste site, o tipógrafo o reescreveu. Coloque os hífens em um span de código.
Se a GitHub mostrar os pipes como texto, adicione a linha em branco que a documentação da GitHub exige e use pelo menos três hífens em cada célula delimitadora. O Hugo 0.164 já aceitava a forma mais curta.
Uma linha delimitadora ausente é a outra forma pela qual um bloco de pipe permanece como texto. O Hugo 0.164 deixou isso como um parágrafo:
| Header 1 | Header 2 |
| Cell A | Cell B |
Uma tabela de parâmetros
A mesma linha delimitadora carrega o alinhamento e deixa espaço para código inline:
| Parameter | Type | Default | Required |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Yes |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
