표
GitLab v19.6요약
표는 복잡한 정보를 간결하게 설명하는 데 사용합니다. 표를 접근하기 쉽고 훑어보기 좋게 유지하려면 빈 셀을 피합니다. 표를 더 쉽게 유지 관리하려면 다음을 따릅니다. 표에 Description 열이 있으면 가능한 한 가장 오른쪽 열로 둡니다.
표는 복잡한 정보를 간결하게 설명하는 데 사용합니다. 대부분의 경우 항목마다 설명이 하나씩만 있는 항목 목록은 순서 없는 목록으로 충분합니다. 그러나 데이터를 행렬로 설명하는 것이 가장 적합하다면 표가 가장 좋은 선택입니다.
작성 가이드라인#
표를 접근하기 쉽고 훑어보기 좋게 유지하려면 빈 셀을 피합니다. 기능 표에서는 숏코드를 사용하여 기능 제공 여부를 나타냅니다. 그 외에 셀에 넣을 의미 있는 값이 없으면 None을 사용합니다.
표를 더 쉽게 유지 관리하려면 다음을 따릅니다.
-
표에
Description열이 있으면 가능한 한 가장 오른쪽 열로 둡니다. -
열 너비가 일정해지도록 공백을 추가합니다. 예를 들면 다음과 같습니다.
| Parameter | Default | Requirements | |-----------|--------------|--------------| | `param1` | `true` | A and B. | | `param2` | `gitlab.com` | None | -
매우 넓은 표는 가장 오른쪽 열에 공백을 추가하지 않습니다. 예를 들면 다음과 같습니다.
| Setting | Default | Description | |-----------|---------|-------------| | Setting 1 | `1000` | A short description. | | Setting 2 | `2000` | A long description that would make the table too wide and add too much whitespace if every cell in this column was aligned. | | Setting 3 | `0` | Another short description. | -
표의 머리글(첫 번째) 행과 구분선(두 번째) 행은 길이가 같아야 합니다.
|-|-|-|나|--|--|처럼 줄여 쓴 구분선 행은 사용하지 않습니다. -
큰 표가 자동 서식에서 제대로 정리되지 않으면 자동 서식을 건너뛸 수 있습니다. 단 다음을 지킵니다.
- 처음 두 행의 길이를 같게 만듭니다.
|문자와 셀 내용 사이에 공백을 둡니다. 예를 들어|Cell1|Cell2|가 아니라| Cell 1 | Cell 2 |로 씁니다.
큰 표를 위한 옵션#
Hugo 클래스 속성을 사용하여 표를 축약형, 확장형, 정렬형으로 만들 수 있습니다. 표에서 린트 오류가 생기지 않도록 모든 규칙을 켠 상태로 표를 로컬에서 테스트합니다.
Hugo 클래스 속성은 GitLab 문서 사이트(https://docs.gitlab.com)에서만 렌더링됩니다.
속성은 표의 마지막 행 바로 다음 줄에 둡니다. 그러지 않으면 Hugo가 속성을 무시합니다. 예를 들면 다음과 같습니다.
| Parameter | Default | Requirements |
|-----------|--------------|--------------|
| `param1` | `true` | A and B. |
| `param2` | `gitlab.com` | None |
축약형 표#
축약형 표는 필요에 따라 세로와 가로로 스크롤할 수 있으며 높이가 제한됩니다.
기본적으로 페이지에 들어가지 않는 넓은 표는 축약됩니다. 긴 표는 축약되지 않습니다. 표가 페이지에서 차지하는 공간을 줄이려면
선택적으로 condensed 클래스 속성을 추가할 수 있습니다.
또는 다음과 같이 씁니다.
{class="condensed"}
확장형 표#
확장형 표에는 Expand table 버튼이 있으며, 이 버튼을 선택하면 대화 상자에서 표가 열립니다.
확장형 표를 만들려면 expandable 클래스 속성을 사용합니다.
표를 축약형이면서 확장형으로 만들려면 두 속성을 모두 사용합니다. 예를 들면 다음과 같습니다.
{.condensed .expandable}
또는 다음과 같이 씁니다.
{class="condensed expandable"}
정렬형 표#
정렬형 표에는 사용자가 선택하여 행을 정렬할 수 있는 열 머리글이 있습니다.
- 첫 번째 선택: 오름차순.
- 두 번째 선택: 내림차순.
- 세 번째 선택: 원래 순서.
속성, 파라미터, 설정, 이벤트 표처럼 사용자가 이름으로 행을 찾는 경우에는 표를 정렬형으로 만듭니다.
다음과 같은 경우에는 표를 정렬형으로 만들지 않습니다.
- 단계의 순서나 시간에 따른 값처럼 행의 순서에 의미가 있는 경우.
- 표가 하위 제목 행 아래에 행을 묶어 놓은 경우.
- 권한 매트릭스나 진리표처럼 사용자가 표를 격자로 훑어보는 경우.
정렬형 표를 만들려면 sortable 클래스 속성을 사용합니다.
표를 축약형이면서 정렬형으로 만들려면 두 속성을 모두 사용합니다.
{.condensed .sortable}
또는 다음과 같이 씁니다.
{class="condensed sortable"}
속성을 추가하기 전에 각 열이 어떻게 정렬되는지 확인합니다.
- 텍스트는 대소문자를 구분하지 않고 정렬됩니다.
- 숫자로 이루어진 각 묶음은 하나의 정수로 정렬되며, 마침표가 이 묶음을 구분합니다.
17.2가17.10보다 앞에 오는 것처럼 버전 번호는 올바르게 정렬됩니다.1.5가1.25보다 앞에 오는 것처럼 소수 값은 올바르게 정렬되지 않을 수 있습니다. 와숏코드를 사용한 셀은Yes와No로 정렬됩니다.- 빈 셀은 항상 마지막에 정렬됩니다.
- 링크가 포함된 머리글은 정렬할 수 없습니다.
표 서식 지정을 위한 에디터 확장#
모든 Markdown 파일에서 표 서식을 일관되게 유지하려면 VS Code Markdown Table Formatter로 표 서식을 지정하는 것을 고려합니다. 이 확장이 위 가이드라인을 따르도록 구성하려면 Follow header row length 설정을 켭니다. 설정을 켜려면 다음을 수행합니다.
-
UI에서:
- VS Code 메뉴에서 Code > Settings > Settings로 이동합니다.
Limit Last Column Length를 검색합니다.- Limit Last Column Length 드롭다운 목록에서 Follow header row length를 선택합니다.
-
VS Code
settings.json에서 다음 줄을 새로 추가합니다.{ "markdown-table-formatter.limitLastColumnLength": "Follow header row length" }
이 확장으로 표 서식을 지정하려면 표 전체를 선택하고 선택 영역을 마우스 오른쪽 버튼으로 클릭한 다음 Format Selection With를 선택합니다. VS Code 명령 팔레트에서 Markdown Table Formatter를 선택합니다.
Sublime Text를 사용한다면 Markdown Table Formatter 플러그인을 사용해 볼 수 있지만, 이 플러그인에는 Follow header row length 설정이 없습니다.
기존 표 업데이트#
기존 표에 행을 추가하거나 편집하면 일부 행의 정렬이 맞지 않게 될 수 있습니다. 몇 개의 행만 변경하는 경우에는 표 전체를 다시 정렬하지 않습니다. 너비에 맞추어 열을 다시 정렬하면 표 전체가 수정된 것으로 표시되어 diff를 읽기 어려워집니다.
Markdown 표는 시간이 지나면 자연스럽게 정렬이 어긋나지만 docs.gitlab.com에서는
여전히 올바르게 렌더링됩니다. 기술 문서 팀은 다음에 해당 페이지를 리팩터링할 때
셀을 다시 정렬할 수 있습니다.
표 머리글#
표 머리글에는 문장형 대소문자(sentence case)를 사용합니다. 예를 들어 Keyword value나 Project name처럼 씁니다.
기능 표#
기능 목록 표를 만들 때(예: 권한 페이지의 권한별 사용 가능 기능) 다음 숏코드를 사용합니다.
| 옵션 | Markdown | 렌더링 결과 | 참고 |
|---|---|---|---|
| No | |
❌ | 화면 낭독기용 숨겨진 span을 렌더링합니다. <span class="gl-sr-only">no</span> |
| Yes | |
✅ | 눈에 보이는 체크 표시 아이콘과 화면 낭독기용 숨겨진 span을 렌더링합니다. <span class="gl-sr-only">yes</span> |
API 문서나 인라인 텍스트에서는 이 숏코드를 사용하지 않습니다. API 문서는 API 토픽 템플릿을 따릅니다.
각주#
표 안에 내용을 넣을 수 없을 때만 표 아래에 각주를 사용합니다. 예를 들어 다음과 같은 경우에 각주를 사용합니다.
- 여러 표 셀에 같은 정보를 제공해야 하는 경우.
- 표의 레이아웃을 흐트러뜨릴 내용을 포함해야 하는 경우.
각주 형식#
표 셀에서 각주 참조를 [^label]로 작성합니다.
참조는 문장 끝에 추가하며 앞에 공백을 두지 않습니다.
셀이나 문장에 각주 참조가 둘 이상 필요하면 쉼표와 공백으로 구분합니다.
예를 들어 [^registration-shell], [^default-shell]처럼 씁니다.
대응하는 정의는 [^label]: Footnote text.로 작성합니다.
예를 들면 다음과 같습니다.
| App name | Description |
|:---------|:------------|
| App A | Description text.[^rate-limit] |
| App B | Description text.[^retention] |
[^rate-limit]: This is the first footnote.
[^retention]: This is the second footnote.
소스를 읽기 쉽게 유지하도록 표의 정의는 해당 표 바로 아래에 추가합니다.
탭()과 같은 숏코드 안에는 각주 참조나 정의를 넣지 않습니다.
렌더러가 각주에 번호를 매기고 표 아래에 Footnotes 제목을 추가합니다.
각주 들여쓰기#
각주 정의가 여러 줄이면 첫 번째 줄 이후의 모든 줄을 공백 네 칸으로 들여씁니다. 같은 문단의 줄과 추가 문단, 목록 모두에 해당합니다.
빈 줄 뒤에는 들여쓰기가 필요합니다. 들여쓰기를 추가하지 않으면 빈 줄 이후의 모든 텍스트가 각주에 포함되지 않고 일반 텍스트로 렌더링됩니다.
예를 들면 다음과 같습니다.
[^rate-limit]: This is the first footnote description sentence.
This is the second sentence.
This is the second paragraph of the same footnote.
각주 번호 매기기#
각주는 처음 참조된 순서대로 번호가 매겨집니다. 번호는 페이지 전체를 기준으로 하며, 페이지의 모든 표와 문단을 포함합니다.
각주 레이블도 페이지 전체를 기준으로 합니다. 여러 참조가 하나의 각주를 공유하게 하려면 참조마다 같은 레이블을 사용합니다. 그렇지 않으면 각주마다 고유한 레이블을 부여합니다. 같은 레이블을 두 번 정의하면 렌더러는 첫 번째 정의를 유지하고 두 번째 정의는 경고 없이 버립니다.