CSV para Markdown

O que é a conversão de CSV para Markdown?

Converter CSV para uma tabela Markdown é uma tarefa comum no dia a dia do desenvolvedor. CSV (Comma-Separated Values) armazena dados tabulares como texto simples, com cada linha em sua própria linha e campos separados por um delimitador como vírgula ou tabulação. É o formato de exportação padrão de planilhas, clientes SQL e ferramentas de análise. Arquivos CSV são compactos e fáceis de gerar, mas não têm nenhuma maneira nativa de controlar como os dados são exibidos. Um arquivo CSV aberto em um editor de texto é uma parede de strings delimitadas por vírgulas — legível por máquinas, mas difícil para humanos percorrerem.

As tabelas Markdown resolvem esse problema de legibilidade. Elas são definidas pela especificação GitHub Flavored Markdown (GFM) e suportadas por GitHub, GitLab, Bitbucket, Notion, Obsidian e geradores de sites estáticos como Hugo e Jekyll — em qualquer lugar onde Markdown é processado, elas são renderizadas como tabelas HTML limpas. A sintaxe usa caracteres pipe para separar colunas e uma linha separadora obrigatória de traços entre o cabeçalho e as linhas de dados.

Converter CSV para uma tabela Markdown significa envolver cada linha na sintaxe delimitada por pipe e inserir a linha separadora após o cabeçalho. A primeira linha do CSV se torna o cabeçalho da tabela, e cada linha seguinte se torna uma linha de dados. Você precisa disso sempre que for colar dados estruturados em um README, na descrição de um pull request, em uma página de wiki ou em qualquer sistema de documentação Markdown.

Por que usar esta ferramenta?

Este conversor analisa seu CSV no navegador, gera a saída em tabela Markdown instantaneamente e nunca transmite seus dados para um servidor.

Casos de uso de CSV para Markdown

Referência de Sintaxe de Tabelas Markdown

As tabelas Markdown seguem a especificação GitHub Flavored Markdown (GFM). Toda tabela requer uma linha de cabeçalho, uma linha separadora e uma ou mais linhas de dados. A linha separadora controla o alinhamento das colunas.

CSV vs Tabela Markdown

Ambos os formatos representam dados tabulares como texto simples. CSV é para máquinas e pipelines de dados; tabelas Markdown são para humanos que leem documentação.

Exemplos de Código

Os exemplos a seguir mostram como converter CSV para uma tabela Markdown programaticamente em diferentes linguagens. Cada um produz uma tabela GFM válida.

const csv = `name,age,city
Alice,30,Berlin
Bob,25,Tokyo`

const [headerLine, ...rows] = csv.trim().split('\n')
const headers = headerLine.split(',')

const separator = '| ' + headers.map(() => '---').join(' | ') + ' |'
const headerRow = '| ' + headers.join(' | ') + ' |'
const bodyRows = rows.map(row =>
  '| ' + row.split(',').join(' | ') + ' |'
)

const markdown = [headerRow, separator, ...bodyRows].join('\n')
// → | name | age | city |
// → | --- | --- | --- |
// → | Alice | 30 | Berlin |
// → | Bob | 25 | Tokyo |

import csv
import io

csv_string = """name,age,city
Alice,30,Berlin
Bob,25,Tokyo"""

reader = csv.reader(io.StringIO(csv_string))
rows = list(reader)
headers = rows[0]

lines = []
lines.append('| ' + ' | '.join(headers) + ' |')
lines.append('| ' + ' | '.join('---' for _ in headers) + ' |')
for row in rows[1:]:
    lines.append('| ' + ' | '.join(row) + ' |')

print('\n'.join(lines))
# → | name | age | city |
# → | --- | --- | --- |
# → | Alice | 30 | Berlin |
# → | Bob | 25 | Tokyo |

# With pandas (one-liner)
import pandas as pd
df = pd.read_csv(io.StringIO(csv_string))
print(df.to_markdown(index=False))

package main

import (
	"encoding/csv"
	"fmt"
	"strings"
)

func main() {
	input := "name,age,city\nAlice,30,Berlin\nBob,25,Tokyo"
	r := csv.NewReader(strings.NewReader(input))
	records, _ := r.ReadAll()

	headers := records[0]
	var lines []string

	lines = append(lines, "| "+strings.Join(headers, " | ")+" |")
	sep := make([]string, len(headers))
	for i := range sep {
		sep[i] = "---"
	}
	lines = append(lines, "| "+strings.Join(sep, " | ")+" |")

	for _, row := range records[1:] {
		lines = append(lines, "| "+strings.Join(row, " | ")+" |")
	}

	fmt.Println(strings.Join(lines, "\n"))
	// → | name | age | city |
	// → | --- | --- | --- |
	// → | Alice | 30 | Berlin |
	// → | Bob | 25 | Tokyo |
}

# Using Miller (mlr) — convert CSV to Markdown table
mlr --icsv --omarkdown cat data.csv
# → | name | age | city |
# → | --- | --- | --- |
# → | Alice | 30 | Berlin |

# Using csvtomd (pip install csvtomd)
csvtomd data.csv

# Using pandas in a one-liner
python3 -c "
import pandas as pd, sys
print(pd.read_csv(sys.argv[1]).to_markdown(index=False))
" data.csv

Perguntas Frequentes