smithREADME나 블로그, 노션에 표를 넣으려고 마크다운을 쓰다 보면 표가 그냥 글자로 보이거나, 가운데 정렬이 안 되거나, 셀을 합치고 싶은데 방법이 없어서 막히곤 해요. 결론부터 말하면 마크다운 표는 | 로 칸을 나누고, 머리글 다음 줄에 |---|---| 구분선을 넣으면 만들어져요. 정렬은 구분선에 콜론(:)을 붙여 정하고, 셀 병합은 표준 마크다운(GFM)에 아예 없어서 HTML 표를 써야 해요.
이 글은 GitHub Flavored Markdown(GFM) 표 문법을 기준으로, 기본 형태부터 정렬, 표가 깨지는 흔한 원인, 셀 안 줄바꿈과 | 문자 넣기, 엑셀·구글 시트 데이터를 표로 바꾸는 방법까지 실제 예시로 정리했어요.
핵심 요약
표는 머리글 행, 구분선 행, 데이터 행 순서로 쓰고, 칸은 | 로 나눠요. 구분선은 칸마다 하이픈 최소 1개(관례상 3개)가 필요해요.
정렬은 구분선에서 정해요. :--- 는 왼쪽, :---: 는 가운데, ---: 는 오른쪽이에요. 셀마다 다르게 정렬하는 기능은 없어요.
셀 병합(colspan, rowspan)은 GFM 표준에 없어요. 꼭 필요하면 HTML table 태그를 직접 쓰고, 렌더러가 HTML을 허용하는지 확인하세요.
표가 안 보이는 가장 흔한 원인은 표 바로 위에 빈 줄이 없거나, 구분선 칸 수가 머리글과 다를 때예요.
마크다운 표 기본 문법
가장 단순한 표는 이렇게 생겼어요.
| 이름 | 언어 | 경력 |
|---|---|---|
| 민수 | Python | 3년 |
| 지영 | TypeScript | 5년 |구조는 세 부분이에요.
- 머리글 행: 첫 줄. 표의 제목 칸이 돼요(HTML의
th). - 구분선 행: 둘째 줄. 칸마다
---를 넣어 "여기부터 표"라고 알려 줘요. 이 줄이 없으면 표로 인식되지 않아요. - 데이터 행: 셋째 줄부터. 한 줄이 한 행이에요.
GFM 명세 기준으로 줄 맨 앞과 맨 뒤의 |는 생략해도 되고, 칸 너비를 공백으로 맞출 필요도 없어요. 아래 두 표는 똑같이 렌더링돼요.
이름 | 언어
--- | ---
민수 | Python
| 이름 | 언어 |
| ---- | ---------- |
| 민수 | Python |다만 양 끝 |를 생략하는 형태는 일부 렌더러(오래된 위키, 일부 블로그 에디터)에서 표로 인식하지 못하는 경우가 있어요. 양 끝 |를 항상 쓰는 습관이 호환성 면에서 안전해요. 공백으로 칸을 맞추는 건 원문 가독성을 위한 선택이고, 결과에는 영향이 없어요.
마크다운 표 정렬: 왼쪽·가운데·오른쪽
정렬은 구분선 행의 콜론 위치로 정해요. 칸(열) 단위로만 지정할 수 있어요.
| 구분선 | 정렬 | 어울리는 데이터 |
|---|---|---|
--- | 기본(대부분 왼쪽) | 일반 텍스트 |
:--- | 왼쪽 | 이름, 설명 |
:---: | 가운데 | 상태, O/X, 아이콘 |
---: | 오른쪽 | 금액, 수량, 퍼센트 |
예를 들어 구분선을 |:---|:---:|---:| 로 쓰면 첫 열은 왼쪽, 둘째 열은 가운데, 셋째 열은 오른쪽으로 정렬돼요.
숫자 열은 오른쪽 정렬이 기본이에요. 자릿수가 오른쪽 끝에서 맞아야 1,200과 98,000의 크기 차이가 한눈에 보이거든요. 반대로 숫자를 왼쪽 정렬하면 자릿수 비교가 어려워져요. 가운데 정렬은 "O/X", "완료/대기"처럼 짧고 길이가 비슷한 값에만 쓰는 게 깔끔해요.
셀 하나만 다르게 정렬하고 싶다면
GFM에는 셀 단위 정렬이 없어요. 꼭 필요하면 HTML을 허용하는 환경에서 <div align="center"> 같은 태그를 셀 안에 쓰거나, 아예 HTML 표로 바꿔야 해요. GitHub는 style 속성을 걸러 내기 때문에 style="text-align:center"는 동작하지 않아요. 대부분은 열 정렬만으로 충분하니, 셀 단위 정렬이 필요하다면 표 구조를 다시 생각해 보는 게 나아요.
마크다운 표가 깨질 때, 흔한 원인 7가지
표가 그냥 | 이름 | 언어 | 글자로 보인다면 아래를 순서대로 확인해 보세요.
| 증상 | 원인 | 해결 |
|---|---|---|
| 표 전체가 글자로 보임 | 표 바로 위 줄이 일반 문단 | 표 위에 빈 줄 한 줄 추가 |
| 표 전체가 글자로 보임 | 구분선 칸 수가 머리글과 다름 | 머리글 칸 수만큼 --- 맞추기 |
| 표 전체가 글자로 보임 | 구분선에 콜론만 있고 하이픈이 없음 | 칸마다 - 최소 1개 |
| 칸이 밀리거나 잘림 | 셀 안에 파이프 문자가 들어 있음 | 앞에 역슬래시를 붙여 이스케이프 |
| 데이터 행 칸이 모자람 | 행마다 칸 수가 다름 | 모자란 칸은 빈칸 처리, 넘치는 칸은 버려짐 |
| 표 아래 문단이 표에 붙음 | 표 뒤에 빈 줄이 없음 | 표 끝에 빈 줄 추가 |
| 일부 블로그에서만 안 됨 | 렌더러가 GFM 표 미지원 | 해당 서비스의 표 기능이나 HTML 사용 |
이 중 가장 자주 만나는 건 첫 번째예요. 마크다운에서 표는 "새 블록"이라, 바로 위에 문단 글자가 붙어 있으면 그 문단의 연속으로 해석되는 렌더러가 많아요. GFM은 문단 바로 아래 표도 인식하지만, 다른 엔진과 호환을 위해 표 위아래로 빈 줄을 하나씩 두는 습관을 들이면 문제가 거의 사라져요.
칸 수 규칙도 알아 두면 좋아요. GFM 명세상 머리글과 구분선의 칸 수는 반드시 같아야 하고, 데이터 행은 칸이 모자라면 빈칸으로 채우고 넘치면 넘친 칸을 버려요. 그래서 "마지막 열 내용이 사라졌다"면 그 행의 | 개수를 세어 보세요.
셀 안에서 줄바꿈, 파이프(|), 코드 넣기
표 셀은 한 줄이어야 해요. 셀 안에서 엔터를 치면 그 자리에서 행이 끝나 버려요. 대신 이렇게 처리해요.
- 줄바꿈:
<br>태그를 써요.첫째 줄<br>둘째 줄처럼요. GitHub, GitLab, 대부분의 블로그 엔진에서 동작해요. - 파이프 문자: 셀 안의
|는 칸 구분으로 읽히니\|로 써요.a \|\| b는 셀 안에서a || b로 보여요. - 인라인 코드 안의 파이프: GFM은 백틱으로 감싼 코드 안에서도 파이프를 칸 구분으로 먼저 처리해요. 그래서 코드 안의 파이프도
\|처럼 이스케이프해야 해요. 헷갈리기 쉬운 부분이에요. - 목록: 셀 안에
-목록은 쓸 수 없어요.• 항목1<br>• 항목2처럼 흉내 내는 방법이 일반적이에요. - 링크·굵게·이미지: 인라인 문법(
**굵게**,[링크](url),)은 셀 안에서 정상 동작해요.
셀 안에 문단이나 코드 블록처럼 여러 줄짜리 내용이 들어가야 한다면, 그 데이터는 표보다 소제목 + 목록 구조가 더 읽기 좋은 경우가 많아요.
마크다운 표 셀 병합은 안 될까
GFM 표에는 셀 병합(colspan, rowspan) 문법이 없어요. 일부 확장 문법(MultiMarkdown의 ||, 특정 정적 사이트 생성기 플러그인)이 병합을 지원하지만, GitHub·노션·대부분의 블로그에서는 통하지 않아요.
병합이 꼭 필요할 때 선택지는 세 가지예요.
- HTML 표 직접 쓰기:
<table>,<tr>,<td colspan="2">로 작성해요. GitHub README에서도 동작해요. 다만 원문이 길어지고, HTML 블록 안에서는 마크다운 문법이 해석되지 않는 경우가 많아 굵게·링크도 HTML로 써야 해요. - 표 구조 바꾸기: 병합하고 싶은 이유는 대개 "같은 값이 반복돼서"예요. 그 값을 열로 빼거나, 그룹마다 표를 나누면 병합 없이도 읽기 쉬워져요.
- 빈 칸으로 흉내 내기: 아래 행의 같은 값을 비워 두거나
〃를 넣는 방식이에요. 보기엔 병합처럼 보이지만 데이터로 다시 쓰기 어렵다는 단점이 있어요.
<table>
<tr><th>분기</th><th>월</th><th>매출</th></tr>
<tr><td rowspan="2">1분기</td><td>1월</td><td>120</td></tr>
<tr><td>2월</td><td>98</td></tr>
</table>이렇게 쓰면 "1분기" 칸이 두 행에 걸쳐 합쳐져요. 마크다운 렌더러가 HTML을 허용하지 않는 환경(일부 댓글창, 보안 설정이 강한 위키)에서는 태그가 그대로 글자로 보이니 미리보기로 꼭 확인하세요.
엑셀·구글 시트 표를 마크다운으로 바꾸기
엑셀에서 범위를 복사해 텍스트 에디터에 붙여넣으면 칸은 탭 문자, 행은 줄바꿈으로 들어와요. 이 구조를 이용하면 변환이 쉬워요.
- 엑셀·구글 시트에서 머리글을 포함해 범위를 복사해요.
- 마크다운 표 생성기에 붙여넣으면 탭을
|로 바꾸고 구분선을 자동으로 넣어 줘요. 정렬도 열마다 고를 수 있어요. - 결과를 복사해 README나 블로그에 붙여넣어요.
직접 하려면 에디터의 찾아 바꾸기로 탭(\t)을 | 로 바꾸고, 줄 앞뒤에 |를 붙인 뒤 둘째 줄에 구분선을 넣으면 돼요. 이때 주의할 점이 있어요.
- 셀 안의 줄바꿈: 엑셀에서 Alt+Enter로 줄바꿈한 셀은 따옴표로 감싸져 여러 줄로 붙여넣어져요. 변환 전에 줄바꿈을
<br>로 바꾸거나 없애야 해요. - 셀 안의
|: 변환 후\|로 이스케이프돼 있는지 확인해요. - 숫자 서식: 엑셀에 보이는 값(1,200원)이 그대로 복사돼요. 콤마가 섞인 숫자는 오른쪽 정렬로 두면 읽기 좋아요.
- CSV 파일: CSV는 쉼표 구분이라 탭과 달라요. 쉼표가 들어간 값은 따옴표로 감싸져 있어서 단순 치환하면 칸이 밀려요. CSV 인코딩 문제는 CSV 엑셀 한글 깨짐 해결에 따로 정리해 뒀어요.
반대로 마크다운 표를 엑셀로 옮길 때는 표를 렌더링된 화면(GitHub 미리보기 등)에서 드래그해 복사하면 대부분 칸이 유지된 채 붙여넣어져요.
어디서 쓰느냐에 따라 다른 점
같은 마크다운이라도 서비스마다 표 지원이 조금씩 달라요.
| 환경 | GFM 표 | 정렬 | HTML 표(병합) | 참고 |
|---|---|---|---|---|
| GitHub README·이슈 | O | O | O | style 속성은 제거됨 |
| GitLab | O | O | O | GFM과 거의 동일 |
| 노션 | 붙여넣기 시 변환 | 일부 | X | 노션 자체 표 블록으로 바뀜 |
| VS Code 미리보기 | O | O | O | 기본 렌더러가 markdown-it |
| Jekyll·Hugo 등 정적 사이트 | O | O | 설정에 따라 | 엔진·옵션 확인 필요 |
| 슬랙·카카오톡 | X | X | X | 표 문법 미지원, 코드 블록으로 대체 |
메신저처럼 표를 지원하지 않는 곳에서는 표를 코드 블록(백틱 세 개)으로 감싸 고정폭 글꼴로 보여 주는 게 차선책이에요. 이때는 공백으로 칸 너비를 맞춰 둬야 정렬돼 보여요. 한글은 고정폭 글꼴에서도 영문 2칸 너비로 그려지는 경우가 많아, 한글과 영문이 섞인 표는 칸이 어긋나기 쉬워요.
자주 묻는 질문
마크다운 표에서 가운데 정렬은 어떻게 하나요?
구분선 행에서 그 열을 :---: 처럼 양쪽에 콜론을 붙이면 돼요. 오른쪽 정렬은 ---:, 왼쪽 정렬은 :---예요. 정렬은 열 단위로만 지정할 수 있어요.
마크다운 표에서 셀 병합이 되나요?
표준 GFM에는 병합 문법이 없어요. HTML <table>에 colspan, rowspan을 쓰면 GitHub 등 HTML을 허용하는 곳에서는 병합돼요. 가능하면 표 구조를 바꿔 병합이 필요 없게 만드는 게 관리하기 편해요.
표 안에서 줄바꿈하려면요?
셀 안에서는 엔터 대신 <br>을 써요. 엔터를 치면 행이 끝나 버려요. 대부분의 마크다운 렌더러가 표 셀 안의 <br>을 지원해요.
표가 표로 안 보이고 글자 그대로 나와요.
표 위에 빈 줄이 있는지, 둘째 줄 구분선의 칸 수가 머리글과 같은지 먼저 확인하세요. 구분선 칸마다 하이픈이 최소 1개 있어야 하고, 쓰는 서비스가 GFM 표를 지원하는지도 확인해야 해요.
구분선 하이픈은 꼭 3개여야 하나요?
GFM 명세상 칸마다 하이픈 1개 이상이면 돼요. 3개는 관례이고, 원문을 보기 좋게 하려고 칸 너비만큼 길게 쓰기도 해요. 길이는 렌더링 결과에 영향을 주지 않아요.
정리
마크다운 표는 머리글 행 → 구분선 행 → 데이터 행 세 부분이면 끝이에요. 정렬은 구분선의 콜론으로(:--- 왼쪽, :---: 가운데, ---: 오른쪽), 셀 안 줄바꿈은 <br>, 셀 안 파이프는 \|로 처리해요. 셀 병합은 표준에 없으니 HTML 표를 쓰거나 표 구조를 바꾸는 게 답이에요. 표가 깨지면 빈 줄과 칸 수부터 확인하세요.
엑셀 데이터를 붙여넣어 바로 표로 바꾸고 싶다면 마크다운 표 생성기를 써 보세요. 표에 넣을 데이터를 다룰 때는 JSON 문법 오류 패턴도 함께 참고하면 좋아요.