Se você precisa de uma tabela no seu README, o caminho mais rápido é colar o seu CSV em CSV para Markdown e clicar em Run. Ele gera uma tabela compatível com GFM que você pode copiar direto para o seu README, tudo dentro do navegador.
Este artigo cobre quando faz sentido usar tabelas no README, como gerá-las a partir de CSV ou JSON e o que ficar de olho no GitHub Flavored Markdown.
Quando um README precisa de uma tabela
Texto puro funciona até a informação crescer. Os seguintes tipos de conteúdo ficam muito mais legíveis como tabelas:
- Listas de endpoints de API (caminho, método, descrição)
- Versões suportadas ou matrizes de compatibilidade de plataforma
- Comparações de recursos (seu projeto vs. alternativas, ou gratuito vs. pago)
- Referências de opções de CLI
- Listas de variáveis de ambiente com valores padrão
Listas com marcadores se esticam verticalmente e dificultam a comparação entre colunas. Uma tabela permite que o leitor percorra os dados na horizontal e perceba as diferenças na hora.
Exemplos reais de tabelas em README
As cinco categorias acima são abstratas. Veja como elas realmente ficam como tabelas Markdown que você pode colocar em um README hoje mesmo.
Referência de opções de CLI — toda ferramenta de CLI acaba ganhando uma lista de flags. Uma tabela vence uma parede de texto de --help:
| Flag | Default | Description |
| :--- | :--- | :--- |
| `--port` | `3000` | HTTP port to listen on |
| `--host` | `0.0.0.0` | Bind address |
| `--log-level` | `info` | One of `debug`, `info`, `warn`, `error` |
Matriz de compatibilidade de versões — suporte a runtime é o motivo mais comum para consultar um README:
| Runtime | Minimum | Tested up to | Status |
| :--- | ---: | ---: | :--- |
| Node.js | 18.x | 22.x | LTS supported |
| Bun | 1.0 | 1.1 | Best effort |
| Deno | 1.40 | 2.0 | Community |
Comparação de recursos com alternativas — usada em toda seção "por que esta biblioteca":
| Feature | This project | Alternative A | Alternative B |
| :--- | :---: | :---: | :---: |
| Zero dependencies | ✅ | ❌ | ✅ |
| TypeScript types | ✅ | ✅ | ❌ |
| Browser-side | ✅ | ❌ | ❌ |
Cada uma delas é pequena de propósito (3–4 linhas, 3–4 colunas): o GitHub as renderiza sem rolagem horizontal no celular, e elas continuam legíveis conforme o README cresce.
Conceitos básicos de tabelas Markdown
Tabelas GFM usam o caractere de barra vertical como separador de colunas:
| Command | Description |
| --- | --- |
| install | Install dependencies |
| build | Build for production |
| test | Run the test suite |
A primeira linha é o cabeçalho, a segunda é o separador e toda linha depois disso são dados. Adicione : ao separador para controlar o alinhamento (:--- à esquerda, :---: ao centro, ---: à direita).
Para um mergulho mais profundo na sintaxe, veja Sintaxe de tabelas Markdown.
Gere uma tabela de README a partir de CSV
Quando seus dados estão em uma planilha ou em um arquivo CSV, use CSV para Markdown:
- Abra CSV para Markdown
- Cole seu CSV no editor da esquerda (copiar e colar do Excel ou do Google Sheets também funciona)
- Pressione Run
- Copie a tabela Markdown do painel da direita para o seu README
Tudo roda no navegador — nenhum dado sai da sua máquina. Para mais detalhes sobre casos extremos e escape de caracteres, veja Como converter CSV em uma tabela Markdown.
Não sabe se os dados deveriam estar em JSON, YAML, CSV ou Markdown? O cheatsheet de comparação de formatos de dados resume quando usar cada formato.
Crie uma tabela a partir de dados JSON
Às vezes seus dados começam como JSON — uma resposta de API, um dump de configuração, um trecho de log. O caminho mais confiável até uma tabela Markdown é passar primeiro pelo CSV.
Para um passo a passo mais detalhado cobrindo arrays, objetos aninhados e respostas de API, veja Como converter JSON em uma tabela Markdown.
Passos
- Formate o JSON com o Formatador de JSON para verificar sua estrutura
- Converta o array JSON em CSV (as chaves dos objetos viram cabeçalhos de coluna e os valores viram células das linhas)
- Cole o CSV em CSV para Markdown para gerar a tabela
Por exemplo, dado este JSON:
[
{ "name": "Node.js", "version": "20.x", "status": "LTS" },
{ "name": "Node.js", "version": "22.x", "status": "Current" }
]
O equivalente em CSV é:
name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current
Cole isso em CSV para Markdown e a tabela estará pronta para o seu README.
Erros comuns em tabelas de README
A maioria das tabelas de README "quebradas" se resume a quatro erros. Saber qual deles te atingiu evita uma longa investigação pelo código-fonte Markdown. Vale esclarecer uma coisa antes da lista: a especificação GFM, seção 4.10Abre em uma nova aba descreve a linha delimitadora como células "cujo único conteúdo são hífens (-) e, opcionalmente, dois-pontos (:) no início ou no fim". Ela não define um número mínimo de hífens nem exige uma linha em branco antes da tabela.
Número de colunas inconsistente
A linha delimitadora fixa a quantidade de colunas. Qualquer linha com mais células tem as células extras descartadas silenciosamente; qualquer linha com menos células recebe células vazias no final.
| name | role |
| --- | --- |
| Alice | Engineer | LA ← célula extra, descartada silenciosamente
| Bob ← célula faltando, renderizada em branco
O GitHub não avisa sobre isso. Se a coluna da direita da sua tabela está misteriosamente vazia, conte os pipes na linha problemática.
Linha delimitadora ausente ou malformada
A linha delimitadora é o que transforma o bloco em tabela, então errar nela produz a falha do tipo "não há tabela nenhuma". O que importa é a contagem de colunas, não a quantidade de hífens.
| name | role |
| --- | ← uma célula delimitadora para duas colunas de cabeçalho: nenhum parser gera tabela
| Alice | Engineer |
Passei esse caso por quatro parsers (scripts/benchmarks/markdown-table-parsers/ no repositório, medido em 2026-07-15 com a API de Markdown do GitHub, marked 18.0.5, remark-gfm 4.0.1 e CommonMark estrito via remark-parse). Uma divergência na contagem de colunas não produziu tabela em nenhum dos quatro.
A quantidade de hífens é outra história. Na mesma medição, tanto | - | - | quanto | -- | -- | foram renderizados como tabelas na API do GitHub, no marked e no remark-gfm. Três hífens é uma convenção de legibilidade, não um requisito: a própria documentação do GitHub diz três ou mais, a especificação não diz nada e as implementações aceitam um. Por isso, quando uma tabela se recusa a renderizar, contar hífens é o ponto de partida errado. O mesmo mito é tratado em detalhe em Por que sua tabela Markdown quebra.
Há um caso em que uma linha delimitadora curta realmente incomoda: se você omitir os pipes externos e usar um único hífen, o GitHub interpreta o bloco como uma lista.
h1 | h2
- | - ← aqui o GitHub renderiza uma lista; `--- | ---` renderiza uma tabela
a | b
Se uma tabela se recusa a renderizar no GitHub mas funciona no seu editor, verifique primeiro a contagem de colunas da linha delimitadora e depois se os pipes externos estão presentes.
Células vazias no GitHub vs editores
O GFM permite células realmente vazias:
| feature | basic | pro |
| :--- | :---: | :---: |
| Export PDF | | ✅ |
| API access | | ✅ |
O GitHub renderiza as células vazias corretamente. Alguns editores colapsam a linha visualmente porque interpretam pipes consecutivos como um erro de sintaxe. O código-fonte Markdown está correto — a pré-visualização do editor é que está errada. Renderize no GitHub para confirmar.
O caractere pipe | literal dentro de uma célula
Um caractere pipe dentro de uma célula encerra a coluna. Escape-o com uma contrabarra, ou use a entidade HTML |:
| condition | meaning |
| --- | --- |
| `a \| b` | bitwise or |
| `a | b` | same, via entity |
Ambos são renderizados como a | b no GitHub. A contrabarra é a forma padrão do GFM; a entidade HTML é uma alternativa mais segura se o seu README for processado por um toolchain que não seja GFM (Hugo, MkDocs).
Se a sua tabela renderiza corretamente quando você a cola no GitHub mas parece quebrada no seu editor local, o editor geralmente é o problema — a pré-visualização em github.com é a fonte da verdade para qualquer tabela de README.
Particularidades das tabelas GFM no GitHub
O renderizador de Markdown do GitHub se comporta de forma diferente dos editores de Markdown de uso geral em alguns aspectos.
Quebras de linha em células com <br>
A especificação de tabelas GFM não permite quebras de linha literais dentro das células. Uma célula com múltiplas linhas escrita assim é achatada em uma única linha:
| step | description |
| --- | --- |
| 1 | install dependencies
then build |
Use <br> em vez disso — o GitHub o renderiza como uma quebra de linha dentro da célula:
| step | description |
| --- | --- |
| 1 | install dependencies<br>then build |
| 2 | run tests<br>commit the lockfile |
<br> é uma das poucas tags HTML que sobrevivem ao sanitizador de Markdown do GitHub dentro de tabelas (veja a próxima seção). A maioria dos editores pré-visualiza isso corretamente, mas se o seu não fizer, cole o README em um GitHub Gist para verificar a renderização real.
Formatação dentro das células: ênfase, código, links, selos
O Markdown inline funciona dentro das células, e é isso que torna as tabelas de README úteis como painéis de status e quadros comparativos. Ênfase, código inline, links, imagens e emoji são todos renderizados:
| Package | Status | Docs |
| --- | --- | --- |
| `core` |  | [Read](./docs/core.md) |
| `cli` | :warning: experimental | [Read](./docs/cli.md) |
Duas coisas não funcionam. Elementos de bloco (títulos, listas, blocos de código cercados) não podem ser aninhados em uma célula: um # no início de uma célula continua sendo um # literal. E qualquer | dentro de uma URL do shields.io ou de um link de imagem divide a célula, então strings de consulta como ?label=a|b precisam do pipe escapado como \| ou codificado como %7C. É a mesma regra de escape da seção "O caractere pipe | literal dentro de uma célula" acima, mas é fácil deixar passar quando o pipe está enterrado em uma URL em vez de no texto.
Se você gera a tabela a partir de CSV ou JSON, mantenha o Markdown do selo na célula de origem: o CSV to Markdown o repassa sem alterações, então a coluna de selos sobrevive a cada regeneração.
HTML limitado dentro das tabelas
O GitHub remove a maior parte do HTML inline por segurança. <br> funciona para quebras de linha dentro da célula, mas <span style="..."> e estilos inline semelhantes são ignorados. Não conte com mudanças de cor ou de tamanho de fonte dentro das células da tabela.
Alinhamento de colunas
A sintaxe de alinhamento com : na linha separadora funciona como esperado no GitHub. Alinhar colunas numéricas à direita facilita a leitura de números de versão e preços.
| Plan | Monthly |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |
Tabelas largas e rolagem horizontal
Tabelas com muitas colunas disparam rolagem horizontal no GitHub. Se os leitores vão ver o README tanto no desktop quanto no celular, mantenha as tabelas com cinco ou seis colunas, ou divida-as em tabelas separadas.
Perguntas frequentes
Posso gerenciar as tabelas do README em uma planilha?
Sim. Mantenha os dados de origem em uma planilha, exporte o CSV sempre que o conteúdo mudar e passe-o por CSV para Markdown para regerar a tabela. Cole o resultado no README e faça o commit.
Posso colocar links dentro das células da tabela?
Sim. A sintaxe padrão de links do Markdown [texto](url) funciona dentro das células de tabelas GFM e é renderizada como links clicáveis no GitHub.
Como adiciono quebras de linha dentro de uma célula?
Use a tag HTML <br> dentro da célula. Consulte a seção "Quebras de linha em células com <br>" acima para exemplos e limitações.
Conclusão
Tabelas tornam o conteúdo do README fácil de percorrer. Escrever as barras verticais à mão tudo bem para algumas poucas linhas, mas qualquer coisa maior pede automação. O CSV para Markdown gera a tabela a partir do CSV colado em segundos, para que você possa investir seu tempo no conteúdo em vez de na formatação.