README에 표를 넣고 싶다면 CSV 데이터를 CSV to Markdown에 붙여넣고 실행하는 것이 가장 빠른 방법입니다. 브라우저 안에서 GitHub Flavored Markdown(GFM) 호환 표가 생성되므로 그대로 README에 복사해 붙여넣을 수 있습니다.
이 글에서는 README에 표를 넣어야 하는 상황, 실무 예시, CSV나 JSON에서 자동 생성하는 절차, GitHub Flavored Markdown(GFM) 고유의 주의점을 정리합니다.
README에 표가 필요한 상황
README에 일반 텍스트나 글머리 기호(불릿 목록)만으로 정보를 나열하면 줄 수가 늘어날수록 가독성이 떨어집니다. 다음과 같은 정보는 표로 정리하는 편이 훨씬 직관적입니다.
- API 엔드포인트 목록(경로, HTTP 메서드, 설명)
- 지원 버전 및 플랫폼 호환성 매트릭스
- 기능 비교(자사 프로젝트 vs 경쟁 라이브러리, 또는 요금제별 기능 차이)
- CLI 명령어 옵션 레퍼런스
- 환경 변수 목록과 기본값
이러한 정보를 글머리 기호로 나열하면 세로로 길어지고 열 방향으로 값을 비교하기 어렵습니다. 표로 정리하면 가로 방향으로 차이를 한눈에 확인할 수 있어 README를 읽는 개발자의 부담이 줄어듭니다.
실제 README에서 쓰이는 표 예시 3가지
위에서 언급한 5가지 용도는 다소 추상적이므로, 실제 README에 바로 복사해 쓸 수 있는 구체적인 마크다운 예시 3가지를 소개합니다.
CLI 옵션 레퍼런스 — 플래그가 늘어났을 때는 --help 출력문을 그대로 붙여넣는 것보다 표로 정리하는 편이 훨씬 읽기 쉽습니다.
| 플래그 | 기본값 | 설명 |
| :--- | :--- | :--- |
| `--port` | `3000` | HTTP 수신 대기 포트 |
| `--host` | `0.0.0.0` | 바인드 주소 |
| `--log-level` | `info` | 로그 레벨 (`debug`, `info`, `warn`, `error`) |
버전 호환성 매트릭스 — README에서 가장 자주 확인되는 부분으로, 지원하는 런타임을 표로 나타내면 한눈에 파악할 수 있습니다.
| 런타임 | 최소 버전 | 검증 버전 | 지원 상태 |
| :--- | ---: | ---: | :--- |
| Node.js | 18.x | 22.x | LTS 공식 지원 |
| Bun | 1.0 | 1.1 | 베스트 에포트 |
| Deno | 1.40 | 2.0 | 커뮤니티 지원 |
경쟁 라이브러리와의 기능 비교 — "왜 이 라이브러리를 써야 하는가" 섹션에서 자주 쓰입니다.
| 기능 | 이 프로젝트 | 대안 A | 대안 B |
| :--- | :---: | :---: | :---: |
| 의존성 제로 (Zero-dep) | ✅ | ❌ | ✅ |
| TypeScript 타입 지원 | ✅ | ✅ | ❌ |
| 브라우저 환경 동작 | ✅ | ❌ | ❌ |
세 가지 예시 모두 34행 × 34열 정도로 간결하게 구성되어 있습니다. 이는 GitHub 모바일 화면에서도 가로 스크롤 없이 깔끔하게 표시되며, README 내용이 늘어나도 가독성을 유지하기 위한 의도적인 설계입니다.
마크다운 표 기본 문법
GFM 표는 파이프 기호 |로 열을 구분합니다.
| 명령어 | 설명 |
| --- | --- |
| install | 의존 패키지 설치 |
| build | 프로덕션 빌드 실행 |
| test | 테스트 스위트 실행 |
1행은 헤더, 2행은 구분 행(delimiter row), 3행 이후는 데이터 행입니다. 구분 행에 콜론 :을 넣으면 열 정렬을 지정할 수 있습니다(:---는 왼쪽 정렬, :---:는 가운데 정렬, ---:는 오른쪽 정렬).
자세한 마크다운 표 문법과 정렬 방법은 마크다운 표 작성법을 참고하세요.
CSV에서 README용 표 생성하기
스프레드시트나 CSV 파일의 데이터를 표로 만들 때는 CSV to Markdown 변환기를 사용합니다.
- CSV to Markdown 도구를 엽니다
- 왼쪽 에디터에 CSV 내용을 붙여넣습니다 (Excel이나 Google Sheets에서 복사한 데이터도 가능합니다)
- 실행 버튼을 누릅니다
- 오른쪽에 생성된 마크다운 표를 복사하여 README에 붙여넣습니다
모든 변환 처리는 브라우저 내부에서 완료되므로 회사 내부 데이터나 비공개 설정값을 붙여넣어도 외부 서버로 전송되지 않습니다. 자세한 변환 원리와 에지 케이스 처리는 CSV를 마크다운 표로 변환하는 방법을 참고하세요.
터미널에서 대량의 데이터를 자동 변환하고 싶다면 CLI 도구를 활용해 cat data.csv | formatarc csv-to-markdown과 같은 방식으로 GFM 표를 출력할 수 있으며, CI 파이프라인에서 README를 자동 갱신하는 용도로도 활용할 수 있습니다. 자세한 CLI 사용법은 formatarc CLI 사용법을 참고하세요.
JSON 데이터에서 표 만들기
API 응답이나 로그, 설정 덤프처럼 원본 데이터가 JSON 형식인 경우도 많습니다. JSON 데이터를 마크다운 표로 만드는 가장 확실한 방법은 먼저 CSV로 변환한 뒤 마크다운 표를 생성하는 것입니다. 배열이나 중첩 구조, API 응답 데이터를 마크다운 표로 만드는 자세한 방법은 JSON을 마크다운 표로 변환하는 방법을 참고하세요.
변환 절차
- JSON 포맷터에서 JSON을 정렬하여 데이터 구조를 확인합니다
- JSON 객체 배열을 CSV 형식으로 변환합니다 (각 객체의 키가 열 헤더가 되고, 값이 행의 셀이 됩니다)
- 변환된 CSV를 CSV to Markdown에 붙여넣어 표를 생성합니다
예를 들어 다음과 같은 JSON 배열이 있다고 가정해 봅니다.
[
{ "name": "Node.js", "version": "20.x", "status": "LTS" },
{ "name": "Node.js", "version": "22.x", "status": "Current" }
]
이를 CSV로 변환하면 다음과 같습니다.
name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current
이 CSV 데이터를 CSV to Markdown에 전달하면 README에 바로 붙여넣을 수 있는 깔끔한 마크다운 표가 완성됩니다.
README 표 작성 시 자주 빠지는 실수 4가지
README에서 표가 제대로 렌더링되지 않거나 깨지는 원인은 대부분 4가지로 좁혀집니다. 원인을 미리 알고 있으면 마크다운 원본을 일일이 디버깅하는 수고를 덜 수 있습니다. 참고로 GFM 사양 섹션 4.10새 탭에서 열립니다에서는 구분 행을 "내용이 하이픈(-)뿐이고 선택적으로 앞뒤에 콜론(:)이 붙은 셀"로 정의하고 있으며, 하이픈의 최소 개수를 규정하지 않습니다. 또한 표 바로 위에 빈 줄이 반드시 있어야 한다는 사양상 규정도 없습니다.
열 수가 일치하지 않음
구분 행이 표의 전체 열 수를 확정합니다. 구분 행의 열 수보다 셀이 많은 행은 초과 셀이 경고 없이 버려지고, 셀이 부족한 행은 빈 셀로 채워집니다.
| name | role |
| --- | --- |
| Alice | Engineer | LA ← 초과된 셀은 아무런 경고 없이 무시됨
| Bob ← 셀이 부족하면 빈칸으로 렌더링됨
GitHub는 이에 대해 에러나 경고를 표시하지 않습니다. 만약 표의 오른쪽 열이 이유 없이 비어 있다면 해당 행의 파이프 개수를 세어 보세요.
구분 행 누락 및 형태 오류
텍스트 블록을 표로 변환하는 핵심 요소는 구분 행입니다. 구분 행이 잘못되면 전체가 표로 인식되지 않습니다. 중요한 것은 하이픈의 개수가 아니라 열 수의 일치 여부입니다.
| name | role |
| --- | ← 헤더는 2열인데 구분 행은 1열: 어떤 파서에서도 표로 인식되지 않음
| Alice | Engineer |
이 케이스를 4개의 파서(저장소의 scripts/benchmarks/markdown-table-parsers/, 2026-07-15 실측. GitHub Markdown API, marked 18.0.5, remark-gfm 4.0.1, strict CommonMark remark-parse)에 통과시켜 검증했습니다. 열 수가 일치하지 않으면 4개 파서 모두에서 표로 렌더링되지 않았습니다.
반면 하이픈의 개수는 표 인식에 영향을 주지 않습니다. 동일한 실측에서 | - | - |나 | -- | -- | 모두 GitHub Markdown API, marked, remark-gfm에서 정상적인 표로 렌더링되었습니다. 하이픈 3개(---)는 가독성을 위한 관례일 뿐 필수 조건이 아닙니다. GitHub 자체 문서에는 "3개 이상"이라고 적혀 있지만 사양에는 규정이 없고 실제 구현체는 1개도 허용합니다. 따라서 표가 그려지지 않을 때 하이픈 개수부터 의심하는 것은 잘못된 접근입니다. 마크다운 표가 렌더링되지 않거나 깨지는 원인과 해결법은 마크다운 표가 안 나오거나 깨질 때를 참고하세요.
다만 구분 행이 짧을 때 문제가 발생하는 예외가 하나 있습니다. 바깥쪽 파이프를 생략한 상태에서 하이픈을 1개만 쓰면(- | -) GitHub는 이를 표가 아닌 목록(List)으로 해석합니다.
h1 | h2
- | - ← GitHub에서는 목록으로 렌더링됨 (`--- | ---`이면 표로 렌더링됨)
a | b
에디터에서는 표로 보이는데 GitHub에서는 보이지 않는다면, 먼저 구분 행의 열 수를 확인하고 다음으로 바깥쪽 파이프 유무를 확인하세요.
GitHub과 에디터 간 빈 셀 처리 차이
GFM에서는 내용이 완전히 비어 있는 빈 셀을 공식적으로 허용합니다.
| 기능 | Basic | Pro |
| :--- | :---: | :---: |
| PDF 내보내기 | | ✅ |
| API 접근 권한 | | ✅ |
GitHub는 이러한 빈 셀을 정상적으로 렌더링하지만, 일부 마크다운 에디터는 연속된 파이프를 문법 오류로 간주해 행을 찌그러뜨려 표시하기도 합니다. 마크다운 원본은 정상이지만 에디터의 미리보기가 잘못된 경우입니다. 최종 결과는 항상 GitHub 상에서 확인하는 것이 정확합니다.
셀 안에서 파이프 | 리터럴 사용 시 에스케이프
셀 안에서 파이프 기호를 그대로 쓰면 열 구분자로 인식되어 표가 깨집니다. 백슬래시로 이스케이프(\|)하거나 HTML 엔티티 |를 사용해야 합니다.
| 조건식 | 의미 |
| --- | --- |
| `a \| b` | 비트 OR 연산 |
| `a | b` | 엔티티 표기 방식 |
GitHub에서는 두 방식 모두 a | b로 올바르게 렌더링됩니다. 백슬래시 이스케이프가 GFM 표준이지만, Hugo나 MkDocs 같은 비 GFM 도구 체인으로 README를 가공하는 환경에서는 엔티티 표기가 더 안전합니다.
로컬 에디터에서 표가 깨져 보이더라도 GitHub에 올렸을 때 정상이라면 에디터 측 파서 문제입니다. README 표의 최종 기준은 항상 github.com 렌더링 화면입니다.
GFM 표 고유의 주의점
GitHub의 마크다운 렌더러는 일반적인 마크다운 에디터와 몇 가지 다른 동작 특성을 갖고 있습니다.
셀 안 줄바꿈은 <br> 태그 사용
GFM 표 사양에서는 셀 안에서 일반 엔터 줄바꿈을 지원하지 않습니다. 여러 줄로 작성하더라도 렌더링 시 한 줄로 합쳐집니다.
| 단계 | 설명 |
| --- | --- |
| 1 | 의존성 패키지 설치
빌드 실행 |
셀 안에서 줄을 바꾸고 싶다면 <br> 태그를 사용해야 합니다. GitHub는 이를 셀 내부의 줄바꿈으로 렌더링합니다.
| 단계 | 설명 |
| --- | --- |
| 1 | 의존성 패키지 설치<br>빌드 실행 |
| 2 | 테스트 실행<br>락 파일 커밋 |
<br> 태그는 GitHub 마크다운 새니타이저(sanitizer)가 표 셀 내부에서 허용하는 몇 안 되는 HTML 태그 중 하나입니다.
셀 안 서식: 강조·코드·링크·배지
표의 셀 내부에서는 인라인 마크다운 문법이 정상 동작합니다. README 표가 상태 표시나 비교 매트릭스로 널리 쓰이는 이유입니다. 볼드체, 인라인 코드, 링크, 이미지, 이모지 모두 렌더링할 수 있습니다.
| 패키지 | 빌드 상태 | 문서 |
| --- | --- | --- |
| `core` |  | [문서 읽기](./docs/core.md) |
| `cli` | :warning: experimental | [문서 읽기](./docs/cli.md) |
단, 두 가지는 지원되지 않습니다. 첫째는 블록 레벨 요소로 제목(Heading), 글머리 목록, 코드 블록(Fenced code block)은 셀 안에 넣을 수 없습니다. 셀 첫머리에 #을 써도 단순한 # 문자로 표시됩니다. 둘째는 파이프 기호입니다. shields.io 배지 URL이나 이미지 링크 안에 |가 포함되어 있으면 셀이 쪼개집니다. ?label=a|b와 같은 쿼리 스트링은 \|로 이스케이프하거나 %7C로 퍼센트 인코딩해야 합니다.
CSV나 JSON에서 표를 자동 생성할 때는 원본 데이터 셀에 배지 마크다운이나 URL을 그대로 넣어 두면 CSV to Markdown이 이를 그대로 보존하여 표를 생성합니다.
HTML 태그 혼용 제한
GitHub는 보안상의 이유로 표 셀 내부의 HTML 스타일 지정을 엄격하게 차단합니다. <br>은 줄바꿈으로 동작하지만 <span style="...">, <font color> 같은 인라인 스타일은 무시됩니다. 따라서 셀 내에서 글자 색상이나 크기를 임의로 변경할 수 없습니다. <details> 같은 접기 블록도 표 외부에서는 동작하지만 셀 내부에서는 작동하지 않습니다.
열 정렬 지정
구분 행에 콜론 :을 추가하는 정렬 문법은 GitHub에서 완벽하게 동작합니다. 버전 번호나 가격, 통계 같은 숫자 데이터 열을 오른쪽 정렬(---:)하면 자릿수가 깔끔하게 맞춰져 가독성이 크게 올라갑니다.
| 플랜 | 월 요금 |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |
넓은 표와 가로 스크롤
열 수가 많은 표는 GitHub 화면에서 가로 스크롤을 발생시킵니다. PC와 모바일 환경 모두에서 README를 원활하게 읽을 수 있도록 하려면 열 수를 5~6열 이내로 제한하거나, 성격에 따라 표를 여러 개로 분할하는 것이 실용적입니다.
자주 묻는 질문
README 표를 스프레드시트로 관리할 수 있나요?
네, 가능합니다. Google Sheets나 Excel에서 표 데이터를 관리하고, 내용이 변경될 때마다 CSV로 내보내어 CSV to Markdown 도구로 변환하면 항상 최신 상태의 마크다운 표를 README에 손쉽게 반영할 수 있습니다.
표 셀 안에 링크나 이미지를 넣을 수 있나요?
네, 가능합니다. 셀 안에 [링크 텍스트](URL) 형식의 마크다운 링크나  형식의 이미지를 넣으면 GitHub 상에서 정상적으로 클릭 가능한 링크 및 이미지로 렌더링됩니다.
정리
- README에 표를 활용하면 복잡한 옵션, 버전 호환성, 기능 비교 등의 정보를 직관적으로 전달할 수 있습니다
- 마크다운 표는 파이프
|와 구분 행의 하이픈-으로 구성되며, 콜론:으로 열 정렬을 지정할 수 있습니다 - 표가 깨지는 주원인은 하이픈 개수가 아니라 헤더와 구분 행의 열 수 불일치 및 셀 안의 파이프(
|) 문자입니다 - 복잡하거나 행이 많은 표는 수작업 대신 CSV to Markdown 변환기를 사용하면 빠르고 안전하게 GFM 호환 표를 생성할 수 있습니다