Como fazer uma tabela em Markdown:sintaxe, alinhamento e células com várias linhas.

A sintaxe básica de uma tabela em Markdown

As tabelas fazem parte do GitHub Flavored Markdown (GFM), o dialeto usado pelo GitHub, pelo GitLab e pela maioria das aplicações Markdown. Uma tabela precisa de três coisas:

1. Uma linha de cabeçalho

   Os nomes das colunas, separados por barras verticais: | Nome | Função |.

2. Uma linha delimitadora

   Uma linha de traços, um grupo por coluna, mesmo debaixo do cabeçalho: | --- | --- |. Tem de ter tantas células como o cabeçalho, ou o texto fica como texto simples e não aparece nenhuma tabela.

3. As linhas

   Uma linha por cada linha da tabela, com as células separadas por barras verticais. Uma linha com poucas células é completada com células vazias; as células a mais são descartadas. A tabela termina na primeira linha em branco.

| Name  | Role     |
| ----- | -------- |
| Alice | Designer |
| Bob   | Engineer |

Eis o que o leitor vê:

As barras verticais no início e no fim de cada linha são opcionais, mas tornam a tabela mais fácil de ler. As colunas não têm de ficar alinhadas no texto; o preenchimento acima serve só para as pessoas. As células podem conter negrito, itálico, código, ligações e imagens.

Alinhamento numa tabela em Markdown

Ponha dois pontos à esquerda, à direita ou em ambas as pontas dos traços de uma coluna:

| Item   | Qty | Price |
|:-------|:---:|------:|
| Pencil |  12 |  $1.50 |
| Ruler  |   3 |  $4.00 |

O alinhamento aplica-se a toda a coluna, cabeçalho incluído. Define-se uma vez, na linha delimitadora, e não célula a célula. Alinhe os números à direita para que os algarismos fiquem em coluna.

Uma barra vertical ou uma segunda linha numa célula

Uma barra vertical fecha uma célula, por isso uma barra que faça parte do texto precisa de uma barra invertida. O GFM aplica isto até dentro do código em linha:

| Command            | Meaning          |
|--------------------|------------------|
| `a \| b`           | a pipe, in code  |
| Either \| or       | a pipe, in text  |

Uma tabela com barras tem uma linha de texto por cada linha da tabela, pelo que uma célula não pode ter uma quebra de linha verdadeira nem um segundo parágrafo. A solução habitual é a etiqueta HTML <br>:

| Step  | What to do                          |
|-------|-------------------------------------|
| Build | Run the build.<br>Fix any errors.  |
| Ship  | Tag the release.<br>Push the tag.  |

O mesmo truque dá uma célula com várias linhas no GitHub e na maioria das outras aplicações que aceitam HTML. Uma lista Markdown não funciona dentro de uma célula; se uma célula precisar de uma lista, escreva <br> entre itens curtos ou tire a lista da tabela.

Tabelas largas e textos longos

O Markdown não tem uma definição para a largura das colunas nem forma de unir células; é a aplicação que mostra a tabela que decide como ela se ajusta. Alguns hábitos mantêm a tabela legível em qualquer lado:

• Mantenha as células curtas, uma palavra ou um número. Ponha a explicação longa numa frase debaixo da tabela.
• Use menos colunas. Se uma tabela tem oito, rode-a: as colunas passam a ser os itens e as linhas as propriedades.
• Não preencha o texto com espaços para alinhar as colunas de uma tabela que edita muitas vezes; uma célula alterada obrigaria a reespaçar todas as linhas.
• Para células unidas, linhas expandidas ou uma legenda, escreva a tabela em HTML. A maioria das aplicações Markdown mostra um simples <table>.

Porque é que uma tabela em Markdown não aparece

• Falta a linha delimitadora. É a linha de traços que faz do texto uma tabela.
• O número de células difere. Se o cabeçalho tiver três células e a linha delimitadora duas, não aparece nada.
• Uma barra vertical sem escape numa célula divide-a em duas. Escreva \|.
• Uma linha em branco dentro da tabela. A tabela acaba aí; o resto é texto simples.
• A aplicação não tem tabelas. As tabelas não existem no Markdown original nem no núcleo do CommonMark. Vêm do GFM, por isso um analisador mínimo mostra as barras como texto.

Para ver o resultado antes de fazer commit, abra o ficheiro num leitor de Markdown. O DotMD mostra as tabelas formatadas e é gratuito para ler. No DotMD Editor, Insert → Table põe no ficheiro uma tabela de três colunas pronta, e a pré-visualização em direto redesenha-a à medida que escreve.

Perguntas sobre tabelas em Markdown

Mais perguntas