텍스트와 서식
GitLab v19.6요약
서로 다른 마크업 사이(예: 문단, 제목, 목록 뒤)에는 빈 줄을 넣습니다. 소스 콘텐츠를 읽기 쉽게 하고 diff를 비교하기 쉽게 하려면 다음 모범 사례를 따릅니다. Markdown에 주석을 넣으려면 게시할 때 렌더링되지 않는 표준 HTML 주석을 사용합니다.
텍스트#
-
새 문단에는 빈 줄을 넣습니다.
-
서로 다른 마크업 사이(예: 문단, 제목, 목록 뒤)에는 빈 줄을 넣습니다. 예:
## Heading Paragraph. - List item 1 - List item 2
줄 길이#
소스 콘텐츠를 읽기 쉽게 하고 diff를 비교하기 쉽게 하려면 다음 모범 사례를 따릅니다.
- 긴 줄은 약 100자에서 나누되 링크는 나누지 않습니다.
- 논리적으로 묶이는 단어 사이에서는 줄을 나누지 않도록 하고, 같은 줄에 함께 둡니다.
- 새 문장은 새 줄에서 시작합니다.
예:
-
권장:
This long line talks about how to manage a GitLab Self-Managed instance deployed to Google Cloud for Education. -
비권장:
This long line talks about how to manage a GitLab Self-Managed instance deployed to Google Cloud for Education.
주석#
Markdown에 주석을 넣으려면 게시할 때 렌더링되지 않는 표준 HTML 주석을 사용합니다. 예:
<!-- This is a comment that is not rendered -->
페이지를 유지 관리하는 작성자가 세부 사항을 알아야 할 때 HTML 주석으로 메모를 남깁니다.
예: This table is autogenerated, edit 'path/to/file.rb' and run 'script.sh' to update the table.
문서를 숨기는 데 HTML 주석을 사용하지 않습니다. 자세한 내용은 문서를 숨기지 말고 삭제를 참조합니다.
문장부호#
문장부호에는 다음 지침을 따릅니다.
UI의 문장부호는 Pajamas를 참조합니다.
- 완결된 문장은 마침표로 끝냅니다.
- 항목이 세 개 이상인 목록에서는 마지막 and 또는 or 앞에 연속 쉼표(옥스퍼드 쉼표)를 사용합니다. (
OxfordComma.yml에서 테스트합니다.)
공백을 둘 때는 다음을 따릅니다.
- 문장 사이에는 공백을 하나 둡니다. (공백을 둘 이상 쓰는지는
SentenceSpacing.yml에서 테스트합니다.) - 줄 바꿈 없는 공백(non-breaking space)을 사용하지 않습니다. 대신 표준 공백을 사용합니다. (
lint-doc.sh에서 테스트합니다.) - 들여쓰기에 탭을 사용하지 않습니다. 대신 공백을 사용합니다. Tab 키를 눌렀을 때 탭 대신 공백이 입력되도록 코드 편집기를 설정하는 방안을 고려합니다.
다음 문장부호는 사용하지 않습니다.
;(세미콜론): 대신 문장을 둘로 나눕니다.–(en 대시) 또는—(em 대시): 대신 문장을 나누거나 쉼표를 사용합니다.“”‘’: 큰따옴표 또는 작은따옴표의 타이포그래퍼식("곡선") 따옴표입니다. 대신 곧은 따옴표를 사용합니다. (NonStandardQuotes.yml에서 테스트합니다.)
줄임표#
줄임표는 사용하지 않도록 합니다. 예를 들어 코드 블록이나 CLI 응답처럼 꼭 써야 한다면
공백 없이 마침표 세 개(...)를 사용합니다.
… HTML 엔티티나 … HTML 코드는 코드 블록 렌더링에 문제를 일으키므로
사용하지 않습니다.
UI 텍스트를 설명할 때는 줄임표를 포함하지 않습니다. 예를 들어 다음과 같이 씁니다.
- Search or go to
다음처럼 쓰지 않습니다.
- Search or go to...
자리표시자 텍스트#
코드 블록에서 특정 값을 사용하는 명령이나 구성을 제시해야 할 때가 있습니다.
이럴 때는 <와 >를 사용해
독자가 자신의 값으로 바꿔야 하는 위치를 표시합니다.
예:
cp <your_source_directory> <your_destination_directory>
자리표시자가 코드 블록 안에 있지 않으면 <와 >를 사용하고 자리표시자를
백틱 하나로 감쌉니다. 예:
Select **Grant admin consent for `<application_name>`**.
따옴표#
곧은 큰따옴표(")를 사용합니다.
작은따옴표(')는 다른 인용문 안의 인용문에만 사용합니다.
쉼표와 마침표는 닫는 따옴표 안에 둡니다. 다른 문장부호는 인용 텍스트의 일부가 아니면 닫는 따옴표 밖에 둡니다.
사용자 입력에는 따옴표를 쓰지 않도록 합니다. 대신 백틱을 사용합니다.
텍스트 서식#
텍스트에 서식을 적용할 때는 다음을 사용합니다.
- 입력, 출력, 코드 등에는 인라인 코드 스타일
- 명령줄 예시와 여러 줄 입력, 출력, 코드 등에는 코드 블록
- 키보드 명령에는
<kbd>
굵게#
키워드나 강조에 굵게를 사용하지 않습니다.
GitLab 19.5 이전에는 굵게를 다음 경우에만 사용하도록 했습니다.
- 화면에 표시되는 레이블이 있는 UI 요소
- 탐색 경로
이제는 UI 요소와 탐색 경로에 숏코드를 사용합니다.
숏코드를 사용하도록 아직 업데이트하지 않은 문서나 하드코딩된 문자열에는 여전히 굵게가 남아 있을 수 있습니다. 예:
- On the Issues page... (아직 업데이트되지 않음)
- Select Jenkins. (하드코딩됨)
인라인 코드#
인라인 코드는 백틱(`) 하나로 감싼 텍스트입니다. 예:
In the **Name** text box, enter `test`.
다음에 인라인 코드를 사용합니다.
- 사용자가 UI에 입력하는 텍스트
true,false,Job succeeded같은 짧은 입력과 출력- 파일 이름, 구성 매개변수, 키워드, 코드. 예:
.gitlab-ci.yml,--version,rules: - 짧은 오류 메시지
- API 및 HTTP 메서드(
POST) - HTTP 상태 코드. 전체(
404 File Not Found)와 약식(404) 모두 해당합니다. - HTML 요소. 예:
<sup>. 꺾쇠괄호를 포함합니다.
예:
- In the Name text box, enter
test. - Use the
rules:CI/CD keyword to control when to add jobs to a pipeline. - Send a
DELETErequest to delete the runner. Send aPOSTrequest to create one. - The job log displays
Job succeededwhen complete.
코드 블록#
코드 블록은 코드 텍스트를 일반 텍스트와 구분하며, 사용자가 복사해서 붙여넣을 수 있습니다.
다음에 코드 블록을 사용합니다.
코드 블록을 추가하려면 텍스트 위아래에 백틱 세 개(```)를 넣고,
올바른 구문 강조를 위해 맨 위에 구문 이름을 지정합니다. 예:
```markdown
This is a code block that uses Markdown to demonstrate **bold** and `backticks`.
```
코드 블록을 사용할 때는 다음을 따릅니다.
- 코드 블록 위아래에 빈 줄을 추가합니다.
- 지원되는 구문 이름
또는
opencypher중 하나를 사용합니다. 더 나은 선택지가 없으면plaintext를 사용합니다. - 코드 블록에 이미 백틱 세 개를 쓰는 다른(중첩) 코드 블록이 들어 있으면
백틱 네 개(
````)를 사용합니다. 위 예시는 코드 블록 형식을 보여 주려고 내부에서 백틱 네 개를 사용합니다.
코드 블록에서 빠진 정보를 나타내려면 주석이나 줄임표를 사용합니다. 예:
# Removed for readability// ...
키보드 명령#
키 입력을 설명할 때는 다음을 따릅니다.
- HTML
<kbd>태그를 사용합니다. - 키 조합에서
<kbd>태그 사이에 공백을 두지 않습니다. Alt를 제외하고 키의 전체 이름을 씁니다. (Vale 규칙:SubstitutionWarning.yml)- 동작 키이면 키 이름의 첫 글자를 대문자로 씁니다. 예:
Shift,Command,Delete. - 키가 문자이면 대문자를 사용합니다.
- 화살표에는
↑,↓,←,→를 사용합니다.
예:
To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.
이 예시는 다음과 같이 렌더링됩니다.
To stop the command, press Control+C.
기울임꼴과 강조#
제품 문서에서는 강조를 위한 기울임꼴을 사용하지 않도록 합니다. 대신 강조가 필요 없을 만큼 명확하게 내용을 작성합니다. GitLab과 https://docs.gitlab.com은 산세리프 글꼴을 사용하는데, 기울임꼴 텍스트는 산세리프를 쓰는 페이지에서 눈에 띄지 않습니다.
이모지#
:smile: 같은 Markdown 이모지 형식은 어떤 용도로도 사용하지 않습니다.
대신 GitLab SVG 아이콘을 사용합니다.