CSV na Markdown

Czym jest konwersja CSV na Markdown?

Konwersja CSV na tabelę Markdown to powszechne zadanie programistyczne. CSV (Comma-Separated Values) przechowuje dane tabelaryczne w postaci zwykłego tekstu — każdy wiersz stanowi oddzielny rekord, a pola są rozdzielone separatorem, takim jak przecinek lub tabulator. Jest to domyślny format eksportu dla arkuszy kalkulacyjnych, klientów SQL i narzędzi analitycznych. Pliki CSV są zwięzłe i łatwe do wygenerowania, ale nie mają wbudowanej kontroli nad wyglądem danych po wyświetleniu. Plik CSV otwarty w edytorze tekstu to ściana ciągów rozdzielonych przecinkami — czytelna dla maszyn, trudna do skanowania przez ludzi.

Tabele Markdown rozwiązują ten problem czytelności. Są zdefiniowane przez specyfikację GitHub Flavored Markdown (GFM) i obsługiwane przez GitHub, GitLab, Bitbucket, Notion, Obsidian oraz generatory stron statycznych, takie jak Hugo i Jekyll — wszędzie tam, gdzie Markdown jest przetwarzany, renderują się jako czyste tabele HTML. Składnia używa znaków pipe do separacji kolumn oraz obowiązkowego wiersza separatora z kresek między wierszem nagłówkowym a wierszami treści.

Konwersja CSV na tabelę Markdown polega na opakowaniu każdego wiersza w składnię rozdzielaną pipe'ami i wstawieniu wiersza separatora po nagłówku. Pierwszy wiersz CSV staje się nagłówkiem tabeli, a każdy kolejny wiersz staje się wierszem treści. Jest to niezbędne zawsze, gdy wklejasz ustrukturyzowane dane do README, opisu pull requesta, strony wiki lub dowolnego systemu dokumentacji w Markdown.

Dlaczego warto używać tego narzędzia?

Ten konwerter parsuje Twój CSV w przeglądarce, natychmiast generuje wyjście w postaci tabeli Markdown i nigdy nie przesyła danych na serwer.

Przypadki użycia konwersji CSV na Markdown

Składnia tabel Markdown — dokumentacja

Tabele Markdown są zgodne ze specyfikacją GitHub Flavored Markdown (GFM). Każda tabela wymaga wiersza nagłówkowego, wiersza separatora i co najmniej jednego wiersza treści. Wiersz separatora kontroluje wyrównanie kolumn.

CSV a tabela Markdown

Oba formaty reprezentują dane tabelaryczne w postaci zwykłego tekstu. CSV jest przeznaczony dla maszyn i potoków danych; tabele Markdown — dla ludzi czytających dokumentację.

Przykłady kodu

Poniższe przykłady pokazują, jak programowo konwertować CSV na tabelę Markdown w różnych językach. Każdy z nich generuje poprawną tabelę GFM.

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

Często zadawane pytania