먼저 진단 순서 — 이 순서로 확인하기
마크다운 표가 표시되지 않거나 표 모양으로 렌더링되지 않을 때, 파서는 오류 메시지를 내보내지 않습니다. 표로 인식되지 않으면 오류 없이 그냥 일반 문단(텍스트)으로 표시하고, 셀 구분을 잘못 읽으면 열이 조용히 어긋난 채로 출력합니다. 오류 메시지가 없는 만큼 원인은 직접 순서대로 짚어가며 확인해야 합니다.
확인해야 할 항목은 다음 5가지입니다. 확실하게 표를 깨뜨리는 원인과 확인 비용이 적게 드는 순서대로 정리했습니다.
- 헤더 행과 구분 행의 열 수가 일치하는가 (열 수 불일치는 사양 수준에서 표 인식을 완전히 잃게 만드는 유일한 구문 조건입니다)
- 셀 안에 이스케이프되지 않은 원본 파이프
|가 들어 있지 않은가 (인라인 코드 영역 안도 포함됩니다) - 표 바로 앞에 빈 줄이 있는가
- 사용 중인 렌더러가 GFM(GitHub Flavored Markdown) 표를 지원하는가
- 문법이 아닌 환경 측 문제(Jupyter 셀 종류, 플랫폼 CSS 등)가 아닌가
원인을 빠르게 좁히는 가장 빠른 방법은 3행짜리 최소 크기 표를 붙여넣어 보는 것입니다.
| A | B |
| --- | --- |
| 1 | 2 |
이 3행이 표로 표시되지 않는다면 원인은 작성한 표가 아니라 렌더러나 실행 환경에 있습니다(증상 1의 후반부 또는 증상 5로 이동). 정상적인 표로 표시된다면 작성한 표의 문법에 원인이 있습니다(증상 1부터 순서대로 확인합니다).
GFM 파서가 표를 어떻게 해석하는지 직접 확인하고 싶다면 Markdown to HTML 변환기에 표를 붙여넣어 보세요. marked 기반 GFM 파서가 생성하는 HTML을 브라우저 안에서 바로 확인할 수 있습니다. 결과에 <table> 태그가 출력된다면 파싱에 성공한 것입니다. 붙여넣은 내용은 서버로 전송되지 않습니다. 다만 이는 GFM 계열 파서의 동작을 확인하는 용도이며, Notion이나 사내 위키 등 특정 플랫폼의 자체 렌더링 동작을 완벽하게 재현하는 것은 아니라는 점에 유의하세요.
이 글은 문제 해결에 초점을 맞추고 있습니다. 마크다운 표의 기본 작성법을 처음부터 확인하고 싶다면 마크다운 표 작성법 가이드를 참고하세요.
증상 1: 표가 되지 않고 일반 텍스트로 표시됨
파이프로 구분된 텍스트가 표가 아니라 하나의 긴 문단으로 그대로 표시되는 경우입니다. 파서가 해당 블록을 "표"로 인식하지 못했음을 뜻합니다.
헤더 행과 구분 행의 열 수 불일치
표 인식을 확실하게 깨뜨리는 구문 조건은 이것 하나뿐입니다. GFM 사양은 구분 행의 열 수가 헤더 행과 일치하지 않으면 표로 취급하지 않는다고 명시하고 있습니다. 오류 메시지 없이 일반 문단으로 폴백됩니다.
깨진 예시입니다. 헤더는 3열인데 구분 행은 2열뿐입니다.
| 이름 | 이메일 | 권한 |
| --- | --- |
| 민준 | minjun@example.com | admin |
구분 행의 열 수를 헤더에 맞추면 바로 표로 인식됩니다.
| 이름 | 이메일 | 권한 |
| --- | --- | --- |
| 민준 | minjun@example.com | admin |
열 수를 셀 때는 헤더 행과 구분 행 두 줄만 확인하면 충분합니다. 데이터 행의 열 수가 많거나 적은 것은 표 인식 자체를 깨뜨리지 않습니다(증상 2에서 다룹니다).
표 직전에 빈 줄이 없음
본문 문단 바로 뒤에 빈 줄을 두지 않고 표를 이어서 작성하면 표로 인식하지 않는 파서가 있습니다. 실측 결과(2026-07-15, 재현 스크립트는 scripts/benchmarks/markdown-table-parsers/) GitHub 공식 렌더러(Markdown API 경유), marked 18.0.5, remark-gfm 4.0.1은 모두 빈 줄이 없어도 표를 인식했지만, 빈 줄을 필수로 요구하는 구현이나 플랫폼도 존재합니다. 빈 줄을 1줄 추가하는 것만으로 확인할 수 있는 가장 간단한 수정이므로, 열 수 확인 다음으로 먼저 시도해 보세요.
목록(리스트) 항목 안에 넣은 표
글머리 기호 목록이나 인용 블록 안에 표를 넣을 때는 단독으로 쓸 때와 다른 규칙이 적용됩니다. 글머리 기호 마커 - 는 하이픈과 공백으로 2글자이고, 번호 매기기 마커 1. 는 숫자와 마침표, 공백으로 3글자입니다. 표를 <li> 요소의 내용으로 유지하려면 이 마커 너비 이상의 들여쓰기가 필요합니다. remark 4.0.1 + remark-gfm 4.0.1 파이프라인에서 실측한 결과입니다(scripts/benchmarks/markdown-table-in-containers/).
| 작성 방식 | 표로 인식되는가 | <li> 안으로 들어가는가 |
|---|---|---|
- item 직후, 들여쓰기 0, 빈 줄 없음 | 인식 안 됨 | — |
- item 뒤, 들여쓰기 0, 빈 줄 있음 | 인식됨 | 들어가지 않음 (<ul> 바깥의 형제 블록으로 분리) |
- item 뒤, 들여쓰기 1, 빈 줄 있음 | 인식됨 | 들어가지 않음 |
- item 뒤, 들여쓰기 2, 빈 줄 없음 | 인식됨 | 들어감 |
- item 뒤, 들여쓰기 2, 빈 줄 있음 | 인식됨 | 들어감 |
1. item 뒤, 들여쓰기 2, 빈 줄 있음 | 인식됨 | 들어가지 않음 |
1. item 뒤, 들여쓰기 3, 빈 줄 있음 | 인식됨 | 들어감 |
들여쓰기가 마커 너비에 미치지 못하고 빈 줄도 없다면 표가 되어야 할 줄이 이전 문단의 연속으로 흡수되어 표가 되지 않습니다(첫 번째 행). 빈 줄을 넣으면 표 자체는 생성되지만, 들여쓰기가 부족하면 목록은 거기서 끝나고 표는 목록 바깥의 형제 블록으로 그려집니다(2, 3, 6번째 행). 번호 매기기 목록은 글머리 기호보다 1글자 더 긴 3글자의 들여쓰기가 필요하므로, 글머리 기호에서는 <li> 안에 들어가는 들여쓰기 2칸이라도 번호 목록에서는 바깥으로 빠집니다(6번째와 7번째 행의 차이). 표를 <li> 안에 안정적으로 넣으려면 목록 마커 너비와 동일하게 들여쓰기를 맞춰 주세요.
인용 블록 안에 넣은 표
인용 블록의 > 기호는 표의 각 행에 붙였는지에 따라 결과가 크게 달라집니다. 동일한 실측 결과입니다(scripts/benchmarks/markdown-table-in-containers/).
| 작성 방식 | 표로 인식되는가 | 데이터 행 |
|---|---|---|
> 기호가 첫 행에만 있음 | 인식 안 됨 (3행이 1개 문단으로 합쳐짐) | — |
> 기호가 헤더 행과 구분 행에만 있음 | 인식됨 | 사라짐 (<thead>만 생성되고 데이터 행은 인용 블록 밖의 문단으로 밀려남) |
> 기호가 전체 행에 있음 | 인식됨 | 정상 유지 |
특히 주의할 점은 두 번째 경우입니다. 헤더 행과 구분 행에만 >를 붙이면 GFM 표 확장은 이 두 행만으로 표로 인식해 <table>을 생성하지만, >가 없는 데이터 행은 인용 블록에 속하지 않아 일반 문단 텍스트로 표 바깥에 떨어집니다. 오류나 경고가 발생하지 않아 표는 표시되는데 내용이 비어 있는 상태를 알아채기 어렵습니다. 인용 블록 안에 표를 작성할 때는 데이터 행을 포함한 모든 행에 >가 붙어 있는지 반드시 확인하세요.
하이픈이 3개 미만이라서 안 된다는 것은 오해
일부 문서나 블로그에서는 "구분 행의 하이픈은 열마다 3개 이상이 필수"라고 설명하기도 하지만, GFM 사양에 최소 개수 규정은 없습니다. GitHub 공식 렌더러, marked 18.0.5, remark-gfm 4.0.1 모두에서 하이픈 1개(| - | - |)만으로도 표가 정상적으로 그려집니다(2026-07-15 실측, scripts/benchmarks/markdown-table-parsers/).
GitHub 공식 문서가 "3개 이상"으로 안내하는 반면, 사양에는 개수 규정이 없고 실제 구현은 1개도 받아들이는 차이가 있습니다. 3개로 맞추는 것은 가독성을 위한 관례일 뿐입니다. 하이픈 개수를 바꾸며 시간을 낭비하지 말고 열 수와 빈 줄을 먼저 확인하세요.
유일한 예외는 바깥 파이프를 생략하고 하이픈을 1개만 쓰는 조합이며, 이는 증상 4에서 설명합니다.
렌더러가 GFM 표를 지원하지 않음
표는 마크다운의 핵심 기본 사양이 아닙니다. 순수 CommonMark새 탭에서 열립니다 사양에는 표 문법 정의가 없으며, 표는 GFM(GitHub Flavored Markdown)의 확장 기능입니다. 표 확장을 적용하지 않은 엄격한 CommonMark 렌더러에서는 아무리 올바르게 작성해도 표로 변환되지 않습니다. 자세한 배경은 CommonMark와 GFM의 차이점에 정리되어 있습니다.
일부 블로그 플랫폼이나 레거시 CMS 중에는 지원하는 마크다운 문법이 제한되어 있어 표를 지원하지 않는 곳도 있습니다. 사용 중인 플랫폼의 도움말에서 표(테이블) 지원 여부를 확인하세요.
ChatGPT·Gemini 등 AI가 생성한 표가 코드 블록으로 붙여넣어짐
ChatGPT나 Gemini 등 생성형 AI가 출력한 마크다운 표를 복사할 때, 표 전체가 코드 펜스(줄 시작의 백틱 3개 ```)로 감싸진 채 붙여넣어져 표가 아닌 코드 블록으로 표시되는 사례가 있습니다(OpenAI Developer Community 보고새 탭에서 열립니다). 앞뒤의 백틱 3개 줄을 삭제하면 일반적인 GFM 표로 정상 인식됩니다.
증상 2: 열이 어긋나거나 셀이 제멋대로 나뉨
표 형태로 인식은 되었으나 열의 위치가 어긋나거나, 하나의 셀이어야 할 내용이 둘로 쪼개지는 경우입니다.
셀 안의 원본 파이프(|)
파이프 | 기호는 열을 구분하는 문자이므로 셀 내용 안에 그대로 쓰면 그 위치에서 열이 분리됩니다. 아래 표는 1열에 cmd1 | cmd2라는 명령어를 표시하려고 했지만 cmd1과 cmd2가 서로 다른 셀로 쪼개지고, 헤더의 열 수(2열)를 초과한 파이프로 연결은 오류 없이 잘려 나갑니다.
| 명령어 | 설명 |
| --- | --- |
| cmd1 | cmd2 | 파이프로 연결 |
\|(백슬래시 이스케이프) 또는 |(HTML 숫자 문자 참조)로 대체하면 하나의 셀에 정상적으로 들어갑니다.
| 명령어 | 설명 |
| --- | --- |
| cmd1 \| cmd2 | 파이프로 연결 |
인라인 코드(백틱) 안의 파이프도 보호되지 않음
직관과 달리 백틱으로 감싼 인라인 코드 영역 안에서도 파이프 기호는 보호되지 않습니다. 마크다운 파서에서 테이블 셀 분할(파이프 파싱)이 인라인 서식(백틱) 해석보다 먼저 실행되기 때문입니다.
| 명령어 | 설명 |
| --- | --- |
| `a | b` | 인라인 코드 영역 |
이 행은 `a와 b`라는 2개의 셀로 쪼개지며, 백틱 짝이 맞지 않아 문자 그대로 노출됩니다. GFM 테이블 확장 사양새 탭에서 열립니다은 셀 안에 파이프를 포함하려면 인라인 코드 스팬 안이라도 이스케이프가 필요하다고 규정하고 있습니다.
해결 방법은 인라인 코드 안에서도 백슬래시 이스케이프를 사용하는 것입니다.
`a \| b`처럼 인라인 코드 안에서도\|로 작성합니다. GitHub, marked, remark-gfm 모두에서a | b라는 코드 형태로 올바르게 그려집니다.|는 인라인 코드 안에서 사용할 수 없습니다. 백틱 안에서는 문자 참조가 변환되지 않아|라는 6글자가 그대로 표시됩니다.- 정리하자면 일반 셀 텍스트에서는
\|와|를 모두 쓸 수 있고, 인라인 코드 안에서는\|만 사용해야 합니다.
데이터 행의 열 수 과부족은 어긋남으로 나타남
데이터 행의 열 수가 헤더와 다르더라도 표 인식 자체가 깨지지는 않지만 외형의 어긋남으로 나타납니다. 실측 결과 열이 부족한 행은 빈 셀로 채워지고, 열이 많은 행은 초과분이 조용히 버려집니다. "마지막 열의 값이 사라졌다"고 느껴질 때는 해당 행의 앞부분에 불필요한 파이프(여분의 열)가 섞여 있지 않은지 확인하세요.
셀 값에 파이프나 특수 문자가 많은 데이터를 수작업으로 일일이 이스케이프하는 것은 번거롭습니다. 원본 데이터가 CSV나 스프레드시트에 있다면 CSV to Markdown 변환기에 붙여넣어 열 수 일치와 파이프 이스케이프가 자동으로 처리된 표를 만드는 편이 안전합니다.
열 어긋남의 원인이 원본 HTML 표의 셀 병합(rowspan / colspan)이라면 HTML 테이블을 마크다운 표로 변환하기에서 변환 시 처리 방식을 확인하세요.
증상 3: 셀 안에서 줄바꿈하면 표가 깨짐
마크다운 표 문법에는 셀 안 줄바꿈을 위한 별도 구문이 없습니다. 셀 작성 도중 Enter 키를 누르면 다음 줄은 새로운 행으로 인식되어 표가 끊기거나 아래 행으로 밀려납니다.
해결 방법은 셀 안에 HTML의 <br> 태그를 직접 넣는 것입니다.
| 항목 | 설명 |
| --- | --- |
| 설정 A | 1번째 줄<br>2번째 줄 |
다만 <br>은 마크다운 고유 문법이 아닌 원시 HTML이므로, 렌더러가 보안을 이유로 HTML 태그를 비활성화하거나 제거(sanitize)하는 환경에서는 동작하지 않습니다. 이 경우에는 셀 안 줄바꿈 대신 문장을 나누거나 행 자체를 분리하는 것이 현실적인 해결책입니다. 이스케이프와 줄바꿈 등 표 서식에 관한 대응표는 GFM 테이블 치트시트를 참고하세요.
증상 4: GitHub에서는 나오는데 다른 플랫폼에서 깨짐
동일한 마크다운 문서라도 파서에 따라 해석 결과가 달라질 수 있습니다. 실측을 통해 확인된 대표적인 차이는 "바깥 파이프 생략 + 하이픈 1개"의 조합입니다.
A | B
- | -
1 | 2
구분 행의 시작이 - (하이픈 + 공백)으로 시작하기 때문에 파서에 따라 이를 목록 기호로 해석할지 표로 해석할지가 갈립니다. GitHub과 remark-gfm은 이를 표로 보지 않고 목록으로 처리하며, marked는 표로 그립니다(2026-07-15 실측, scripts/benchmarks/markdown-table-parsers/).
바깥 파이프를 생략하는 방식을 쓴다면 하이픈을 최소 2개 이상(-- | --)으로 두세요. 행의 처음과 끝에 파이프를 붙여 두면(| A | B |) 파서에 관계없이 이 문제가 발생하지 않습니다.
"로컬 미리보기에서는 잘 나오는데 배포 대상 플랫폼(velog, Tistory, Notion 등)에서 깨진다"는 증상은 대개 이러한 파서 차이나 플랫폼의 GFM 지원 범위 차이에서 비롯됩니다. 플랫폼별 차이(Notion이 정렬 콜론이나 <br>을 지원하지 않는 등)가 의심된다면 Markdown to HTML 변환기로 표준 GFM HTML 출력을 비교해 보세요.
증상 5: 문법은 맞는데 특정 에디터나 환경에서만 안 나옴
문법을 모두 확인했는데도 해결되지 않는다면 마크다운 작성법이 아니라 렌더링하는 환경 자체를 의심해 보아야 합니다.
- VS Code Jupyter 확장: 마크다운 셀에 올바른 표를 작성해도 빈 화면으로 표시되는 사례가 보고된 바 있습니다(microsoft/vscode-jupyter #16043새 탭에서 열립니다). 아울러 셀 종류가 Code로 되어 있으면 마크다운이 렌더링되지 않으므로 Markdown 셀로 전환되었는지 확인하세요.
- Obsidian: 일부 버전에서 표 바로 앞에 빈 줄이 없으면 표를 그리지 않는 현상이 있습니다(Obsidian 포럼 보고새 탭에서 열립니다). 이는 증상 1에서 언급한 "표 직전의 빈 줄 누락"이 특정 에디터에서 발현된 구체적인 사례입니다.
- Prettier 등 코드 자동 포매터: 저장할 때마다 표의 서식을 자동으로 재구성하면서 줄바꿈이나 이스케이프를 깨뜨리는 경우가 있습니다(Atlassian Community 사례새 탭에서 열립니다). 포매터를 일시적으로 비활성화한 뒤 정상 표시되는지 확인하세요.
모든 구문 검사를 통과했다면 원인은 표 문법이 아니라 환경입니다. 에디터 업데이트, 확장 프로그램 설정 점검, 다른 뷰어에서 열기 등을 시도해 보세요.
고치는 것보다 다시 만드는 것이 빠를 때
행이 수십 줄인 깨진 표에서 파이프를 하나하나 세어가며 고치는 것보다, 원본 데이터에서 표를 다시 생성하는 편이 훨씬 빠릅니다. 원본 데이터가 CSV나 엑셀, 스프레드시트에 있다면 다음 3단계로 다시 만들 수 있습니다.
- 원본 데이터를 CSV 형식으로 복사합니다 (엑셀이나 스프레드시트의 셀 범위를 그대로 복사해도 됩니다).
- CSV to Markdown 변환기에 붙여넣습니다.
- 자동 생성된 마크다운 표를 복사해 깨진 표와 교체합니다.
열 수 일치, 파이프 이스케이프, 구분 행 생성이 모두 자동으로 처리됩니다. 모든 변환은 브라우저 안에서만 처리되고 데이터가 외부 서버로 전송되지 않으므로 사내 보안 데이터가 포함된 표도 안심하고 사용할 수 있습니다. CSV를 통한 변환 절차에 대한 자세한 내용은 CSV에서 마크다운 표 변환 가이드를, 변환 후의 표를 HTML로 변환하는 방법은 마크다운을 HTML로 변환하는 방법을 참고하세요.
자주 묻는 질문
마크다운 표가 일반 텍스트로 표시되는 가장 흔한 원인은 무엇인가요?
헤더 행과 구분 행의 열 수가 맞지 않는 경우가 가장 흔합니다. GFM 사양상 열 수가 다르면 파서는 오류 메시지 없이 표 인식을 포기하고 일반 문단으로 취급합니다. 구분 행의 열 수를 헤더에 맞추는 것만으로 대부분 해결됩니다.
셀 안에서 줄바꿈을 하려면 어떻게 해야 하나요?
마크다운 표 사양에는 줄바꿈 문법이 없으므로 HTML 태그인 <br>을 셀 내용 안에 직접 작성해야 합니다. 다만 원시 HTML을 제한하는 플랫폼에서는 작동하지 않을 수 있습니다.
인라인 코드(백틱) 안의 파이프 |는 왜 표를 깨뜨리나요?
마크다운 파서는 인라인 코드 서식을 해석하기 전에 먼저 파이프 기호를 기준으로 셀을 분할하기 때문입니다. 백틱 안이라도 파이프를 셀 내용으로 표시하려면 반드시 \|로 이스케이프해야 합니다.
표 바로 앞에 빈 줄은 꼭 넣어야 하나요?
일부 파서나 에디터(Obsidian 등)는 이전 문단과 표 사이에 빈 줄이 없으면 표를 문단의 연속으로 간주해 표로 렌더링하지 않습니다. 표 앞뒤에 빈 줄을 1줄씩 두는 것이 가장 안전합니다.
관련 글
정리 — 진단 순서만 기억하기
마크다운 표가 표시되지 않거나 깨질 때는 다음 순서로 점검하세요.
- 표가 아예 안 나올 때: 헤더 행과 구분 행의 열 수 일치 확인 → 표 직전 빈 줄 추가 → 렌더러의 GFM 지원 여부 확인
- 열이 어긋나거나 쪼개질 때: 셀 안의 파이프 기호(
\|로 이스케이프) 확인 → 인라인 코드 안 파이프 점검 → 데이터 행 열 수 확인 - 하이픈 개수: 바깥 파이프가 있다면 하이픈 1개로도 정상 작동하므로 개수 조절에 시간을 쓰지 않아도 됨
표 파싱 동작을 검증하고 싶다면 Markdown to HTML 변환기로 브라우저 내에서 HTML 태그 생성을 확인하고, 표를 깔끔하게 다시 작성하고 싶다면 CSV to Markdown 변환기를 활용해 보세요.