마크다운 표(테이블) 만들기 - 문법·정렬·줄바꿈 총정리

결론부터

마크다운 표는 파이프 기호 |와 하이픈 -만으로 만들 수 있습니다.

| 이름 | 이메일 | 권한 |
| --- | --- | --- |
| 김민준 | minjun@example.com | admin |
| 이서연 | seoyeon@example.com | viewer |

직접 쓰기 번거롭다면 CSV to Markdown 변환기에 CSV를 붙여넣으면 바로 변환됩니다. 아래에서 문법을 자세히 살펴봅니다.

기본 문법 — 파이프와 하이픈

마크다운 표(테이블)는 세 부분으로 구성됩니다.

1. 헤더 행 — 열 이름을 파이프 |로 구분
2. 구분 행 — 하이픈 -을 나열해 헤더와 데이터를 분리(3개씩 쓰는 것이 관례)
3. 데이터 행 — 각 셀을 파이프로 구분

| 항목 | 값 |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

행의 처음과 끝의 파이프는 생략할 수 있지만 가독성을 위해 붙이는 것이 일반적입니다. 열별로 너비를 맞출 필요는 없습니다. 렌더링할 때 자동으로 조정됩니다.

파이프와 구분 행의 구조

파이프 기호 |는 열을 구분하는 기호입니다. 구분 행(헤더 구분 행, 대시 행이라고도 합니다)은 하이픈 -으로 구성되며 헤더와 데이터의 경계를 렌더러에 알려 줍니다.

파이프와 하이픈에 관해 알아 둘 규칙은 다음과 같습니다.

• 열마다 하이픈 3개(---)를 쓰는 것은 관례일 뿐 파서의 규칙이 아닙니다. GFM 사양에 최소 개수 규정은 없으며 --나 - 1개로도 GFM 렌더러는 표로 그립니다(marked 18.0.5 / remark-gfm 4.0.1에서 검증). 3개로 맞추는 것은 가독성을 위해서입니다
• 실제로 표를 깨뜨리는 것은 헤더 행과 구분 행의 열 수 불일치입니다. GFM 사양에 명시된 대로 열 수가 일치하지 않으면 표로 인식되지 않습니다
• 행의 처음과 끝의 파이프는 생략 가능합니다. | A | B |와 A | B는 같은 방식으로 그려집니다
• 정렬 콜론(:---, :---:, ---:)을 둘 수 있는 곳은 구분 행뿐입니다. 데이터 행에는 쓰지 않습니다
• GFM에서는 헤더 행이 필수입니다. CommonMark 핵심 사양에는 표 정의 자체가 없으므로 헤더 없는 표는 독자 확장에서만 존재합니다

표가 렌더링되지 않는다면 가장 먼저 헤더 행과 구분 행의 열 수를 확인하세요. 여기가 일치하지 않으면 표로 전혀 인식되지 않습니다. 그다음으로 많은 원인은 표 앞의 빈 줄 누락이며, 하이픈 개수가 원인이 되는 일은 거의 없습니다.

정렬 지정 — 왼쪽·가운데·오른쪽

구분 행에 콜론 :을 추가하면 열 정렬을 제어할 수 있습니다.

| 상품 | 수량 | 단가 |
| :--- | :---: | ---: |
| 사과 | 3 | 1200 |
| 귤 | 10 | 800 |

숫자 열을 오른쪽 정렬하면 자릿수가 맞춰져 읽기 쉬워집니다.

GFM(GitHub Flavored Markdown)에서의 동작

GitHub, GitLab, Notion, Obsidian, velog, Tistory 등 주요 플랫폼은 GitHub Flavored Markdown(GFM)의 표 문법을 지원합니다. 위에서 소개한 문법을 그대로 사용할 수 있습니다.

GFM 표에서 기억해 두면 좋은 점을 정리합니다.

• 헤더 행은 필수. 헤더 없는 표는 GFM에서 만들 수 없음
• 구분 행의 하이픈은 3개(---) 나열이 관례. 사양상으로는 그보다 적어도 유효
• 셀 안에서 인라인 서식(코드, 링크, 취소선 등)을 사용할 수 있음
• 표 앞뒤에 빈 줄을 넣지 않으면 파서가 표로 인식하지 못하는 경우가 있음

플랫폼별 파이프 표 지원

표의 3가지 기본 요소, 즉 파이프 | 표, 구분 행의 콜론 정렬(:---), 셀 안 줄바꿈용 <br>은 플랫폼에 따라 지원 상황이 다릅니다.

표에 관한 참고 사항입니다.

• GitHub는 GitHub Flavored Markdown 사양의 Tables (extension) 섹션새 탭에서 열립니다에 따라 파이프 표와 구분 행의 콜론 정렬을 정의합니다. 셀은 인라인 콘텐츠로 해석되므로 <br> 같은 인라인 HTML이 허용되며, GitHub는 이를 셀 안 줄바꿈으로 그립니다.
• GitLab Flavored Markdown도 같은 파이프 표와 정렬 문법을 문서화하고 있으며, 셀 안에서 여러 줄을 만들기 위해 <br> 태그를 쓸 수 있다고 공식 문서에 명시되어 있습니다.
• Obsidian은 파이프 표와 콜론 정렬을 지원하며 실제로 <br> 태그를 셀 안 줄바꿈으로 그립니다.
• Notion은 파이프 표를 가져오거나 붙여넣을 수 있지만 GFM으로 그리는 대신 자체 표 블록으로 변환합니다. Notion 표에는 열별 정렬이 없으므로 정렬 콜론(:---)은 외형에 영향을 주지 않고, 셀 안 <br>도 줄바꿈으로 그려지지 않습니다.

구체적인 규칙은 GitHub Flavored Markdown 사양의 Tables (extension) 섹션새 탭에서 열립니다에 정의되어 있습니다. 순수 CommonMark새 탭에서 열립니다에는 표 문법 정의가 없으므로 표는 기술적으로 GFM의 확장 기능입니다. CommonMark만 엄격하게 구현하고 확장을 채택하지 않는 렌더러에서는 표로 표시되지 않습니다.

구분 행의 실제 동작 — 4개 렌더러 검증 (GitHub / marked / remark-gfm / CommonMark)

GFM Tables 확장은 구분 행을 "내용이 하이픈(-)뿐이고 앞이나 뒤에 콜론(:)을 둘 수 있는 셀"이라고 정의할 뿐, 하이픈의 최소 개수는 어디에도 적혀 있지 않습니다. GitHub 자체 문서는 "각 열에 하이픈 3개 이상"이라고 설명하지만 사양에 그런 규칙은 없고, GitHub 렌더러는 1개도 받아들입니다. 사양 자체의 정렬 예시도 하이픈 1개짜리 :-:를 사용합니다.

이 주장을 확정하기 위해 같은 엣지 케이스 묶음을 GitHub의 실제 렌더러(Markdown API 경유), marked, remark-gfm, 확장 없는 엄격한 CommonMark 파이프라인에 통과시켰습니다. 재현 스크립트는 저장소의 scripts/benchmarks/markdown-table-parsers/에 있습니다. 2026-07-15 측정, marked 18.0.5 / remark-gfm 4.0.1 / remark-parse 11.0.0:

주목할 만한 발견이 3가지 있습니다.

• 하이픈의 개수는 표로 그려지는지 여부를 좌우하지 않습니다. GitHub / marked / remark-gfm에서 1개는 3개와 완전히 같게 동작하며, "3개"는 가독성을 위한 관례이지 요건이 아닙니다
• 유일한 실질적인 파서 차이는 표의 아래에서 두 번째 행에 있습니다. 바깥 파이프를 생략하고 하이픈을 1개로 두면 구분 행이 - 로 시작하는데, GitHub과 remark-gfm은 이것을 목록 마커로 읽고 marked는 표로 처리합니다. 바깥 파이프를 생략한다면 하이픈은 2개 이상 남겨 두세요
• 어떤 렌더러에서든 확실하게 표가 깨지는 것은 구분 행의 열 수가 헤더와 일치하지 않을 때입니다. 표로 인식되지 않고 문단으로 폴백되며 오류 메시지도 나오지 않습니다

파이프와 특수 문자 이스케이프

셀 안에 파이프 |를 그대로 쓰면 열 구분으로 오인되어 표가 깨집니다. 안전하게 쓰는 방법은 두 가지입니다.

| 명령어 | 의미 |
| --- | --- |
| cmd1 \| cmd2 | 백슬래시로 이스케이프 |
| cmd1 | cmd2 | HTML 엔티티로 표기 |

• \|(백슬래시 이스케이프)는 GitHub, GitLab, Notion, Obsidian, velog 등 주요 GFM 렌더러에서 동작합니다
• |(HTML 숫자 문자 참조)는 렌더러가 \|를 제대로 처리하지 못할 때의 대안으로 안전하며, 에디터 간에 복사해도 잘 깨지지 않는 것이 장점입니다

셀 안에서 백슬래시 자체를 표시하고 싶다면 \\로 씁니다. 줄바꿈 없는 공백을 넣고 싶다면  를 사용합니다.

자주 빠지는 함정

셀 안 줄바꿈

마크다운 표 사양상 셀 안에서 줄바꿈은 할 수 없습니다. 꼭 줄바꿈을 넣고 싶다면 HTML 태그 <br>을 직접 쓰는 방법이 있지만, 플랫폼에 따라 지원되지 않을 수 있습니다.

빈 셀

셀을 비우고 싶을 때는 파이프 사이에 공백만 넣습니다. 파이프를 연속으로 써도 문제없지만 공백을 끼우는 쪽이 읽기 쉽습니다.

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

열 수 불일치

헤더가 3열인데 데이터 행이 2열뿐이라면 대부분의 파서는 부족한 부분을 빈 셀로 처리합니다. 반대로 데이터 행이 많으면 잘립니다. 열 수는 맞춰 두는 것이 안전합니다.

데이터가 많다면 CSV에서 자동 생성

5행 정도라면 직접 써도 충분하지만, 20행이 넘는 데이터나 열이 많은 표는 손으로 만들면 시간이 걸립니다. 엑셀이나 스프레드시트의 데이터를 CSV로 복사해 CSV to Markdown 변환기에 붙여넣으면 파이프 정렬이나 이스케이프 처리를 신경 쓰지 않고 한 번에 변환할 수 있습니다.

변환된 마크다운 표를 HTML로 바꾸고 싶다면 Markdown to HTML 변환기를, 기존 HTML에서 마크다운 표를 추출하고 싶다면(복사한 웹 페이지, Notion 내보내기, CMS 덤프 등) HTML to Markdown 변환기를 활용하세요.

자주 묻는 질문

헤더 없는 마크다운 표를 만들 수 있나요?

GFM에서는 헤더 행이 필수입니다. 헤더가 필요 없는 경우에도 빈 헤더 행과 구분 행을 써야 합니다.

셀 안에 링크나 이미지를 넣을 수 있나요?

인라인 마크다운([텍스트](URL)이나 ![alt](이미지URL))은 셀 안에서 사용할 수 있습니다. 다만 표가 가로로 너무 길어지면 가독성이 떨어지므로 링크 정도로 제한하는 것이 현실적입니다.

표의 열 너비를 지정할 수 있나요?

마크다운 사양에는 열 너비 지정 방법이 없습니다. 렌더링할 때 내용에 따라 자동 조정됩니다. 세밀하게 제어하고 싶다면 HTML의 <table>을 써야 합니다.

정리

마크다운 표(테이블) 문법은 단순해서 파이프와 하이픈만 기억하면 손쉽게 표를 만들 수 있습니다. 정렬 지정이나 이스케이프 같은 세부 규칙도 있지만 기본만 익혀 두면 곤란할 일은 없습니다.

행이 많은 데이터를 다룰 때는 CSV to Markdown 변환기에 CSV를 붙여넣기만 하면 되는 변환을 추천합니다. 손으로 쓰는 수고를 덜고 정확한 마크다운 표를 만들 수 있습니다.