GUIDE - Updated 2026-05-15
GitHub README 표를 깔끔하게 만드는 법
GitHub README에서 Markdown 표를 읽기 좋게 만들기 위해 헤더, 정렬, escape, 긴 셀 처리 기준을 정리하는 방법.
Open Markdown Table Generator핵심 요약
GitHub README 표는 열을 적게 유지하고, 헤더를 명확히 쓰고, 셀 안의 |와 줄바꿈을 처리해야 깔끔하게 보입니다. CSV/TSV 원본이 있다면 직접 손으로 맞추기보다 Markdown 표로 변환한 뒤 미리보기에서 확인하는 편이 빠릅니다.
왜 중요한가
README는 프로젝트의 첫 화면입니다. 설치 방법, 옵션, 비교표가 깨져 있으면 사용자는 도구를 신뢰하기 어렵습니다. 표는 정보를 빠르게 비교하게 해주지만, 너무 크거나 깨지면 오히려 이해를 방해합니다.
기본 개념
| 요소 | 기준 |
|---|---|
| 헤더 | 짧고 구체적으로 |
| 구분선 | ` |
| 정렬 | 필요할 때만 :---, ---: 사용 |
| 긴 설명 | 표 밖으로 빼거나 <br> 사용 |
| 특수문자 | ` |
비교표
| 상황 | 권장 방식 |
|---|---|
| 옵션 3-5개 비교 | README 표 사용 |
| 행이 50개 이상 | 별도 문서나 CSV 링크 |
| 설명이 긴 기능 | 표에는 요약, 아래에 상세 |
| CSV 원본 있음 | 변환 도구 사용 |
실무 적용 방법
- 표의 목적을 하나로 정합니다.
- 열 수를 3-5개 정도로 줄입니다.
- CSV/TSV는 Markdown Table Generator로 변환합니다.
- 셀 안의
|와 줄바꿈을 확인합니다. - GitHub preview에서 모바일 폭까지 확인합니다.
예제
| Tool | Use case | Output |
|---|---|---|
| CSV Fixer | Encoding check | UTF-8 BOM CSV |
| JSON Doctor | Parse error check | Pretty JSON |
헤더가 짧고, 각 행의 역할이 분명하면 README에서 스캔하기 쉽습니다.
관련 도구
- Markdown Table Generator: CSV/TSV를 GitHub Markdown 표로 변환합니다.
관련 에러
관련 가이드
업데이트 날짜
2026-05-15