Guia · Markdown → HTML

De tabelas de Markdown para tabelas HTML

A tabela de barras é a parte do Markdown que mais gente já viu falhar. Aparece certa no GitHub e em outro lugar sai como um parágrafo cheio de barras.

Isto passa pela sintaxe que sobrevive à conversão, como fica o HTML do outro lado, e os três erros que transformam uma tabela de volta em texto.

Abrir o conversor

O que uma tabela precisa para ser uma tabela

Tabelas de barras não fazem parte do CommonMark. Vêm do GitHub Flavoured Markdown, o que significa que o conversor precisa optar por suportá-las — e alguns não suportam. Este suporta.

Três coisas são obrigatórias. Uma linha de cabeçalho. Uma linha de hifens embaixo dela. E pelo menos uma linha de conteúdo. Falte qualquer uma das três e você recebe parágrafos.

01Escreva a linha de cabeçalho com uma barra entre cada célula. As barras das pontas são opcionais, mas deixam muito mais fácil perceber uma tabela desalinhada.
02Escreva a linha de hifens logo abaixo, sem nenhuma linha em branco no meio. Três hifens por coluna é o mínimo seguro.
03Escreva as linhas de conteúdo. Não precisam ficar alinhadas no código: as células são separadas pelas barras, não pelas colunas.

Markdown

| Part | Qty |
| ---- | --- |
| Bolt | 12 |
| Nut  | 12 |

HTML

<table>
  <thead>
    <tr>
      <th scope="col">Part</th>
      <th scope="col">Qty</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Bolt</td>
      <td>12</td>
    </tr>
  </tbody>
</table>

O atributo scope, e por que ele está ali

As células de cabeçalho saem como <th scope="col">, não como <td> em negrito. Esse atributo é a única razão pela qual um leitor de tela consegue anunciar «Qty, 12» em vez de ler um número solto sem ideia de a que coluna ele pertence.

Não custa nada e é a diferença entre uma tabela e uma grade de números. Um layout falsificado com divs não consegue expressar isso, e esse é o argumento mais forte para nunca construir um.

Alinhamento: a linha dos dois-pontos

Os dois-pontos na linha de hifens definem o alinhamento por coluna. À esquerda alinha à esquerda, nos dois lados centraliza, à direita alinha à direita — que é o que você quer para números.

No HTML você recebe uma classe, não um estilo inline: align-left, align-center ou align-right. Estilos inline são removidos de toda saída deste site, porque um atributo style é a porta por onde entra injeção de CSS.

Isso significa que a saída em página completa já vem com o alinhamento funcionando: a folha de estilos no <head> define essas três classes. A saída em fragmento deixa isso para o seu próprio CSS, que é justamente o sentido do fragmento: três regras de uma linha e ele combina com o seu site em vez de brigar com ele.

Markdown

| Item | Cost |
| :--- | ---: |
| Bolt | 0.40 |

HTML

<th scope="col" class="align-left">Item</th>
<th scope="col" class="align-right">Cost</th>
...
<td class="align-left">Bolt</td>
<td class="align-right">0.40</td>

Quando a tabela sai como um parágrafo

Três causas, na ordem em que aparecem.

01Uma linha em branco entre o cabeçalho e a linha de hifens. Isso já divide tudo em dois parágrafos antes do analisador de tabelas chegar a ver.
02Uma barra dentro do texto de uma célula. Escape como \| ou a célula se divide em duas e a linha acaba com mais células do que o cabeçalho.
03Hifens de menos. Um hífen por coluna funciona em alguns analisadores e não em outros; três é a versão com que todos concordam.

Células com mais do que texto

Markdown inline funciona dentro das células: negrito, itálico, código inline, links. Conteúdo de bloco não — nem listas, nem parágrafos, nem blocos de código cercados. É um limite da própria sintaxe de tabelas, não deste conversor.

Uma quebra de linha dentro de uma célula precisa de um <br> literal, escrito à mão. Aqui o HTML cru dentro do Markdown é repassado em vez de escapado, então funciona, e é higienizado na saída como todo o resto.

É isso tudo o que numa tabela de barras se comporta diferente quando vira HTML. O conversor aceita Markdown colado ou um arquivo .md solto em cima, e nada sai do seu navegador.

MD → HTML