마크다운 표에서 파이프·줄바꿈 때문에 열이 깨질 때 고치는 방법
마크다운 표의 셀 값에 들어가는 파이프는 `\|`로 이스케이프하고, 셀 안에서 줄을 바꾸려면 대상 렌더러가 허용하는 경우 `<br>`을 사용하세요. 헤더 행과 구분 행의 열 수부터 맞춘 뒤 실제 게시 환경에서 미리보기해야 표가 예기치 않게 갈라지는 것을 막을 수 있습니다.
표의 세로선은 보기에는 단순한 장식이지만 파서는 열 경계로 읽습니다. 제품명 `A | B`, 셸 명령, 여러 줄 설명처럼 구분자가 데이터 안에 들어오면 원본과 렌더링 결과를 함께 보며 문법 경계부터 정리해야 합니다.
먼저 보는 핵심 요약
- 헤더와 구분 행의 파이프 배치를 먼저 고정하면 이후 행에서 열 수가 어긋난 위치를 찾기 쉽습니다.
- 셀 내용의 리터럴 파이프는 역슬래시로 이스케이프하고 코드 서식만으로 보호된다고 가정하지 않습니다.
- 셀 내부 줄바꿈은 구현별 차이가 있으므로 `<br>` 지원 여부와 HTML 정리 정책을 게시 환경에서 확인합니다.
파이프 하나가 새 열로 해석되는 이유
GFM 표는 헤더 행, 구분 행, 데이터 행의 파이프를 열 경계로 사용합니다. 셀 값에 포함된 파이프도 이스케이프하지 않으면 같은 경계로 읽힐 수 있습니다. 행마다 앞뒤 파이프를 쓰는지는 선택할 수 있지만, 한 표 안에서는 열 구조를 일관되게 유지해야 오류 위치를 찾기 쉽습니다.
리터럴 파이프를 안전하게 넣는 방법
셀에 문자 자체를 표시하려면 `\|`처럼 역슬래시로 이스케이프합니다. 코드 조각 안의 파이프도 렌더러가 표를 먼저 나누는 경우가 있으므로 실제 대상에서 확인해야 합니다. 변환기가 만든 결과를 다시 편집할 때 역슬래시가 자동 제거되지 않았는지도 살펴보세요.
셀 안 줄바꿈을 표현할 때 생기는 차이
마크다운 원문에서 줄을 그대로 나누면 다음 행이나 표 바깥 문단으로 해석될 수 있습니다. GitHub처럼 인라인 HTML을 허용하는 환경에서는 `<br>`이 실용적이지만, 보안 필터가 HTML을 제거하는 게시판에서는 한 줄 문장이나 목록 바깥 설명으로 바꾸는 편이 안전합니다.
정렬 표시와 열 개수를 함께 검수하는 법
구분 행의 하이픈은 각 열에 필요하고 콜론은 왼쪽·오른쪽·가운데 정렬을 나타냅니다. 정렬 콜론을 추가하다 파이프를 빠뜨리면 뒤 셀이 한 칸씩 밀릴 수 있습니다. 헤더부터 마지막 행까지 열 개수를 세고, 긴 내용은 렌더링 폭까지 확인하세요.
단계별로 확인하는 방법
- 헤더 구조 고정하기
헤더와 구분 행의 열 개수 및 정렬 콜론을 먼저 맞춥니다.
- 셀 안 파이프 이스케이프하기
데이터로 표시할 파이프를 찾아 `\|`로 바꾸고 누락된 위치가 없는지 확인합니다.
- 줄바꿈 방식 선택하기
대상 서비스가 인라인 HTML을 허용하면 `<br>`을 쓰고, 허용하지 않으면 셀 문장을 한 줄로 정리합니다.
- 게시 환경에서 렌더링하기
생성기 미리보기뿐 아니라 실제 README, 위키, 게시판에 붙여 열과 줄바꿈을 최종 검수합니다.
판단 기준을 한눈에 비교하기
| 확인 항목 | 판단 기준 |
|---|---|
| 셀 값의 `|` | `\|`로 이스케이프해 열 구분자가 아니라 문자로 처리합니다. |
| 원문의 실제 개행 | 표 행이 끝난 것으로 해석될 수 있어 셀 내부 용도로 바로 쓰지 않습니다. |
| `<br>` | 인라인 HTML을 허용하는 렌더러에서 셀 내부 시각적 줄바꿈으로 사용할 수 있습니다. |
| 구분 행의 `:` | 하이픈 양끝의 위치로 열 정렬을 지정하며 열 개수에는 포함되지 않습니다. |
실행 전 체크리스트
- 헤더와 구분 행의 열 개수가 같나요?
- 셀 데이터의 모든 파이프를 이스케이프했나요?
- 대상 렌더러가 `<br>`과 인라인 HTML을 허용하나요?
- 모바일 폭에서도 긴 셀이 읽을 수 있게 표시되나요?
주의할 점
Markdown 표 기능은 모든 Markdown 구현에 공통인 핵심 문법이 아닙니다. GFM에서 보이는 결과가 다른 위키나 편집기에서는 달라질 수 있으므로, 중요한 문서는 대상 시스템의 표 지원과 HTML 필터 정책을 기준으로 검수하세요.
함께 보면 좋은 글
자주 묻는 질문
표의 맨 앞과 맨 뒤 파이프는 꼭 필요한가요?
GFM에서는 생략할 수 있지만 열 구조를 눈으로 확인하기 쉽게 한 표 안에서는 같은 스타일을 유지하는 편이 좋습니다.
코드 블록 안의 파이프도 이스케이프해야 하나요?
표 셀 안의 인라인 코드라면 파서 구현에 따라 경계로 처리될 수 있습니다. `\|` 형태를 사용하고 대상 렌더러에서 결과를 확인하세요.
셀 안에 두 문단을 넣을 수 있나요?
일반적인 파이프 표는 블록 문단을 안정적으로 담기 어렵습니다. 한 셀 안에는 짧은 문장과 지원되는 줄바꿈만 두거나 표 밖으로 설명을 옮기세요.
열 너비를 마크다운으로 고정할 수 있나요?
GFM 표 문법 자체에는 픽셀 단위 열 너비 지정이 없습니다. 너비가 중요하면 대상 플랫폼의 HTML 또는 별도 스타일 기능을 사용해야 합니다.
근거와 출처
- GitHub Flavored Markdown 명세 — 1차 출처, 조회일 2026-08-30
- GitHub Docs 표 작성 안내 — 1차 출처, 조회일 2026-08-30
도구에서 직접 확인하기
설명한 기준을 실제 값에 적용하려면 마크다운 표 생성기에서 작은 샘플부터 확인하세요. 원본과 결과를 나란히 비교한 뒤 실제 사용 환경에 적용하는 순서가 가장 안전합니다.
이 글은 알파카랩스 Utils의 텍스트 및 문자열 도구와 함께 보는 정보성 가이드입니다. 규격과 외부 서비스 정책은 바뀔 수 있으므로 중요한 결정 전에는 연결된 공식 출처의 최신 내용을 다시 확인하세요.