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.
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.
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.
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.
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?
A especificação de tabelas GFM não suporta quebras de linha literais dentro das células. Use uma tag <br> — o GitHub a renderiza como uma quebra de linha dentro da célula.
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.