Gerador de Tabelas Markdown

Gerador de Tabelas Markdown

Tabelas GFM (GitHub Flavored Markdown) usam caracteres de pipe para separar colunas, uma linha separadora com traços para definir o cabeçalho e dois pontos opcionais na linha separadora para controlar o alinhamento. O formato é suportado por GitHub, GitLab, muitos geradores de sites estáticos é a maioria dos editores Markdown.

Sintaxe de Tabelas GFM

A tabela mínima válida exige uma linha de cabeçalho, uma linha separadora e pelo menos uma linha de dados:

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

A linha separadora deve conter pelo menos três traços (---) por célula. Mais traços não importam; não mudam o comportamento, só afetam a legibilidade no código fonte.

Alinhamento de Colunas

O alinhamento é definido com dois pontos na linha separadora:

| Left | Center | Right |
|:-----|:------:|------:|
| text | text | text |

O alinhamento à direita é mais útil para colunas numéricas onde você quer alinhar os dígitos.

Formatação de Pipes no Código Fonte

Os pipes no início e final de cada linha são opcionais na especificação, mas a maioria dos formatadores e linters os exige. Você não precisa preencher as células para alinhar visualmente os pipes. Estas duas tabelas são renderizadas igual:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Short | A much longer cell value | x |

|Column 1|Column 2|Column 3|
|---|---|---|
|Short|A much longer cell value|x|

Prettier e formatadores similares preencherão a versão curta para a versão alinhada ao salvar.

O Que Tabelas Markdown Não Podem Fazer

Sem células mescladas

Cada linha deve ter exatamente o mesmo número de células. Não há equivalente a colspan ou rowspan. Se uma célula está conceitualmente vazia, use um espaço ou deixe em branco: | |.

Sem tabelas aninhadas

Uma célula de tabela não pode conter outra tabela. Células também não podem conter elementos de bloco como code fences, blockquotes ou listas. Formatação inline (negrito, código, links) funciona dentro de células.

Sem células multilinha

Uma célula não pode abranger várias linhas no código fonte. Se você precisa colocar muito texto em uma célula, a tabela ficará difícil de ler. A solução alternativa é manter células curtas ou mudar para uma estrutura de conteúdo diferente.

Tabelas HTML como Alternativa

Quando tabelas GFM não são flexíveis o suficiente, HTML bruto funciona dentro da maioria dos documentos Markdown:

<table>
  <tr>
    <th colspan="2">Merged header</th>
  </tr>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
  </tr>
</table>

Isso funciona no GitHub e na maioria dos geradores de sites estáticos. Não funciona em ambientes que removem HTML por razões de segurança (alguns wikis, algumas ferramentas de visualização Markdown).

Gerando Tabelas a Partir de Dados

Se você tem dados estruturados e precisa convertê-los para Markdown, algumas abordagens funcionam bem:

import pandas as pd

df = pd.read_csv("data.csv")
print(df.to_markdown(index=False))

// Node.js: TSV básico para tabela Markdown
const rows = tsvString.trim().split("\n").map(r => r.split("\t"));
const header = `| ${rows[0].join(" | ")} |`;
const sep = `| ${rows[0].map(() => "---").join(" | ")} |`;
const body = rows.slice(1).map(r => `| ${r.join(" | ")} |`).join("\n");
console.log([header, sep, body].join("\n"));

Mantendo Tabelas Fonte Legíveis

Para tabelas que você edita manualmente no código fonte, alguns hábitos ajudam. Mantenha o conteúdo das colunas curto (menos de 20 caracteres se possível). Use um formatador Markdown (Prettier com a opção prose-wrap) para que o alinhamento seja tratado automaticamente. Para tabelas que serão lidas principalmente na forma renderizada e raramente editadas, o alinhamento no código fonte importa menos.

Se você usa VS Code, a extensão Markdown Table pode auto-formatar tabelas ao salvar e permite navegar entre células com Tab da mesma forma que em uma planilha.