마크다운에서 표: GFM 구문, 정렬, 한계
GFM 파이프 테이블, 정렬, 셀 제한
Markdown 테이블은 헤더 행, 하이픈으로 된 구분자 행, 그리고 그 아래에 있는 데이터 행으로 구성됩니다. GFM과 Hugo에서 파이프 기호(|)를 테이블로 변환하는 핵심 요소는 구분자 행입니다.
이 가이드는 2026년 문서 도구: 마크다운, LaTeX, PDF 및 인쇄 워크플로의 일부입니다. 다른 블록 형식은 마크다운 치트시트에서 확인할 수 있습니다.
테이블은 원래 마크다운 문법이나 CommonMark에 포함되어 있지 않습니다. 이는 GitHub Flavored Markdown 사양의 테이블 확장입니다. Hugo 0.164는 해당 확장이 기본적으로 켜진 Goldmark를 사용합니다 (markup.goldmark.extensions.table). 아래 예시들은 파이프 기호가 그대로 유지되도록 코드 블록으로 둘러싸였으며, 이는 마크다운 코드 블록에서 다루는 패턴과 동일합니다.
파이프 테이블 문법
테이블은 세 부분으로 구성됩니다. 헤더 행 1개, 구분자 행 1개, 그리고 0개 이상의 데이터 행입니다. 셀은 |로 구분됩니다. 행의 시작과 끝에 파이프 기호를 사용하는 것은 선택 사항입니다. 파이프 기호 옆의 공백은 제거됩니다.
| Header 1 | Header 2 |
| --- | --- |
| Cell A1 | Cell B1 |
| Cell A2 | Cell B2 |
GitHub의 작성 문서는 각 구분자 셀에 최소 3개의 하이픈이 필요하며, GitHub가 테이블을 렌더링하려면 테이블 앞의 빈 줄이 필수적이라고 명시합니다. GFM 사양은 구분자 셀을 하이픈으로 설명하며, 양쪽에 선택적인 콜론을 허용하며, 그 예시에는 하이픈 1개짜리 셀이 포함되어 있습니다. Hugo 0.164는 이를 테이블로 렌더링했습니다:
| A | B |
| - | - |
| 1 | 2 |
동일한 Hugo 렌더링은 앞 줄이 문단이고 빈 줄이 없는 경우에도 테이블을 <table>로 변환했습니다. GitHub에서는 3개 하이픈 구분자와 빈 줄을 따르세요. 이 사이트에서는 하이픈 1개면 충분하며 빈 줄은 필수하지 않습니다.
|Too|Tight|와 |---|---| 구분자도 렌더링되었습니다. 파이프 기호 옆의 공백은 제거됩니다. 첫 번째 예시의 공백은 소스 차이를 읽기 쉽게 유지하기 위한 것입니다.
헤더 행과 구분자 행은 동일한 수의 셀을 가져야 합니다. 수가 다르면 Hugo는 테이블로 인식하지 않습니다. 이 경우 평범한 텍스트로 남으며, 하이픈은 Hugo의 타이포그래퍼(문자 형태 변환기) 적용 대상이 됩니다:
| abc | def |
| --- |
| bar |
데이터 행은 헤더보다 짧거나 길 수 있습니다. 짧은 행은 빈 셀로 채워집니다. 헤더의 셀 수를 초과하는 셀은 제거됩니다.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
위 두 예시 중 첫 번째는 세 번째 셀을 빈 셀로 렌더링합니다. 두 번째는 1과 2만 렌더링합니다.
파이프 기호가 없는 줄도 빈 줄이 올 때까지 테이블 내부에 속합니다. Hugo 0.164는 후속하는 bar를 두 번째 셀이 빈 행으로 테이블 내에 넣었으며, 이는 GFM 예시 202와 일치합니다. 다음 문단은 빈 줄 이후에 시작됩니다.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
열 정렬
정렬은 구분자 행의 콜론으로 설정됩니다. 콜론이 없는 ---는 왼쪽 정렬이며, :---와 동일합니다.
| Left | Right | Center |
| :--- | ----: | :----: |
| text | 12.50 | yes |
| Left | Right | Center |
|---|---|---|
| text | 12.50 | yes |
헤더 행의 콜론은 해당 셀의 문자일 뿐입니다. 정렬을 설정하지 않습니다. 아래 구분자 행이 Hugo에서 실제로 사용된 것입니다:
| :--- Left | Right ---: |
| :-------- | ---------- |
| Correct | Alignment |
셀 내용
셀 내부에는 인라인(행 내) 요소가 작동합니다. 강조, 코드 스팬, 링크 등이 가능합니다. 하지만 블록 구성 요소는 작동하지 않습니다. GFM 사양은 테이블 내에 블록 레벨 요소를 삽입할 수 없다고 명시하므로, 셀 내부의 목록이나 코드 페ンス는 각각 목록이나 페ンス로 취급되지 않습니다.
| Feature | Status | Documentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Released* | [Docs](/api) |
| `Auth` | Beta | Coming soon |
리터럴(그대로의) 파이프 기호는 \| 또는 |로 표현합니다. Hugo 0.164는 둘 다 |로 렌더링했습니다.
| Expression | Result |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
셀 내부의 줄바꿈은 HTML <br> 태그입니다. 이 사이트는 markup.goldmark.renderer.unsafe를 true로 설정하여 해당 태그가 유지됩니다. 생 HTML을 제거하는 처리기를 사용할 경우 두 부분의 텍스트가 연결됩니다.
셀 텍스트로 쓰인 하이픈 3개는 Hugo에서 또 다른 함정입니다. 타이포그래퍼가 셀 안의 ---를 em dash(—)로 변환합니다. 코드 스팬 안의 하이픈은 유지됩니다. \---는 -–로 렌더링되었습니다.
| As text | As code |
| ------- | ------- |
| --- | `---` |
병합된 셀
GFM에는 rowspan이나 colspan이 없습니다. 한 셀이 두 행을 커버해야 하는 경우, 테이블은 HTML로 작성해야 합니다. 이 사이트의 unsafe 렌더러는 그 HTML을 페이지에 그대로 유지합니다:
<table>
<tr>
<td rowspan="2">Merged</td>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
</tr>
</table>
Pandoc의 markdown+pipe_tables writer는 이 페이지에서 파이프 문법을 출력합니다. 이 writer는 Word 문서에서 마크다운으로 변환할 때 사용됩니다. Grid 테이블과 기타 Pandoc 전용 레이아웃은 방언(dialect) 특성이며, GFM vs CommonMark vs Pandoc Markdown에서 다룹니다.
너비가 넓은 파이프 테이블은 스크롤되거나 벗어나는 경우가 많습니다. 이동 가능한 해결책은 전치(행렬의 행과 열을 바꿈) 레이아웃, 여러 개의 작은 테이블로 나누기, 또는 자체 CSS를 가진 HTML 테이블을 사용하는 것입니다. 파이프 문법에는 캡션(caption) 기능이 없습니다. Hugo의 목차는 헤더에서 생성됩니다.
테이블이 텍스트로 남아 있을 때 확인 사항
헤더 행과 구분자 행의 셀 수를 세어보세요. 이 두 값이 다르면 해당 블록은 문단으로 처리됩니다. 짧은 데이터 행은 여전히 테이블이며, 끝이 빈 셀이 됩니다. markdownlint 규칙 MD056은 짧은 행이 누락된 셀처럼 보이고, 추가된 셀은 제거되므로 모든 행이 해당 셀 수와 일치하도록 요구합니다.
구분자 행의 콜론을 확인하세요. 헤더에 있는 콜론은 텍스트일 뿐이며, 열은 구분자 행의 정렬을 따릅니다.
셀 내부의 ---가 이 사이트에서 대시 문자 하나로 보인다면, 타이포그래퍼가 변환한 것입니다. 하이픈을 코드 스팬 안에 넣으세요.
GitHub에서 파이프 기호가 텍스트로 보인다면, GitHub 문서에서 요구하는 빈 줄을 추가하고 각 구분자 셀에 최소 3개의 하이픈을 사용하세요. Hugo 0.164는 이미 더 짧은 형태를 수락했습니다.
구분자 행이 없는 경우는 파이프 블록이 텍스트로 남아 있는 또 다른 경우입니다. Hugo 0.164는 이것을 문단으로 남겼습니다:
| Header 1 | Header 2 |
| Cell A | Cell B |
파라미터 테이블
동일한 구분자 행은 정렬을 지정하고 인라인 코드를 위한 공간을 제공합니다:
| Parameter | Type | Default | Required |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Yes |
| `timeout` | number | 30000 | No |
| `retries` | number | 3 | No |
