깃허브 마크다운 표(GFM Table) 문법 치트시트 - 정렬·줄바꿈·병합

TL;DR — GFM 테이블 치트시트

GFM(GitHub Flavored Markdown) 테이블은 GitHub 사양에서 정의된 파이프(|) 구분 표로, 순수 CommonMark 핵심 사양에는 포함되지 않는 확장 기능입니다.

• 표는 헤더 행, 구분 행(---, 각 열에 3개씩 배치하는 것이 관례), 데이터 행을 파이프 |로 구분해 작성합니다. 표 앞뒤에는 반드시 빈 줄이 필요합니다.
• 정렬은 구분 행의 콜론 위치로 지정합니다: :--- 왼쪽 정렬 / :---: 가운데 정렬 / ---: 오른쪽 정렬.
• 셀 안의 파이프 기호는 백슬래시로 이스케이프(\|)하며, 지원되지 않는 환경에서는 HTML 엔티티 |를 폴백으로 사용합니다.
• 셀 안 줄바꿈은 <br> 태그를 직접 작성합니다. GitHub와 GitLab에서는 정상 동작하지만, Obsidian이나 Notion 등은 편집 모드나 가져오기 경로에 따라 결과가 다를 수 있습니다.
• 셀 병합(rowspan/colspan), 여러 문단, 코드 블록 등의 블록 요소는 GFM 테이블에서 사용할 수 없습니다. 이러한 서식이 필요하다면 HTML <table>로 전환해야 합니다.
• 직접 파이프를 입력하기 번거롭다면 CSV to Markdown에 CSV 데이터를 붙여넣는 것만으로 GFM 호환 표가 즉시 생성됩니다.

이 글은 마크다운 표 문법을 이미 어느 정도 알고 있는 사용자가 필요한 구문을 빠르게 확인하기 위한 치트시트입니다. 표 작성을 기초부터 차례대로 배우고 싶다면 마크다운 표(테이블) 만들기를 먼저 참고하세요.

GFM 테이블에서 가능한 것과 불가능한 것

블록 요소나 셀 병합이 필요할 때는 마크다운 대신 HTML <table> 태그를 직접 작성합니다.

기본 구조 — 최소 쌍으로 확인

GFM 테이블은 헤더 행, 구분 행, 데이터 행의 세 부분으로 구성됩니다. 구분 행의 하이픈은 열마다 3개를 쓰는 것이 관례이며(GFM 사양에 최소 개수 규정은 없음), 행의 처음과 끝에 위치한 파이프는 생략할 수 있습니다.

문법:

| 이름 | 권한 |
| --- | --- |
| 김민준 | admin |
| 이서연 | viewer |

결과:

가장 작은 표(헤더 1행 + 데이터 1행)는 다음과 같이 작성합니다.

| key | value |
| --- | --- |
| name | FormatArc |

정렬 문법 요약 표

구분 행에서 콜론(:)의 위치에 따라 각 열의 정렬 방식을 지정합니다.

문법:

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

결과:

숫자 데이터를 담은 열을 오른쪽 정렬하면 자릿수가 깔끔하게 맞아 가독성이 높아집니다.

셀 안에서 사용할 수 있는 서식

셀 내부에서는 인라인 요소를 사용할 수 있습니다. 코드 블록, 글머리 기호 목록, 여러 줄 문단과 같은 블록 요소는 사용할 수 없습니다.

셀 안에 이미지를 넣을 수는 있지만, 표가 세로로 길어져 레이아웃이 깨지기 쉬우므로 작은 아이콘 수준으로 제한하는 것이 실무적으로 안전합니다.

빈 셀(블랭크 셀) 작성법

셀을 빈칸으로 두는 것은 유효한 문법입니다. 파이프 사이에 아무것도 작성하지 않으면 해당 셀은 공백으로 렌더링됩니다.

문법:

| 이름 | 권한 | 비고 |
| --- | --- | --- |
| 김민준 | admin | |
| 이서연 | | viewer |

결과:

빈 셀을 다룰 때 주의할 점은 다음 두 가지입니다.

• 열 개수를 헤더와 반드시 일치시켜야 합니다. 빈 셀은 | |(파이프 2개 사이가 비어 있는 형태)을 의미하며, 파이프 자체를 누락하는 것이 아닙니다. 파이프 개수를 줄이면 열이 모자라 표 전체가 깨집니다.
• 행의 첫 번째 셀이 비어 있고 행 머리의 파이프마저 생략하면, 렌더러에 따라 첫 번째 열을 누락된 것으로 오인할 수 있습니다. 행 머리의 |를 유지하거나(| | 값 |), 안전장치로 빈 링크 []()를 넣어 두면 열 누락을 방지할 수 있습니다.

빈 셀은 셀 병합이 아닙니다. GFM에는 rowspan이나 colspan이 없으므로 빈 셀은 단지 빈 공간일 뿐이며, 위나 옆의 셀과 시각적으로 합쳐지지 않습니다. 병합이 필요하다면 HTML <table>로 전환해야 합니다.

파이프·특수 문자 이스케이프 요약

셀 안에 파이프 기호 |를 그대로 쓰면 열 구분자로 오인되어 테이블 레이아웃이 깨집니다. 안전하게 작성하는 방법은 두 가지가 있습니다.

문법:

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

결과:

그 외에도 백슬래시 자체를 표시하고 싶다면 \\를, 줄바꿈 없는 공백을 넣고 싶다면  를 사용합니다. CSV나 HTML 데이터에서 마크다운 표를 생성할 때는 CSV to Markdown이나 HTML to Markdown 도구를 사용하면 파이프 이스케이프가 자동으로 처리됩니다.

셀 안 줄바꿈과 플랫폼별 지원 여부

마크다운 표 사양상 셀 내부에서 키보드의 Enter로 일반 줄바꿈을 넣을 수 없습니다. 셀 안에서 줄을 바꾸려면 HTML 태그 <br>을 직접 작성해야 합니다. 다만 플랫폼별로 지원 차이가 존재합니다.

줄바꿈이 많이 필요한 복잡한 표라면 GFM 테이블에 억지로 맞추기보다 HTML <table>을 사용하거나 열을 나누어 설계하는 것이 안전합니다.

표가 깨지는 원인과 체크리스트

표가 올바르게 렌더링되지 않고 텍스트로 노출될 때는 다음 항목을 순서대로 점검하세요.

• 표 앞뒤에 빈 줄이 있는가 — 이전/다음 줄과 붙어 있으면 파서가 표로 인식하지 못하는 경우가 많습니다 (특히 GitHub에서 중요).
• 헤더 행이 존재하는가 — GFM에서는 헤더 행이 필수입니다. 헤더 텍스트가 필요 없더라도 빈 헤더 행과 구분 행을 작성해야 합니다.
• 헤더 행과 구분 행의 열 수가 일치하는가 — 이 두 행의 열 수가 다르면 파서가 표 자체를 인식하지 않습니다. 하이픈의 개수(--나 ---)는 오류의 원인이 되지 않습니다.
• 헤더, 구분 행, 데이터 행의 열 수(파이프 개수)가 일치하는가 — 데이터 행의 열이 부족하면 빈 셀로 채워지고, 넘치면 잘려 나갑니다.
• 셀 내부에 이스케이프되지 않은 파이프 |가 있는가 — 있는 경우 \| 또는 |로 변경합니다.
• 행 머리에 불필요한 들여쓰기(공백 4칸 이상)가 있는가 — 코드 블록으로 오인될 수 있습니다.
• 셀 내부에 코드 블록이나 글머리 기호 목록 등 블록 요소를 넣지 않았는가 — GFM 테이블에서는 인라인 서식만 허용됩니다.

체크리스트로 해결되지 않는 문제는 마크다운 표가 안 나오거나 깨질 때 증상별 해결법에서 자세한 대처 방법을 다룹니다.

CSV / HTML / JSON에서 테이블 자동 생성하기

5행 이내의 작은 표라면 직접 작성해도 충분하지만, 데이터가 20행을 넘어가거나 열이 많은 표는 수작업 시 파이프 정렬이나 이스케이프 누락 실수가 발생하기 쉽습니다. 원본 데이터 형식에 맞는 FormatArc 변환 도구를 활용하면 한 번에 GFM 호환 마크다운 표를 만들 수 있습니다.

• CSV / 스프레드시트 / Excel 데이터: CSV to Markdown에 붙여넣고 실행하면 즉시 파이프 테이블로 변환됩니다. 자세한 절차는 CSV를 마크다운 표로 변환하는 방법, README에 표를 넣는 방법은 GitHub README 표 만들기를 참고하세요.
• 기존 HTML(웹 페이지 표, Notion 내보내기, CMS 덤프 등): HTML to Markdown에 HTML 코드를 넣으면 <table> 태그가 마크다운 파이프 표로 추출됩니다. 자세한 내용은 HTML 마크다운 변환 가이드를 참고하세요.
• JSON(API 응답이나 로그 데이터): CSV 형식으로 먼저 변환한 뒤 CSV to Markdown에 전달하는 방식이 가장 확실합니다. 세부 변환 절차는 JSON to Markdown Table 변환 방법을 참고하세요.
• 완성된 마크다운 표를 마크다운을 지원하지 않는 CMS나 HTML 이메일에 붙여넣어야 한다면 Markdown to HTML로 변환해 사용합니다. 변환 절차는 마크다운 HTML 변환 방법을 참고하세요.

FormatArc의 모든 처리는 브라우저 내부에서 로컬로 완료되므로, 사내 데이터나 고객 정보가 포함된 텍스트를 붙여넣어도 외부 서버로 전송되지 않습니다. 별도의 회원가입이나 파일 업로드도 필요하지 않습니다.

생성된 표를 LLM 프롬프트에 전달할 때도 마크다운 표는 동일한 내용의 HTML보다 토큰 소모량이 적고 가독성이 높아 파싱 정확도를 유지하는 데 유리합니다. 실측한 토큰 수와 정확도 비교는 LLM 입력에 Markdown vs HTML 비교를 참고하세요.

마크다운 표로 불가능한 것 — HTML로 전환하는 기준

다음과 같은 요구사항이 있는 표는 GFM 테이블로 구현할 수 없으므로, 마크다운 문서 안에 HTML <table> 태그를 직접 작성하는 방식을 사용해야 합니다.

• 행 또는 열 단위의 셀 병합(rowspan, colspan)이 필요한 경우
• 셀 안에 글머리 기호 목록, 여러 문단, 코드 블록을 넣어야 하는 경우
• 열 너비를 픽셀이나 비율(%)로 고정해야 하는 경우
• 표 내부에 제목이나 다른 표를 중첩해야 하는 경우

다만 GitHub 등에서는 보안상의 이유로 표 내부 HTML 속성을 엄격하게 제한합니다. <br>은 허용되지만 <span style="...">의 style 속성은 태그만 남고 속성 자체가 제거되므로, 글자 색상이나 폰트 크기 변경은 적용되지 않습니다.

GFM이 셀 병합(rowspan / colspan)을 지원하지 않는 이유

GFM 사양의 Tables (extension)새 탭에서 열립니다은 파이프 구분 문법에서 "1줄 = 1행(row)" 구조를 ABNF 문법 수준에서 엄격하게 요구합니다. 이로 인해 여러 줄에 걸친 셀 병합을 표현할 문법적 여지가 구조적으로 없습니다. 이는 텍스트 자체의 가독성과 파서 구현의 단순함을 우선시한 설계이며, 이후 CommonMark 확장 논의에서도 동일하게 유지되었습니다. 따라서 병합이 필요한 표는 GFM의 범위를 벗어난 것으로 간주하고 HTML <table>을 직접 사용하는 것이 실무적인 정답입니다.

HTML <table>로 병합하는 최소 코드 예제

마크다운 파일 내에 HTML 태그를 그대로 작성하면 GitHub를 비롯한 대부분의 GFM 렌더러는 이를 HTML 표로 렌더링합니다.

열 방향 병합 (colspan):

<table>
  <tr><td colspan="2">기간 (2026)</td></tr>
  <tr><td>4월</td><td>9월</td></tr>
</table>

행 방향 병합 (rowspan):

<table>
  <tr><td rowspan="2">프로젝트 A</td><td>킥오프</td></tr>
  <tr><td>납품</td></tr>
</table>

GitHub가 허용하는 HTML 속성과 제거하는 속성

GitHub는 보안(XSS 방지)을 위해 표 내부의 HTML을 살균(sanitize) 처리하며, 허용 목록에 없는 속성은 속성 자체가 삭제됩니다. 다음 표는 GitHub의 마크다운 렌더링 API(README 및 이슈 본문과 동일한 파이프라인)에 실제로 통과시켜 측정한 결과입니다(측정 스크립트는 저장소의 scripts/benchmarks/github-table-attributes/에 위치).

글자 색상이나 크기로 특정 셀을 강조하고 싶다면 표 외부에 뱃지나 다이어그램을 배치하거나, 마크다운의 **굵은 글씨**를 활용하거나, 표를 이미지로 캡처해 첨부하는 방식을 선택해야 합니다.

GFM 이외의 셀 병합 확장 문법 (GitHub에서는 미지원)

GitHub에서는 지원되지 않지만, 로컬 마크다운 프리뷰나 특정 도구 환경에서는 다음과 같은 독자 확장 문법을 지원하기도 합니다.

• VS Code 확장 Markdown Preview Enhanced새 탭에서 열립니다 — >로 위쪽 셀 병합, ^로 왼쪽 셀 병합
• Python-Markdown 확장 mdx_tableau새 탭에서 열립니다 — 마크다운 문법 내에서 colspan/rowspan 표현
• Pandoc grid table / multiline table새 탭에서 열립니다 — +---+---+ 격자 형태로 병합 표현 가능

하지만 GitHub README나 Issue에서 완벽하게 렌더링되도록 하려면 이러한 도구 전용 확장에 의존하지 않고 표준 HTML <table>을 직접 작성하는 것이 가장 안전합니다.

CommonMark와 테이블의 관계

순수 CommonMark새 탭에서 열립니다 사양에는 표 문법 정의가 존재하지 않습니다. 파이프 구분 테이블은 GitHub Flavored Markdown 사양의 Tables (extension) 섹션새 탭에서 열립니다에서 정의된 GFM 전용 확장 기능입니다. 따라서 CommonMark 핵심 사양만 엄격하게 구현하고 테이블 확장을 포함하지 않은 파서에서는 | col | 구문이 표가 아닌 일반 문자열로 출력됩니다. 사용 중인 환경이 GFM 테이블을 지원하는지 확인하려면 간단한 3행짜리 표를 먼저 작성해 테스트해 보는 것이 좋습니다.

자주 묻는 질문

가장 작은 마크다운 표는 어떻게 작성하나요?

헤더 행 1줄, 구분 행 1줄, 데이터 행 1줄의 총 3줄이 최소 단위입니다. | key | value | 아래에 | --- | --- |를 두고, 그 아래에 | name | FormatArc | 형태로 작성합니다. 구분 행의 하이픈은 열마다 3개(---)를 배치하는 것이 관례이지만 GFM 사양상 1개만 있어도 유효합니다.

셀을 빈칸으로 두려면 어떻게 하나요?

두 파이프 사이에 공백을 두면 빈 셀이 됩니다(| 값 | |). 열 개수를 헤더와 동일하게 유지해야 하므로, 빈 셀은 | | 형태여야 하며 파이프 자체를 생략해서는 안 됩니다. 빈 셀이 행의 맨 앞에 위치할 때는 행 머리의 파이프를 반드시 남겨야(| | 값 |) 일부 렌더러에서 첫 열이 유실되는 현상을 방지할 수 있습니다.

\|와 | 중 어느 것을 써야 하나요?

기본적으로 백슬래시 이스케이프 \|를 우선 사용합니다. GitHub 공식 사양에 명시되어 있으며 대다수의 GFM 렌더러에서 정상 동작합니다. 특정 렌더러가 \|를 제대로 인식하지 못하거나 에디터 간 복사·붙여넣기 과정에서 문자가 손상되는 환경이라면 폴백으로 |를 사용하세요.

셀 안에서 글자 색상이나 크기를 변경할 수 있나요?

GFM 테이블만으로는 변경할 수 없습니다. GitHub를 포함한 주요 플랫폼은 보안을 위해 표 내부의 style 속성을 필터링하므로, <span style="...">을 작성해도 스타일이 무시됩니다. 서식 지정이 반드시 필요하다면 별도의 다이어그램이나 HTML 렌더링 환경을 검토해야 합니다.

표의 열 너비 기준이 있나요?

마크다운에는 열 너비를 직접 지정하는 문법이 없으며, 렌더러가 셀 내용의 길이에 맞추어 자동으로 조절합니다. 실무적으로 PC와 모바일 환경을 모두 고려한다면 열 수를 5~6개 이내로 유지하는 것이 좋습니다. 그 이상 늘어나면 가로 스크롤이 발생해 가독성이 떨어집니다.

셀 병합(rowspan / colspan)을 할 수 있나요?

GFM 테이블 문법 자체로는 불가능합니다. 셀 병합이 필요한 표는 마크다운 문서 안에 HTML <table> 태그를 직접 작성해야 합니다.

표가 그려지지 않고 | col | 텍스트 그대로 나옵니다. 왜 그런가요?

가장 흔한 원인은 표 앞뒤의 빈 줄 누락, 헤더 행 누락, 헤더 행과 구분 행의 열 수 불일치, 또는 렌더러가 GFM 테이블 확장을 지원하지 않는 순수 CommonMark 환경인 경우입니다. 본문의 "표가 깨지는 원인과 체크리스트"를 확인하세요.

정리

GFM 마크다운 표는 파이프(|)와 하이픈(-)을 이용해 간결하게 표를 작성할 수 있는 유용한 도구입니다. 정렬 지정, 파이프 이스케이프, 빈 셀 처리 등의 기본 규칙만 숙지하면 GitHub README나 문서 작성 시 깔끔한 표를 손쉽게 구성할 수 있습니다.

행 수가 많거나 복잡한 스프레드시트 데이터를 다룰 때는 CSV to Markdown 변환기를 활용해 자동으로 마크다운 표를 생성하면 입력 실수와 작업 시간을 크게 줄일 수 있습니다.