CSV para tabela Markdown: como converter um CSV para GitHub, README e documentação
Transforme um CSV em tabela Markdown para GitHub, um README ou documentação: alinhamento por coluna, barras verticais e quebras de linha seguras, e limites de tamanho.
Atualizado em 8 de novembro de 202610 min de leitura
Para transformar um CSV em tabela Markdown, solte o arquivo em um conversor de CSV para Markdown, confira a visualização renderizada, defina o alinhamento de cada coluna e copie o resultado para o seu README, a sua issue ou a sua página de documentação. O conversor escreve as três partes de que toda tabela Markdown precisa: uma linha de cabeçalho, uma linha separadora de hífens e uma linha por registro. A parte difícil não é o formato, são as células: uma barra vertical, uma quebra de linha dentro de um campo entre aspas ou um asterisco solto podem partir uma linha, empurrar dados para a coluna errada ou deixar texto em itálico. Este guia cobre os passos, o alinhamento, esses caracteres problemáticos e os limites de tamanho que importam antes de colar.
Como converter um CSV em tabela Markdown
Adicione o CSV
Abra o conversor de CSV para Markdown e solte um arquivo .csv, .tsv, .txt ou .psv. O delimitador, o caractere de aspas e a codificação são detectados a partir do próprio arquivo, e a ferramenta mostra o que escolheu.
Confira a linha de cabeçalho
Deixe Primeira linha como cabeçalho ativado quando a linha um tiver os nomes das colunas. Desative se o arquivo começa direto com dados; a tabela recebe então rótulos gerados Col 1, Col 2.
Defina o alinhamento
Escolha um Alinhamento padrão para a tabela inteira e depois mude qualquer coluna específica pelo menu suspenso no cabeçalho dela na visualização. Números costumam ficar mais legíveis alinhados à direita.
Confira a visualização dos dois jeitos
Alterne entre Renderizada e Markdown. A visualização renderizada mostra se uma célula com asterisco ou quebra de linha se comporta bem; a visualização bruta mostra exatamente o que você vai colar.
Copie ou baixe
Clique em Converter para Markdown e depois em Copiar Markdown para um README ou pull request, ou em Baixar .md com o nome de arquivo que você digitou em Baixar como.
Do que é feita uma tabela Markdown
Uma tabela Markdown no dialeto GitHub-Flavored é texto puro. A primeira linha é o cabeçalho, com as células separadas por barras verticais. A segunda linha é o separador: hífens sob cada coluna, e é a presença dela que transforma o bloco em tabela. Cada linha seguinte é um registro. GitHub, GitLab, Obsidian, VS Code e a maioria dos geradores de sites estáticos leem esse mesmo formato, então uma tabela convertida funciona em todos eles.
O formato tem limites rígidos que vale conhecer antes de começar. Não há como mesclar células entre linhas ou colunas, cada linha da tabela precisa caber em uma única linha de texto e o cabeçalho sempre aparece em negrito. Se uma linha do CSV tiver menos células que o cabeçalho, o conversor completa com células vazias; se tiver mais, a tabela é ampliada até a linha mais larga, para que nada seja cortado sem aviso.
Alinhamento de colunas em uma tabela Markdown
O alinhamento fica só na linha separadora, na forma de dois-pontos ao lado dos hífens. O conversor escreve isso para você, e pode escrever um diferente para cada coluna:
| Alinhamento | Separador escrito | Melhor para |
|---|---|---|
| Esquerda | :--- | Nomes, rótulos, texto livre |
| Centro | :---: | Colunas curtas de status, sim/não, marcas de um caractere |
| Direita | ---: | Preços, quantidades, porcentagens |
| Nenhum | --- | Deixar para o renderizador (esquerda em quase todo lugar) |
O caso comum é uma tabela que mistura o nome de um produto com um preço e um estoque: defina Esquerda como padrão e mude as duas colunas numéricas para Direita no cabeçalho delas na visualização. Números alinhados à direita se alinham pelo último dígito, e é isso que permite comparar uma coluna de valores só de olhar. Saiba que alguns aplicativos ignoram os dois-pontos; o Notion, por exemplo, transforma uma tabela Markdown colada em uma tabela própria e descarta o alinhamento.
Alinhamento por coluna, escape seguro de barras verticais e quebras de linha, saída preenchida ou compacta, cópia ou download em .md. Grátis: um CSV de até 25 MB, sem limite de linhas, com todas as opções de formatação. Pro: até 50 arquivos de uma vez em um ZIP ou em um único documento mesclado. Tudo roda no seu dispositivo, não nos nossos servidores.
Converter CSV para MarkdownBarras verticais, quebras de linha e caracteres que quebram uma tabela
O texto de uma planilha não sabe que está prestes a virar Markdown. Estes são os caracteres que dão problema e o que o conversor faz com cada um:
| Em uma célula | O que dá errado sem escape | O que o conversor faz |
|---|---|---|
| Uma barra vertical | | Ela fecha a célula antes da hora; a linha ganha uma coluna e os dados se deslocam | Sempre escapada como \| |
| Uma barra invertida | Pode engolir o caractere seguinte | Sempre duplicada, então um caminho do Windows sobrevive |
| Uma quebra de linha em um campo entre aspas | A linha termina no meio da célula e o resto da tabela desmorona | Vira <br> por padrão, ou um \n literal, ou um espaço |
| Asteriscos, sublinhados, crases | O texto vira negrito, itálico ou código | Escapados só com Escapar caracteres Markdown ativado |
| Colchetes, sinais de menor e maior, tils | Podem virar links, HTML ou texto tachado | Escapados pela mesma opção |
| Hífens, pontos, sinais de mais | Nada, dentro de uma célula de tabela | Ficam como estão, para que datas e preços continuem legíveis |
A configuração para as quebras é Quebras de linha numa célula. Mantenha <br> para GitHub e GitLab, onde ele aparece como uma quebra real e um endereço continua sendo uma única célula legível. Escolha \n literal quando a tabela for para um lugar que remove HTML e você ainda quiser ver que havia uma quebra ali. Escolha Espaço quando as quebras foram um acidente da exportação, como texto quebrado automaticamente em uma coluna da planilha.
Deixe Escapar caracteres Markdown desativado, a não ser que a visualização mostre um problema. A maioria das tabelas não tem nenhum desses caracteres, e com a opção ativada cada um ganha uma barra invertida visível no arquivo bruto. Uma célula com um valor como _rascunho_ ou uma palavra entre asteriscos é justamente o caso em que você precisa dela: sem escape, ela aparece em itálico e as marcas somem.
Primeiro, ler o CSV do jeito certo
Muitas tabelas quebradas já estão quebradas antes de qualquer Markdown ser escrito, porque o CSV foi dividido pelo caractere errado. O conversor testa vírgula, ponto e vírgula, tabulação e barra vertical em uma amostra, fica com o que dá larguras de linha mais consistentes e avisa se a leitura parecer incerta. Exportações do Excel em português costumam usar ponto e vírgula; se a visualização mostrar tudo em uma só coluna, defina o Delimitador manualmente.
- Codificação: se nomes com acento aparecem como caracteres estranhos, o arquivo provavelmente é Windows-1252 e não UTF-8. Defina manualmente; um arquivo com marca de ordem de bytes (BOM) sempre prevalece, e a marca invisível que a exportação CSV UTF-8 do Excel adiciona é removida para não grudar no seu primeiro título de coluna.
- Pular linhas iniciais: exportações de relatórios costumam ter um título e uma data acima do cabeçalho real. Pule essas linhas para que a linha um vire o cabeçalho.
- Remover linhas vazias e Remover colunas vazias: exportações de planilhas acumulam linhas em branco no fim e colunas sem uso na lateral. Cada uma viraria células vazias na sua tabela.
- Limitar linhas: um README precisa das primeiras 20 linhas de uma exportação grande, não de todas. 0 mantém todas as linhas.
Se a tabela precisa de menos colunas do que o CSV tem, tire-as antes com Adicionar ou remover colunas CSV, e veja como remover colunas de um CSV para os detalhes. Uma tabela com quatro colunas bem escolhidas é muito mais fácil de ler do que uma com doze.
Limites de tamanho: o conversor e o lugar onde você cola
No plano grátis, o conversor aceita um arquivo de até 25 MB, sem limite de linhas. O site mede uma exportação de 25 MB com cerca de 225.000 linhas sendo convertida em mais ou menos um segundo em um computador de mesa. A visualização mostra só as primeiras linhas e colunas para manter a página rápida, mas o download e o texto copiado trazem todas. O Pro converte até 50 arquivos de uma vez, em um ZIP ou mesclados em um único documento Markdown, com cada tabela sob um título tirado do nome do arquivo.
O limite mais apertado costuma ser o destino, não o conversor:
| Destino | Limite prático | O que fazer |
|---|---|---|
| Issue, pull request ou comentário no GitHub | O corpo tem limite de 65.536 caracteres | Use Limitar linhas, ou versione a tabela como arquivo .md |
| README ou arquivo de documentação em um repositório | Sem um teto pequeno, mas uma tabela muito longa é difícil de ler | Mostre uma amostra e coloque um link para o CSV completo |
| Qualquer página lida no celular | Tabelas largas rolam na horizontal | Fique em cerca de 4 a 6 colunas |
| Texto bruto em um editor | O preenchimento deixa cada linha tão larga quanto o valor mais largo | Use a saída compacta para células de texto longas |
Lembre que o Markdown fica maior que o CSV de origem: cada célula ganha barras e espaços, e o preenchimento acrescenta mais. Uma exportação completa raramente cabe bem em um documento. Vinte linhas bem escolhidas com um link para o arquivo de origem é o que a maioria dos leitores quer.
Outras opções que vale conhecer
- Numerar as linhas adiciona uma coluna de contagem, útil quando revisores precisam dizer "a linha 14 está errada" em um comentário.
- Primeira linha de dados em negrito e Primeira coluna em negrito valem só para o corpo, já que o cabeçalho já aparece em negrito.
- Caractere de aspas pode ser aspas duplas, apóstrofo ou nenhum; uma aspa só abre um campo no começo dele, então o apóstrofo de O'Brien continua sendo texto.
Quando uma tabela Markdown não é a escolha certa
Tabelas Markdown servem para dados pequenos e legíveis dentro de um texto. Se alguém precisa ordenar, filtrar ou calcular, entregue os dados como planilha com CSV para Excel. Se um programa vai ler os dados, CSV para JSON é o formato melhor. Se você só precisa examinar um arquivo grande antes de escolher as linhas, abra-o primeiro no visualizador de CSV.
Se a sua tabela está em um documento do Word e não em um CSV, o trabalho é outro: títulos, listas e formatação vêm junto. Isso está explicado em converter Word para Markdown, com a ferramenta Word para Markdown.
Perguntas frequentes
Como converto um CSV em tabela Markdown?
Solte o CSV no conversor de CSV para Markdown, deixe Primeira linha como cabeçalho ativado se a linha um tiver os nomes das colunas, defina o alinhamento, clique em Converter para Markdown e copie o resultado ou baixe como arquivo .md. A linha de cabeçalho, a linha separadora e o escape são escritos para você.
Como alinho uma coluna à direita em uma tabela Markdown?
Coloque dois-pontos na ponta direita do separador dessa coluna, escrito ---:. No conversor isso é feito pelo menu suspenso no cabeçalho da coluna na visualização, então as colunas de números podem ficar à direita enquanto o texto fica à esquerda.
Como coloco uma barra vertical dentro de uma célula de tabela Markdown?
Escape como \| para que ela não seja lida como o fim da célula. O conversor faz isso automaticamente com todas as barras verticais, inclusive dentro de texto que parece código.
Uma célula de tabela Markdown pode ter quebra de linha?
Não diretamente: cada linha da tabela precisa ser uma única linha de texto. No GitHub e no GitLab, um <br> dentro da célula aparece como quebra de linha, e esse é o padrão do conversor para campos CSV com várias linhas. Você também pode escolher um \n literal ou um simples espaço.
Por que o meu CSV inteiro aparece em uma única coluna?
O arquivo usa um delimitador diferente do que está sendo aplicado, quase sempre ponto e vírgula em exportações de versões do Excel em português ou de outros países europeus. Defina o Delimitador manualmente como Ponto e vírgula, Tabulação ou Barra vertical e as colunas se separam.
Existe limite de tamanho para converter CSV em Markdown?
O plano grátis converte um arquivo de até 25 MB, sem limite de linhas e com todas as opções de formatação. O Pro aceita até 50 arquivos de uma vez. O limite mais comum é o destino: o GitHub limita o corpo de uma issue ou pull request a 65.536 caracteres, então use Limitar linhas nas tabelas que for colar ali.