CSV는 거의 모든 도구의 기본 내보내기 형식입니다. 스프레드시트, 데이터베이스 덤프, 분석 대시보드가 모두 CSV로 내보냅니다. 하지만 README를 작성하거나, GitHub Issue를 등록하거나, 기술 문서를 만들 때 필요한 건 Markdown 표입니다. CSV를 Markdown 표로 수동 변환하는 건 번거롭고 실수가 생기기 쉽습니다. 이 글에서는 Markdown 표 형식, CSV 엣지 케이스 처리, 그리고 온라인에서 즉시 변환하는 방법을 정리합니다.

CSV를 Markdown 표로 변환하기 →

Markdown 표 형식

Markdown 표는 세 부분으로 구성됩니다:

| 열 A | 열 B | 열 C |
|------|------|------|
| 값 1 | 값 2 | 값 3 |
| 값 4 | 값 5 | 값 6 |

규칙:

  • 첫 번째 행이 헤더입니다.
  • 두 번째 행(구분자 행)은 대시 ---와 선택적 콜론으로 구성합니다.
  • 모든 행은 같은 수의 파이프 구분 셀을 가져야 합니다.

열 정렬

구분자 행이 열 정렬을 제어합니다:

| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:----------|:-----------:|------------:|
| 텍스트    | 텍스트      | 텍스트      |
문법정렬
---왼쪽 정렬 (기본값)
:---왼쪽 정렬 (명시적)
:---:가운데 정렬
---:오른쪽 정렬

숫자 열에는 오른쪽 정렬을 사용하면 훨씬 읽기 편합니다.

CSV → Markdown 표: 예시

기본 변환

입력 CSV:

이름,역할,팀
Alice,엔지니어,플랫폼
Bob,디자이너,프로덕트
Charlie,매니저,그로스

출력 Markdown:

| 이름    | 역할     | 팀       |
|---------|----------|----------|
| Alice   | 엔지니어 | 플랫폼   |
| Bob     | 디자이너 | 프로덕트 |
| Charlie | 매니저   | 그로스   |

렌더링 결과:

이름역할팀
Alice엔지니어플랫폼
Bob디자이너프로덕트
Charlie매니저그로스

쉼표가 포함된 필드

CSV는 이중 따옴표로 값 내부의 쉼표를 처리합니다:

도시,설명
서울,"대한민국 수도, 인구 1000만 도시"
부산,"제2의 도시, 항구 도시"

변환 도구는 따옴표를 제거하고 값 내부의 파이프 문자(|)를 \|로 이스케이프해서 Markdown 표 구조를 유지합니다.

숫자 열

숫자 데이터가 있는 표는 숫자 열을 오른쪽 정렬하면 가독성이 크게 향상됩니다:

제품,가격,수량
키보드,89000,30
마우스,32000,80
헤드셋,120000,15

오른쪽 정렬 적용 출력:

| 제품   |    가격 | 수량 |
|--------|--------:|-----:|
| 키보드 |  89000  |   30 |
| 마우스 |  32000  |   80 |
| 헤드셋 | 120000  |   15 |

빈 셀

CSV에서 값이 없으면 Markdown 표에서 빈 셀이 됩니다:

id,이름,이메일
1,Alice,[email protected]
2,Bob,
3,,[email protected]

출력:

| id | 이름  | 이메일            |
|----|-------|-------------------|
| 1  | Alice | [email protected] |
| 2  | Bob   |                   |
| 3  |       | [email protected] |

주요 사용 사례

GitHub README

GitHub은 README, Wiki, Issue에서 Markdown 표를 네이티브로 렌더링합니다. CSV를 변환 도구에 붙여넣고, Markdown을 복사해서 README에 넣으면 끝입니다.

API 문서

요청 파라미터나 응답 필드를 문서화할 때, 스프레드시트에서 CSV로 내보내고 Markdown으로 변환해서 문서에 붙여넣습니다. 수동으로 표를 포맷팅하는 것보다 훨씬 빠릅니다.

GitHub Issue와 PR

버그를 보고할 때 테스트 결과, 벤치마크 비교, 설정 값을 첨부하는 경우, Markdown 표는 생 CSV 코드 블록보다 훨씬 읽기 좋습니다.

Notion, Confluence

Notion은 Markdown 붙여넣기를 인식해서 표로 변환합니다. Confluence도 Markdown 표를 지원합니다.

정적 문서 사이트

Docusaurus, VitePress, MkDocs 모두 Markdown 표를 렌더링합니다. 표 데이터를 스프레드시트로 관리하고, CSV 내보내기 → 변환 → 붙여넣기 워크플로로 유지할 수 있습니다.

값에 파이프 문자가 있을 때

파이프 |는 Markdown 표의 구분자입니다. CSV 값에 파이프 문자가 있으면 출력에서 \|로 이스케이프해야 합니다:

단축키,동작
Cmd|Ctrl+C,복사
Cmd|Ctrl+V,붙여넣기

변환 후:

| 단축키      | 동작       |
|-------------|------------|
| Cmd\|Ctrl+C | 복사       |
| Cmd\|Ctrl+V | 붙여넣기   |

좋은 변환 도구는 이를 자동으로 처리합니다.

코드로 변환하기

JavaScript

function csvToMarkdown(csv, alignRight = []) {
  const lines = csv.trim().split('\n');
  const rows = lines.map(line =>
    line.split(',').map(cell =>
      cell.trim().replace(/^"|"$/g, '').replace(/\|/g, '\\|')
    )
  );

  const headers = rows[0];
  const separator = headers.map((_, i) =>
    alignRight.includes(i) ? '---:' : '---'
  );

  const toRow = cells => '| ' + cells.join(' | ') + ' |';
  return [toRow(headers), toRow(separator), ...rows.slice(1).map(toRow)].join('\n');
}

const csv = `제품,가격\n키보드,89000\n마우스,32000`;
console.log(csvToMarkdown(csv, [1])); // 1번 열 오른쪽 정렬

Python

import csv
import io

def csv_to_markdown(csv_text, align_right=None):
    align_right = align_right or []
    reader = csv.reader(io.StringIO(csv_text.strip()))
    rows = [[cell.replace('|', '\\|') for cell in row] for row in reader]

    if not rows:
        return ''

    headers = rows[0]
    col_widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]

    def fmt_row(cells):
        padded = [cells[i].ljust(col_widths[i]) for i in range(len(cells))]
        return '| ' + ' | '.join(padded) + ' |'

    sep = [('-' * w + ':') if i in align_right else '-' * w
           for i, w in enumerate(col_widths)]

    lines = [fmt_row(headers), '| ' + ' | '.join(sep) + ' |']
    lines += [fmt_row(row) for row in rows[1:]]
    return '\n'.join(lines)

csv_text = "제품,가격\n키보드,89000\n마우스,32000"
print(csv_to_markdown(csv_text, align_right=[1]))

Markdown 표의 한계

Markdown 표에는 몇 가지 제약이 있습니다:

  • 셀 병합 불가: colspan이나 rowspan을 지원하지 않습니다. 복잡한 레이아웃에는 HTML 표를 사용합니다.
  • 다중 행 셀 불가: 셀 내부의 줄바꿈은 표 구조를 깨뜨립니다.
  • 스타일 지정 불가: 글꼴, 색상, 테두리는 테마가 제어합니다. Markdown에서는 지정할 수 없습니다.
  • 초대형 표: 열이 30개를 넘거나 행이 수백 개를 넘으면 가독성이 크게 떨어집니다. 분할하거나 코드 블록 사용을 고려하세요.

Markdown으로 처리하기 어려운 경우, GitHub은 인라인 HTML 표도 지원합니다:

<table>
  <tr><th>이름</th><th>역할</th></tr>
  <tr><td>Alice</td><td>엔지니어</td></tr>
</table>

온라인 CSV to Markdown 변환 도구

ZeroTool CSV to Markdown 변환 도구는 완전히 브라우저 안에서 동작합니다. CSV를 붙여넣고, 열 정렬을 선택하고, Markdown 출력을 복사하세요. 파일 업로드 불필요, 계정 등록 불필요.

CSV to Markdown 변환 도구 열기 →