마크다운 표(테이블) 완벽 가이드

마크다운에서 표(테이블)는 데이터를 정리하고 비교할 때 자주 사용됩니다. 간단한 문법으로 깔끔한 표를 만들 수 있지만, 복잡한 표를 다루려면 몇 가지 요령이 필요합니다. 이 글에서는 마크다운 표의 기본 문법부터 고급 활용법, 한계와 대안까지 상세하게 안내합니다.

기본 표 문법

마크다운 표는 파이프(|)와 하이픈(-)으로 만듭니다.

| 이름 | 나이 | 직업 |
|------|------|------|
| 김철수 | 30 | 개발자 |
| 이영희 | 28 | 디자이너 |
| 박지민 | 35 | PM |

렌더링 결과:

이름	나이	직업
김철수	30	개발자
이영희	28	디자이너
박지민	35	PM

구성 요소

헤더 행: 첫 번째 행이 자동으로 헤더가 됩니다.
구분선: 헤더와 본문을 구분하는 하이픈 행이 반드시 필요합니다.
데이터 행: 구분선 아래의 행들이 데이터입니다.

꼭 지켜야 할 규칙

헤더 행과 구분선 행은 반드시 있어야 합니다.
구분선의 하이픈은 최소 3개 이상이어야 합니다.
각 행의 열 수는 동일해야 합니다.

파이프 정렬은 선택 사항

소스 코드에서 파이프를 맞추면 가독성이 좋아지지만, 필수는 아닙니다.

<!-- 정렬된 표 (보기 좋음) -->
| 이름   | 나이 | 직업     |
|--------|------|----------|
| 김철수 | 30   | 개발자   |

<!-- 정렬하지 않은 표 (동일하게 렌더링됨) -->
|이름|나이|직업|
|---|---|---|
|김철수|30|개발자|

텍스트 정렬

구분선에 콜론(:)을 사용해 열의 정렬 방향을 지정할 수 있습니다.

| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:----------|:----------:|-----------:|
| 왼쪽 | 가운데 | 오른쪽 |
| Left | Center | Right |
| 텍스트 | 텍스트 | 텍스트 |

왼쪽 정렬	가운데 정렬	오른쪽 정렬
왼쪽	가운데	오른쪽
Left	Center	Right
텍스트	텍스트	텍스트

:--- : 왼쪽 정렬 (기본값)
:---: : 가운데 정렬
---: : 오른쪽 정렬

숫자 데이터는 오른쪽 정렬, 텍스트는 왼쪽 정렬, 상태나 카테고리는 가운데 정렬하는 것이 일반적입니다.

표 안에서 서식 사용

표의 셀 안에서 마크다운 인라인 서식을 사용할 수 있습니다.

| 기능 | 설명 | 상태 |
|------|------|------|
| **로그인** | `POST /api/login` | 완료 |
| **회원가입** | `POST /api/register` | *진행중* |
| ~~탈퇴~~ | `DELETE /api/user` | 보류 |
| [API 문서](https://api.example.com) | 전체 API 참조 | 완료 |

기능	설명	상태
로그인	`POST /api/login`	완료
회원가입	`POST /api/register`	진행중
탈퇴	`DELETE /api/user`	보류
API 문서	전체 API 참조	완료

다만 셀 안에서 블록 레벨 요소(목록, 코드 블록 등)는 사용할 수 없습니다.

실전 활용 예시

기능 비교표

| 기능 | 무료 플랜 | 프로 플랜 | 엔터프라이즈 |
|:-----|:--------:|:--------:|:-----------:|
| 프로젝트 수 | 3개 | 무제한 | 무제한 |
| 저장 용량 | 1GB | 50GB | 무제한 |
| 팀원 수 | 1명 | 10명 | 무제한 |
| 이메일 지원 | - | O | O |
| 전담 매니저 | - | - | O |
| 가격 | 무료 | 월 9,900원 | 문의 |

API 엔드포인트 정리

| 메서드 | 경로 | 설명 | 인증 |
|:------:|------|------|:----:|
| GET | `/api/users` | 사용자 목록 조회 | 필요 |
| POST | `/api/users` | 사용자 생성 | 필요 |
| GET | `/api/users/:id` | 특정 사용자 조회 | 필요 |
| PUT | `/api/users/:id` | 사용자 정보 수정 | 필요 |
| DELETE | `/api/users/:id` | 사용자 삭제 | 관리자 |

단축키 정리

| 동작 | Windows/Linux | macOS |
|------|:------------:|:-----:|
| 복사 | `Ctrl+C` | `Cmd+C` |
| 붙여넣기 | `Ctrl+V` | `Cmd+V` |
| 실행 취소 | `Ctrl+Z` | `Cmd+Z` |
| 저장 | `Ctrl+S` | `Cmd+S` |
| 전체 선택 | `Ctrl+A` | `Cmd+A` |

마크다운 표의 한계

셀 병합 불가

마크다운 표는 HTML의 colspan이나 rowspan을 지원하지 않습니다. 셀 병합이 필요하면 HTML을 직접 사용해야 합니다.

<table>
  <tr>
    <th colspan="2">이름</th>
    <th>점수</th>
  </tr>
  <tr>
    <td>성</td>
    <td>이름</td>
    <td>점수</td>
  </tr>
  <tr>
    <td>김</td>
    <td>철수</td>
    <td>95</td>
  </tr>
</table>

셀 내 줄바꿈

마크다운 표의 셀 안에서는 일반적인 줄바꿈이 되지 않습니다. <br> 태그를 사용하면 줄바꿈을 넣을 수 있습니다.

| 항목 | 설명 |
|------|------|
| 기능 A | 첫 번째 줄<br>두 번째 줄 |

넓은 표의 가로 스크롤

열이 많거나 내용이 긴 표는 화면을 넘어갈 수 있습니다. 웹에서는 CSS로 가로 스크롤을 추가할 수 있습니다.

.table-wrapper {
  overflow-x: auto;
}

표 작성을 도와주는 도구

온라인 테이블 생성기

마크다운 표를 직접 타이핑하기 번거로우면 온라인 도구를 활용합니다.

Tables Generator (tablesgenerator.com): GUI로 표를 만들고 마크다운으로 내보내기
Markdown Tables Generator: 열과 행 수를 지정하면 템플릿 생성

VS Code 확장

Markdown All in One: Tab 키로 셀 간 이동, 자동 정렬
Markdown Table Formatter: 표를 자동으로 정렬

CSV에서 변환

엑셀이나 CSV 데이터를 마크다운 표로 변환할 수 있습니다.

# csvtomd 도구 사용 예시
pip install csvtomd
csvtomd data.csv

PDF 출력 시 표 관련 팁

마크다운 표를 printmd 등으로 PDF로 변환할 때 몇 가지 주의할 점이 있습니다.

페이지 넘김 방지

표가 페이지 중간에서 잘리지 않도록 CSS를 추가합니다.

table {
  page-break-inside: avoid;
}

표 너비 조절

PDF에서 표가 넘치지 않도록 최대 너비를 지정합니다.

table {
  width: 100%;
  table-layout: fixed;
  word-wrap: break-word;
}

줄무늬 행 (Striped Rows)

가독성을 위해 줄무늬 배경을 추가할 수 있습니다.

tr:nth-child(even) {
  background-color: #f8f9fa;
}

실전 팁 정리

열 수를 적절히 유지하세요: 5-6열이 넘으면 가독성이 떨어집니다.
숫자는 오른쪽 정렬하세요: 자릿수를 맞춰 비교하기 쉬워집니다.
헤더는 짧고 명확하게: 헤더가 길면 표 전체가 넓어집니다.
빈 셀은 -로 표시하세요: 의도적으로 비운 것임을 알 수 있습니다.
복잡한 표는 여러 개로 나누세요: 하나의 큰 표보다 여러 개의 작은 표가 읽기 쉽습니다.

마무리

마크다운 표는 단순하지만 강력합니다. 기본 문법과 정렬만 알아도 대부분의 상황에서 충분히 활용할 수 있습니다. 복잡한 표가 필요할 때는 HTML을 병용하거나, 표를 단순화할 방법을 먼저 고민해보세요. 잘 정리된 표는 긴 설명보다 훨씬 효과적으로 정보를 전달합니다.

printmd에서는 마크다운 표가 깔끔하게 렌더링되며, PDF로 변환해도 서식이 잘 유지됩니다. 표가 많은 문서를 작성할 때 특히 유용합니다.