GitHub README 표를 깔끔하게 만드는 법

핵심 요약

GitHub README 표는 열을 적게 유지하고, 헤더를 명확히 쓰고, 셀 안의 |와 줄바꿈을 처리해야 깔끔하게 보입니다. CSV/TSV 원본이 있다면 직접 손으로 맞추기보다 Markdown 표로 변환한 뒤 미리보기에서 확인하는 편이 빠릅니다.

좋은 README 표는 “예쁘게 정렬된 텍스트”가 아니라 “비교 기준이 분명한 작은 데이터 구조”입니다. 열 수를 줄이고, 각 열의 의미를 고정하고, 긴 설명은 표 밖으로 빼야 모바일과 GitHub preview에서 읽기 쉽습니다.

왜 중요한가

README는 프로젝트의 첫 화면입니다. 설치 방법, 옵션, 비교표가 깨져 있으면 사용자는 도구를 신뢰하기 어렵습니다. 표는 정보를 빠르게 비교하게 해주지만, 너무 크거나 깨지면 오히려 이해를 방해합니다.

GitHub Markdown 표는 pipe(|)와 hyphen(-)으로 헤더와 셀을 구분합니다. 표 앞에 빈 줄이 없거나, 헤더 구분선이 부족하거나, 셀 안의 |를 escape하지 않으면 의도와 다르게 렌더링될 수 있습니다. 따라서 README에 붙여넣기 전에 preview 기준으로 확인해야 합니다.

기본 개념

비교표

GitHub 표 준비 체크리스트

실무 적용 방법

1. 표의 목적을 하나로 정합니다.
2. 열 수를 3-5개 정도로 줄입니다.
3. CSV/TSV는 Markdown Table Generator로 변환합니다.
4. 셀 안의 |와 줄바꿈을 확인합니다.
5. GitHub preview에서 모바일 폭까지 확인합니다.

CSV/TSV를 표로 바꾸기 전 정리

원본 데이터가 CSV라면 먼저 헤더 이름을 사람이 읽을 수 있게 고칩니다. is_enabled, max_retry, created_at 같은 개발자용 필드는 README 표에서는 Enabled, Retry limit, Created처럼 짧은 이름이 더 읽기 쉽습니다.

다음으로 셀 안에 쉼표, pipe, 줄바꿈이 있는지 확인합니다. CSV의 쉼표는 Markdown 표에서 문제가 되지 않지만, pipe는 열 구분자로 해석될 수 있습니다. 줄바꿈이 많은 설명은 표 안에 모두 넣기보다 표 아래에 항목별 상세 설명으로 분리하는 편이 좋습니다.

예제

| Tool | Use case | Output |
|---|---|---|
| CSV Fixer | Encoding check | UTF-8 BOM CSV |
| JSON Doctor | Parse error check | Pretty JSON |

헤더가 짧고, 각 행의 역할이 분명하면 README에서 스캔하기 쉽습니다.

셀 안에 pipe가 있는 예

| Option | Meaning |
|---|---|
| `a \| b` | a 또는 b를 선택 |

a | b처럼 escape하지 않으면 GitHub가 셀을 나누는 구분자로 오해할 수 있습니다. 변환 도구를 사용할 때도 이 문자를 자동으로 처리하는지 확인해야 합니다.

실무 FAQ

Markdown 표의 공백 정렬을 손으로 맞춰야 하나요?

필수는 아닙니다. GitHub는 셀 폭을 렌더링 단계에서 맞춥니다. 사람이 관리하기 쉬운 정도로만 정리하고, 열 수와 셀 내용이 맞는지를 더 중요하게 봐야 합니다.

README에 큰 표를 넣어도 되나요?

행이 많거나 열이 넓으면 README 첫 화면이 무거워집니다. 핵심 비교만 README에 두고, 상세 데이터는 별도 문서, CSV, docs 페이지로 분리하는 편이 좋습니다.

셀 안 줄바꿈은 어떻게 처리하나요?

짧은 줄바꿈만 필요하면 <br>을 쓸 수 있습니다. 다만 설명이 길다면 표 밖으로 빼는 것이 더 읽기 쉽습니다.

CSV를 Markdown으로 바꾸면 항상 GitHub에서 잘 보이나요?

아닙니다. CSV 원본의 헤더, pipe 문자, 긴 셀, 줄바꿈, 빈 값이 Markdown 렌더링에 영향을 줍니다. 변환 후 GitHub preview에서 실제 표시를 확인해야 합니다.

관련 도구

• Markdown Table Generator: CSV/TSV를 GitHub Markdown 표로 변환합니다.

관련 에러

• Markdown 표 깨짐 해결
• CSV를 Markdown 표로 바꾸는 법

관련 가이드

• Markdown / GitHub Docs Center

업데이트 날짜

2026-06-25