ERROR - Updated 2026-05-15

Markdown 표 깨짐 해결

GitHub README나 문서에서 Markdown 표가 깨지는 이유와 헤더, 구분선, 파이프 문자, 줄바꿈을 확인하는 방법.

Markdown 표가 깨지는 가장 흔한 이유는 헤더와 구분선의 열 개수가 맞지 않거나, 셀 안의 파이프 문자 |가 표 구분자로 해석되기 때문입니다. GitHub README에서는 표 문법이 단순해 보이지만, 줄바꿈과 특수문자가 섞이면 쉽게 흐트러집니다. 먼저 첫 두 줄의 열 개수를 확인하고, 셀 안의 |와 줄바꿈을 처리하세요.

증상

README에서 표가 표로 보이지 않고 일반 텍스트로 표시됩니다.
일부 행만 열이 밀립니다.
셀 안의 A | B 같은 문구 때문에 열이 늘어납니다.
CSV에서 복사한 내용을 붙였더니 Markdown 표 정렬이 깨집니다.

원인

Markdown 표는 첫 줄 헤더, 두 번째 줄 구분선, 이후 데이터 행의 열 구조가 맞아야 합니다. 각 열은 |로 구분되고, 두 번째 줄에는 --- 같은 구분선이 필요합니다.

문제	예	해결
구분선 없음	헤더 다음에 바로 데이터	두 번째 줄에 `---` 추가
열 개수 불일치	헤더 3열, 데이터 2열	모든 행 열 개수 맞춤
셀 안 파이프	`A	B`
셀 안 줄바꿈	여러 줄 설명	`<br>` 또는 짧은 문장으로 정리

바로 해결 방법

표 첫 줄과 두 번째 줄이 있는지 확인합니다.
헤더, 구분선, 데이터 행의 | 개수를 맞춥니다.
셀 내부의 |는 \|로 escape합니다.
줄바꿈이 들어간 긴 셀은 <br> 또는 짧은 문장으로 바꿉니다.
CSV/TSV 원본이 있다면 Markdown Table Generator로 다시 변환합니다.

FixData 도구로 확인하기

Markdown Table Generator는 CSV 또는 TSV를 GitHub README에 붙여넣기 좋은 Markdown 표로 바꿔줍니다. 원본 데이터의 구분자를 확인하고, 변환된 표를 복사해 README에 넣으면 수동으로 열을 맞추는 시간을 줄일 수 있습니다.

표가 여전히 깨진다면 원본 셀 안에 파이프 문자, 줄바꿈, 따옴표가 들어 있는지 확인하세요.

수동 해결 방법

기본 표 구조 확인

올바른 기본 구조:

| Name | Role |
|---|---|
| Alice | Admin |
| Bob | Editor |

두 번째 줄의 ---가 빠지면 GitHub에서 표로 렌더링되지 않을 수 있습니다.

파이프 문자 escape

셀 안에 파이프 문자가 있으면 열 구분자로 오해됩니다.

| Regex | Meaning |
|---|---|
| A \| B | A 또는 B |

긴 셀 줄이기

README 표는 너무 긴 설명을 넣으면 읽기 어려워집니다. 긴 문장은 표 밖 설명으로 빼거나 <br>로 줄을 나눕니다.

예제

깨진 표:

| Name | Status |
|---|---|
| API | Ready | Stable |

수정한 표:

| Name | Status |
|---|---|
| API | Ready \| Stable |

자주 하는 실수

헤더와 데이터 행의 열 개수를 세지 않습니다.
셀 안의 |를 escape하지 않습니다.
CSV 원본의 줄바꿈과 쉼표를 그대로 붙여넣습니다.
GitHub README와 다른 Markdown 렌더러의 차이를 확인하지 않습니다.
표 안에 너무 긴 설명을 넣어 가독성을 떨어뜨립니다.

업데이트 날짜

2026-05-15