Como Converter CSV em Tabela Markdown

Você quer inserir uma tabela comparativa em um README do GitHub. Precisa compartilhar números de benchmark na descrição de um pull request. Está migrando anotações de uma planilha para o Notion ou o Obsidian. Em todos esses casos, a peça que falta é a mesma: transformar dados em formato CSV em uma tabela Markdown limpa.

Colar uma planilha diretamente no GitHub não vai gerar uma tabela Markdown, e escrever as barras verticais na mão deixa de ser prático depois de algumas poucas linhas. Este guia cobre a estrutura das tabelas Markdown, as armadilhas que costumam pegar as pessoas e como fazer a conversão no navegador sem nenhuma configuração.

Quer a tabela agora mesmo? Cole o seu CSV na ferramenta CSV to Markdown e clique em Run: você recebe de volta uma tabela compatível com o GitHub. Se preferir entender antes a sintaxe e os casos extremos, continue lendo.

O que a conversão realmente faz

Comece pelo lado do CSV, porque é isso que você vai colar:

name,email,role
Mika,mika@example.com,admin
Noah,noah@example.com,viewer

Passar isso pelo conversor gera isto:

| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

A linha de cabeçalho vira a linha de cabeçalho da tabela, uma linha separadora é inserida logo abaixo, e cada linha restante vira uma linha de dados com barras verticais ao redor e entre os campos. Essa é toda a transformação — o resto deste artigo trata dos casos em que a entrada não está tão arrumada assim.

Como é uma tabela Markdown

As tabelas do GitHub Flavored Markdown (GFM) usam o caractere de barra vertical (pipe) como separador de colunas:

| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

A primeira linha é o cabeçalho, a segunda é o separador de alinhamento e tudo abaixo são os dados. Adicionar : ao separador controla o alinhamento daquela coluna.

| Left | Center | Right |
| :--- | :---: | ---: |
| a | b | c |

A sintaxe é simples, mas digitá-la na mão deixa de escalar rápido. Uma tabela de 20 linhas e 5 colunas exige manter todas as barras verticais alinhadas enquanto você digita, o que não é como ninguém quer gastar o tempo.

Por que a conversão manual vira um sofrimento

Algumas linhas tudo bem. No trabalho real o atrito aparece de imediato:

• A quantidade de linhas cresce — tabelas comparativas em um README costumam passar de 30 linhas
• Células que contêm o caractere de barra vertical | precisam ser escapadas
• Células que contêm quebras de linha simplesmente não cabem em uma tabela Markdown
• CSVs com contagem inconsistente de colunas produzem tabelas quebradas

CSVs exportados do Excel são especialmente divertidos: separadores de milhar nos números podem colidir com os delimitadores de coluna, e quebras de linha no estilo Windows às vezes quebram parsers ingênuos.

Comparando as opções

Há mais de uma forma de transformar CSV em uma tabela Markdown. A que faz mais sentido depende do seu ambiente e de quanto dado você lida.

Um CLI se encaixa bem em um pipeline, mas exige instalação e um runtime. Escrever na mão é tranquilo para poucas linhas, mas para de funcionar bem conforme a contagem cresce. Uma ferramenta no navegador não exige configuração, nunca envia o que você cola e escapa as barras verticais para você.

Converta com o FormatArc

O CSV to Markdown recebe o CSV colado e produz uma tabela compatível com GFM. Não há nada para instalar.

Passo 1: Abra a ferramenta

Acesse o CSV to Markdown.

Passo 2: Cole o seu CSV

Cole o CSV no painel da esquerda. Uma cópia do Excel, do Google Sheets ou de um arquivo de texto simples funcionam todas da mesma forma. A primeira linha é tratada como o cabeçalho.

Passo 3: Clique em Run

Pressione Run. O painel da direita é preenchido com a tabela Markdown.

A saída está pronta para colar direto em um README, uma issue ou um documento Markdown. A contagem de colunas e a largura dos separadores são normalizadas para você.

Tudo roda no navegador. Listas de clientes ou planilhas internas nunca são enviadas para um servidor. Para CSVs sensíveis, isso é mais seguro do que um conversor online baseado em upload (veja os conversores online são seguros?).

Casos extremos que vale conhecer

Barras verticais dentro das células

Se uma célula contém |, o conversor a escapa como \| automaticamente para que não colida com o separador de coluna.

| x | y |
| --- | --- |
| foo\|bar | baz |

Se, mesmo assim, a tabela sair quebrada depois de colar em outro lugar, veja o que fazer quando uma tabela Markdown não renderiza.

Quebras de linha dentro das células

A especificação de tabelas Markdown não tem representação para quebras de linha dentro das células. O FormatArc as substitui por espaços. Se você precisa de uma quebra de linha visível dentro de uma célula, use uma tag <br> explícita nos seus dados de origem.

Linhas irregulares

Se uma linha de dados for mais larga que o cabeçalho, as colunas extras são descartadas. Se uma linha de dados for mais curta, as células que faltam são preenchidas com strings vazias. De qualquer forma, a saída continua sendo uma tabela válida.

Campos entre aspas

Um campo CSV entre aspas duplas pode conter o próprio delimitador, então "Tokyo, Japan" é uma única célula, não duas. As aspas fazem parte da sintaxe do CSV, não dos dados, e não aparecem na saída Markdown:

name,location,note
Mika,"Tokyo, Japan","said ""ok"" twice"

| name | location | note |
| --- | --- | --- |
| Mika | Tokyo, Japan | said "ok" twice |

Uma aspa duplicada dentro de um campo entre aspas ("") é o escape do CSV para uma aspa literal ", por isso a coluna note sai com aspas simples normais. Se a sua tabela mostrar aspas soltas ou um valor dividido em duas colunas, geralmente o CSV de origem está com a citação incorreta, e não o conversor lidando mal com isso.

Para onde vai a tabela convertida

READMEs do GitHub

Listas de endpoints de API, opções suportadas, comparações de bibliotecas — tabelas em README aparecem o tempo todo. Manter a origem como CSV significa que a tabela pode ser regerada sempre que os dados subjacentes mudarem.

Pull requests e issues

Números de benchmark, matrizes de testes de regressão e resumos de decisões de design ficam todos mais legíveis como tabelas. Agregue os dados em uma planilha, passe pelo conversor e cole.

Notion, Obsidian, Zenn, Qiita

A maioria das ferramentas de anotação e de publicação para desenvolvedores fala Markdown. Armazenar os dados como CSV e converter sob demanda elimina a necessidade de reformatar as tabelas toda vez que você muda de plataforma.

Contexto para LLMs

Alimentar uma tabela para o ChatGPT, o Claude ou o Gemini funciona melhor como Markdown do que como HTML bruto: usa menos tokens e é extraída com mais precisão. Veja Markdown vs HTML para LLMs para números medidos de custo em tokens e precisão de extração de tabelas.

Compatibilidade de renderizadores para alinhamento

A sintaxe de alinhamento GFM (:---, :---:, ---:) tem bom suporte em plataformas para desenvolvedores, mas às vezes é ignorada silenciosamente ou funciona só parcialmente em ferramentas de publicação voltadas ao público geral. Use esta tabela quando suspeitar que uma tabela está sendo renderizada com o alinhamento errado em algum ponto adiante. As linhas marcadas como "documentado" seguem a especificação ou a documentação publicada pela própria plataforma; as linhas marcadas como "reportado" refletem um comportamento amplamente relatado por usuários que não testamos de forma independente — trate-as como ponto de partida e verifique com uma tabela de exemplo de duas linhas na sua plataforma de destino antes de confiar nelas.

Se você precisa mesclar células ou um layout mais complexo, use HTML puro dentro do Markdown — a maioria dos renderizadores aceita um bloco <table> como está.

Quando o CSV vem do Excel: separador ; e decimais com vírgula

Se você salva uma planilha do Excel como arquivo .csv, o separador de lista usado por padrão nem sempre é a vírgula. Ele depende da configuração regional do Windows: ao salvar uma planilha como CSV, o Excel usa o separador de lista definido na configuração regional, e esse separador pode ser trocado na configuração regional do Windows (documentação da Microsoft, importar ou exportar arquivos de textoAbre em uma nova aba). A própria Microsoft indica que, quando o símbolo decimal da configuração regional é a vírgula, o Excel usa o ponto e vírgula como separador de lista ao exportar.

Isso quer dizer que um CSV exportado de uma máquina com configuração regional brasileira pode chegar com ; como separador em vez de ,. O CSV to Markdown detecta automaticamente entre ,, ;, \t e |, então colar o arquivo assim como está costuma funcionar sem que você precise mudar nada.

O que não muda é a vírgula decimal em si. Medimos o mesmo analisador que a ferramenta usa com o formato numérico padrão de oito configurações regionais, em 2, 3 e 4 colunas (medição reproduzível em scripts/benchmarks/spreadsheet-paste-delimiter/): de 48 casos, falharam apenas os 9 que combinam separador de milhar por vírgula com números grandes, e a vírgula decimal sozinha não alterou a detecção em nenhuma configuração regional. Esse é um cenário diferente de colar diretamente da área de transferência do Excel — para esse caso (TSV com separador de milhar deslocando colunas), veja Excel ou Google Sheets para uma tabela Markdown.

Perguntas frequentes

Posso colar uma coluna do Excel diretamente sem salvar como CSV?

Sim. Quando você copia um intervalo do Excel ou do Google Sheets, o que chega na área de transferência é texto separado por tabulação (TSV), não CSV. O CSV to Markdown detecta automaticamente o delimitador de tabulação, então colar e rodar funciona do mesmo jeito. Veja Excel ou Google Sheets para uma tabela Markdown para o caminho completo.

O FormatArc envia meu CSV para um servidor?

Não. A conversão roda inteiramente como JavaScript na aba do seu navegador. Nada é enviado para o FormatArc ou para qualquer servidor de terceiros. Se o seu CSV contém dados de clientes, números financeiros ou conteúdo coberto por NDA, a conversão baseada em colar é a única opção segura, fora rodar um script local. Veja os conversores JSON online são seguros? para a comparação de privacidade completa entre tipos de ferramentas.

Por que minha tabela renderiza no GitHub mas quebra em outro lugar?

Provavelmente um renderizador que não suporta o alinhamento GFM ou a sintaxe de tabelas com barras (o Notion descarta o alinhamento silenciosamente; alguns renderizadores Markdown de CMS esperam CommonMark e ignoram completamente as tabelas com barras). Veja a tabela acima, ou converta para HTML com Markdown to HTML para plataformas que não lidam com tabelas de barras.

Como eu escapo um | dentro de uma célula?

Use \| (barra invertida + barra vertical). O conversor do FormatArc faz isso automaticamente para CSV colado que contém caracteres de barra vertical. Veja tabela Markdown não renderiza se a sua tabela sair quebrada depois de copiar e colar.

Qual é o tamanho máximo que posso colar?

Não há um limite rígido além do que a aba do navegador consegue manter em memória. Medimos o mesmo código de conversão que roda na ferramenta (scripts/benchmarks/csv-to-markdown-throughput/, medido em 2026-07-13 em um Apple M5 Pro, Node, mediana de 7 execuções aquecidas): um CSV de 10.000 linhas converte em cerca de 7 ms, 50.000 linhas em cerca de 36 ms, e 100.000 linhas (~5 MB) em cerca de 75 ms — os tempos no navegador variam por máquina, mas a conversão em si está longe de ser o gargalo. Para CSVs muito grandes (centenas de MB), rodar um script local com formatarc no npm é mais prático do que colar em uma aba.

Encerrando

Converter CSV em tabela Markdown na mão consome tempo com contagem de linhas, largura de colunas e escapes. O CSV to Markdown faz isso em três cliques. Experimente na próxima vez que se pegar montando barras verticais manualmente.

Se você precisa ajustar com mais cuidado a tabela gerada — alinhamento, barras verticais escapadas, quebras de linha ou outras especificidades do GFM — veja Tabelas em Markdown: Sintaxe, Alinhamento e Exemplos para Copiar e Colar para a referência completa. Para uma referência rápida de sintaxe, o resumo de tabelas GFM também é útil.

Para o contexto sobre o que é o CSV em si, veja O que é CSV. Para converter CSV em JSON, veja o guia de CSV para JSON. Se você quer copiar direto do Excel ou do Google Sheets sem passar por um arquivo CSV, veja Excel ou Google Sheets para uma tabela Markdown. Se os seus dados de origem estão em HTML em vez de CSV — por exemplo, uma tabela de uma página web ou uma exportação de CMS — veja o guia de HTML para Markdown. Se você precisa levar a tabela Markdown resultante adiante até HTML — para incorporar em um CMS que não fala Markdown ou em um e-mail HTML — veja o guia de Markdown para HTML. Se você prefere rodar a mesma conversão a partir da barra de ferramentas do navegador, veja o guia da Extensão FormatArc para Chrome 2026.