Markdown과 목록
GitLab v19.6요약
모든 GitLab 문서는 Markdown으로 작성합니다. 문서 웹사이트는 Hugo 정적 사이트 생성기와 기본 Markdown 엔진인 Goldmark를 사용합니다. Markdown 서식은 markdownlint와 Vale로 테스트합니다.
Markdown#
모든 GitLab 문서는 Markdown으로 작성합니다.
문서 웹사이트는 Hugo 정적 사이트 생성기와 기본 Markdown 엔진인 Goldmark를 사용합니다.
Markdown 서식은 markdownlint와 Vale로 테스트합니다.
Markdown 안의 HTML#
하드코딩된 HTML도 유효하지만, 다음과 같은 이유로 권장하지 않습니다.
- 사용자 지정 마크업은 향후 사이트 전체 변경이나 디자인 시스템 업데이트를 깨뜨릴 수 있습니다.
- 사용자 지정 마크업에는 사이트 전반의 일관성을 보장하는 테스트 범위가 없습니다.
- 사용자 지정 마크업은 반응형이 아니거나 접근성을 갖추지 못할 수 있습니다.
- 사용자 지정 마크업은 Pajamas 지침을 따르지 않을 수 있습니다.
- Markdown 안의 HTML과 CSS는
/help에서 렌더링되지 않습니다. - HTML을 직접 작성하면 오류가 생기기 쉽습니다. 잘못된 HTML로 페이지 레이아웃이나 다른 구성 요소가 깨질 수 있습니다.
다음 경우에는 HTML을 허용합니다.
- Markdown에 이에 해당하는 기능이 없는 경우
- 테크니컬 라이터가 콘텐츠를 검토하고 승인한 경우
- 사용자 지정 요소가 시급하게 필요하고 Technical Writing 엔지니어의 구현을 기다릴 수 없는 경우
HTML <a> 태그로 만드는 모든 링크는 href 속성에 절대 URL을 사용해야 합니다.
일반 링크와 달리 Markdown 파일로의 상대 링크는 사용하지 않습니다.
Hugo는 Markdown 형식의 링크만 처리하고 바꿀 수 있기 때문입니다.
Docs 사이트에 유용할 새 요소에 대한 아이디어나 요청이 있으면 기능 요청을 제출합니다.
Markdown의 제목 수준#
각 문서 페이지에는 메타데이터에 title 속성이 있어야 합니다.
title은 HTML로 렌더링될 때 H1 요소가 됩니다.
페이지마다 H1은 하나만 있을 수 있으므로 Markdown에 H1 제목을 추가하지 않습니다.
- 하위 섹션마다 제목 수준을 하나씩 높입니다. 즉, 토픽 제목 앞의
#문자 수를 하나씩 늘립니다. H5(#####)보다 큰 제목 수준은 사용하지 않도록 합니다. 제목 수준이 다섯 개를 넘게 필요하면 토픽을 새 페이지로 옮깁니다.H4보다 큰 제목 수준은 오른쪽 사이드바 탐색에 표시되지 않습니다.- 수준을 건너뛰지 않습니다. 예:
##>####. - 토픽 제목 앞뒤에 빈 줄을 하나씩 둡니다.
- 토픽 제목에 코드를 사용하면 코드를 백틱으로 감쌉니다.
- 토픽 제목에는 굵은 텍스트를 사용하지 않습니다.
제목이 목차(TOC)에 나타나지 않게 하려면 제목 텍스트 뒤에 `` 속성을 추가합니다.
## My heading
제목은 페이지에 그대로 렌더링되지만 TOC에서는 제외됩니다.
Markdown의 설명 목록#
용어를 정의하거나 옵션을 구분하려면 설명 목록을 사용합니다. UI 요소 목록에는 설명 목록 대신 일반 목록을 사용합니다.
설명 목록을 다른 스타일과 섞어 쓰지 않습니다.
Term 1
: Definition of Term 1
Term 2
: Definition of Term 2 is much longer, but we can use
multiple lines.
이러한 목록은 다음과 같이 렌더링됩니다.
Term 1 : Definition of Term 1
Term 2 : Definition of Term 2 is much longer, but we can use multiple lines.
목록#
목록을 사용하면 정보를 훑어보기 쉬운 형식으로 제시할 수 있습니다.
-
목록의 모든 항목을 병렬 구조로 만듭니다. 예를 들어 일부 항목은 명사로, 다른 항목은 동사로 시작하지 않습니다.
-
모든 항목을 대문자로 시작합니다.
-
모든 항목에 같은 문장부호를 사용합니다.
-
항목이 완결된 문장이 아니면 마침표를 사용하지 않습니다.
-
완결된 문장마다, 또는 도입 문구와 결합했을 때 완결된 문장이 되는 목록 항목마다 마침표를 사용합니다. 세미콜론이나 쉼표는 사용하지 않습니다.
-
도입 문구 뒤에 콜론(
:)을 추가합니다. 예:The basket contains these fruits: - Bananas - Apples -
목록에서 키워드나 개념을 정의하는 데 굵게 서식을 사용하지 않습니다. 굵게는 UI 요소 레이블에만 사용합니다. 예:
**Start a review**: This is a description of the button that starts a review.Offline environments: This is a description of offline environments.
-
목록 항목으로 도입 문구를 완성하지 않도록 합니다. 이 형식은 문장 구조가 다른 언어로 현지화하기 어려울 수 있습니다. 예를 들어 다음과 같이 씁니다.
You can get the license key in the following ways: - Copy the license key from the email. - Download the file.다음처럼 쓰지 않습니다.
You can get the license key by: - Copying it from the email. - Downloading the file.
순서 있는 목록과 순서 없는 목록 선택#
단계의 순서가 있으면 순서 있는 목록을 사용합니다. 예:
Follow these steps to do something.
1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.
단계를 순서대로 완료하지 않아도 되면 순서 없는 목록을 사용합니다. 예:
These things are imported:
- Thing 1
- Thing 2
- Thing 3
목록 마크업#
- 순서 없는 목록에는 별표(
*) 대신 대시(-)를 사용합니다. - 순서 있는 목록의 모든 항목을
1.로 시작합니다. 렌더링되면 목록 항목에 순서대로 번호가 매겨집니다. - 목록 앞뒤에 빈 줄을 둡니다.
- 중첩된 하위 항목을 나타내려면 줄을 공백(탭이 아님)으로 시작합니다.
목록 항목 안에 중첩#
다음 항목은 목록 항목 아래에 중첩할 수 있으며, 목록 항목과 같은 들여쓰기로 렌더링됩니다.
중첩된 항목은 항상 목록 항목의 첫 글자에 맞춰 정렬합니다.
순서 없는 목록(- 사용)에서는 들여쓰기 수준마다 공백 두 개를 사용합니다.
- Unordered list item 1
A line nested that uses 2 spaces to align with the `U` above.
- Unordered list item 2
> A quote block that will nest
> inside list item 2.
- Unordered list item 3
```plaintext
a code block that nests inside list item 3
```
- Unordered list item 4

순서 있는 목록에서는 들여쓰기 수준마다 공백 세 개를 사용합니다.
1. Ordered list item 1
A line nested that uses 3 spaces to align with the `O` above.
목록을 다른 목록 안에 중첩할 수 있습니다.
1. Ordered list item one.
1. Ordered list item two.
- Nested unordered list item one.
- Nested unordered list item two.
1. Ordered list item three.
- Unordered list item one.
- Unordered list item two.
1. Nested ordered list item one.
1. Nested ordered list item two.
- Unordered list item three.