CSV를 Markdown 표로 바꾸는 법

CSV를 Markdown 표로 바꿀 때는 쉼표를 |로 단순 치환하면 자주 깨집니다. CSV에는 따옴표로 감싼 쉼표, 셀 안 줄바꿈, 빈 값, 한글 인코딩 문제가 섞일 수 있기 때문입니다. GitHub README에 넣을 표라면 원본 구분자와 헤더를 확인한 뒤 Markdown 표 문법에 맞게 변환하는 것이 안전합니다.

증상

• CSV를 붙여넣었는데 README에서 표가 아니라 텍스트로 보입니다.
• 쉼표가 들어간 값 때문에 열이 밀립니다.
• 한글 CSV를 변환했더니 글자가 깨집니다.
• 셀 안의 | 또는 줄바꿈 때문에 Markdown 표가 깨집니다.

원인

CSV는 단순히 쉼표로만 나뉘는 형식처럼 보이지만, 실제로는 따옴표와 줄바꿈 규칙이 중요합니다. Markdown 표는 | 문자를 열 구분자로 사용하기 때문에 CSV 셀 안의 특수문자를 그대로 넣으면 표 구조가 깨질 수 있습니다.

바로 해결 방법

1. 원본이 CSV인지 TSV인지 확인합니다.
2. 한글이 깨져 있다면 먼저 CSV Encoding Fixer로 인코딩 문제를 확인합니다.
3. 정상 텍스트를 Markdown Table Generator에 붙여넣습니다.
4. 헤더 행과 구분자가 올바르게 잡혔는지 확인합니다.
5. 변환된 Markdown 표를 README에 붙여넣고 GitHub 미리보기로 확인합니다.

FixData 도구로 확인하기

Markdown Table Generator는 CSV/TSV 텍스트를 Markdown 표로 변환하고 복사할 수 있게 해줍니다. 직접 쉼표를 |로 바꾸는 방식보다 헤더와 행 구조를 확인하기 쉽습니다.

한글이 깨진 CSV라면 변환 전에 CSV Encoding Fixer로 UTF-8 또는 Excel 관련 문제를 먼저 해결하세요. 글자가 깨진 상태로 Markdown 표를 만들어도 원래 내용이 복구되지는 않습니다.

수동 해결 방법

기본 변환 구조 이해하기

CSV:

name,role
Alice,Admin
Bob,Editor

Markdown 표:

| name | role |
|---|---|
| Alice | Admin |
| Bob | Editor |

첫 줄은 헤더가 되고, 두 번째 줄은 Markdown 표 구분선입니다.

쉼표가 들어간 셀 확인

CSV 값에 쉼표가 들어 있으면 따옴표로 감싸야 합니다.

name,note
Alice,"Seoul, Korea"

이 값을 단순 split하면 열이 3개처럼 잘못 나뉠 수 있습니다. CSV 파서나 변환 도구를 쓰는 편이 안전합니다.

Markdown 특수문자 처리

셀 안에 |가 있으면 \|로 escape해야 합니다. 줄바꿈이 있는 긴 설명은 <br>로 바꾸거나 표 밖으로 빼는 편이 읽기 좋습니다.

예제

원본 TSV:

tool	status
CSV Fixer	ready
JSON Doctor	ready

Markdown:

| tool | status |
|---|---|
| CSV Fixer | ready |
| JSON Doctor | ready |

TSV는 쉼표가 아니라 탭으로 열이 나뉘므로 구분자를 잘못 잡으면 한 열로 들어갈 수 있습니다.

자주 하는 실수

• 쉼표를 전부 |로 바꾸면 된다고 생각합니다.
• CSV 셀 안의 쉼표와 따옴표를 고려하지 않습니다.
• 한글 깨짐을 해결하지 않은 채 Markdown 표로 변환합니다.
• GitHub README 미리보기를 확인하지 않습니다.
• 표가 너무 커도 README에 전부 넣으려고 합니다.

관련 도구

• Markdown Table Generator: CSV/TSV를 Markdown 표로 변환합니다.
• CSV Encoding Fixer: 한글 CSV가 깨져 있을 때 먼저 확인할 수 있습니다.

관련 글

• Markdown / GitHub Docs Center
• Markdown 표 깨짐 해결
• CSV / Excel Encoding Center
• CSV 한글 깨짐 해결
• Excel CSV UTF-8 깨짐 해결

업데이트 날짜

2026-05-15