GitLab 음성
문서는 단일 정보 원천(SSoT)입니다
주제 유형
문서 우선 방법론
지역화 작성
Markdown
- Markdown에서의 HTML
- Markdown에서의 제목 레벨
언어
텍스트
텍스트 형식
목록
테이블
링크
내비게이션
일러스트레이션
- 스크린샷
- 다이어그램
  - 지침
  - 다이어그램 만들기

GitLab 문서 스타일 가이드

이 문서는 GitLab 문서 작성에 대한 표준을 정의하며, 문법, 서식 등을 포함합니다. 구체적인 단어에 대한 지침은 단어 목록을 참조하십시오.

GitLab 음성

GitLab 브랜드 가이드라인은 큰 조직에서 사용하는 음성을 정의합니다.

이 가이드라인을 바탕으로 GitLab 문서의 음성은 간결하고 명확하며 정확하려고 노력합니다. 목표는 쉽게 검색하고 스캔할 수 있는 정보를 제공하는 것입니다.

문서의 음성은 대화 형식이면서 간결하며 친근하면서도 간결해야 합니다.

문서는 단일 정보 원천(SSoT)입니다

GitLab 문서는 구현, 사용 및 문제 해결과 관련된 모든 제품 정보에 대한 SSoT입니다. 문서는 지속적으로 발전하며, 새로운 제품 및 기능과 명확성, 정확성 및 완전성 향상을 위해 업데이트됩니다.

이 정책은 정보 실로를 방지하여 GitLab 제품에 대한 정보를 찾기 쉽게 만듭니다. 또한 문서에 포함될 콘텐츠 종류에 대한 결정 사항을 알려줍니다.

주제 유형

GitLab은 주제 유형을 사용하여 제품 문서를 구성합니다.

주제 유형은 사용자가 정보를 더 빨리 파악하는 데 도움이 됩니다. 또한 다음과 같은 문제를 해결하는 데 도움이 됩니다.

콘텐츠가 찾기 어렵습니다. GitLab 문서는 포괄적이며 다양한 유용한 정보를 포함합니다. 주제 유형은 콘텐츠를 스캔하고 구문 분석하기 쉽게 하는 반복 가능한 패턴을 만듭니다.
콘텐츠는 종종 기여자의 관점에서 작성됩니다. GitLab 문서는 다양한 기여자에 의해 작성됩니다. 주제 유형(특히 작업)은 기능이 어떻게 구현되었는지 기록하는 것보다 다른 사람들을 돕는 형식으로 정보를 제공하는 데 도움이 됩니다.

문서 우선 방법론

제품 문서는 완전하고 신뢰할 수 있는 출처여야 합니다.

질문의 답이 문서에 있는 경우 정보를 다시 작성하는 대신 문서의 링크를 공유합니다.
GitLab 문서에 없는 정보를 만난 경우, 정보를 추가하기 위해 병합 요청(MR)를 생성합니다. 그런 다음 MR을 공유하여 해당 정보를 전달합니다.

문서에 정보를 반사적으로 추가할수록, 문서는 다른 사람들이 작업을 효율적으로 수행하고 문제를 해결하는 데 도움이 됩니다.

지역화 작성

GitLab 문서는 지역화되지 않지만, 전 세계적인 관객을 위해 작성하는 데 도움이 되는 지침을 따릅니다.

GitLab 음성은 번역을 염두에 두고 명확하고 직접적으로 작성해야 한다고 지시합니다. 저희의 스타일 가이드, 단어 목록 및 Vale 규칙을 통해 문서의 일관성을 보장합니다.

문서가 다른 언어로 번역될 때 각 단어의 의미가 명확해야 합니다. 기계 번역, GitLab Duo Chat 및 기타 AI 도구의 증가로 일관성은 더욱 중요해졌습니다.

다음 규칙들은 문서의 효율적인 번역을 돕습니다.

피하십시오:

존재한다 및 있다와 같이 주제를 숨기는 구문 there is 및 there are.
모호한 대명사 it.
-ing으로 끝나는 단어.
서로 혼동될 수 있는 단어 since 및 because.
라틴 약어 예를 들면 및 다시 말하면.

사용하십시오:

링크 텍스트의 표준 텍스트.
복잡한 문장 대신 목록 및 테이블.
AI 및 CI/CD와 같은 일반적인 약어 및 이전에 철자로 풀어쓴 약어.

또한, 다음 지침에 유의하십시오:

기능 이름 및 상호 작용 방법과 일관성 유지.
명사 문자열 분리. 예를 들어 프로젝트 통합 사용자 정의 설정 대신 프로젝트 통합을 위한 사용자 정의 설정을 사용합니다.
국제 관객을 대상으로 날짜 및 시간을 일관되게 서식화합니다.
스크린샷을 포함한 일러스트레이션을 절약해서 사용합니다.
UI 텍스트의 경우, 번역에서 최대 30% 확장 및 수축을 허용합니다. 다른 언어로 문자열이 얼마나 확장되거나 축소되는지 확인하려면 문자열을 Google 번역에 붙여넣고 결과를 확인합니다. 언어를 구사하는 동료에게 번역이 명확한지 확인해달라고 요청할 수 있습니다.

Markdown

모든 GitLab 문서는 Markdown으로 작성됩니다.

문서 웹사이트는 Markdown에서 HTML로 페이지를 렌더링하는 “flavored” Kramdown 엔진인 GitLab Kramdown을 사용합니다. Kramdown의 기능은 리터들에 의해 제한되므로 일반 Markdown을 사용하고 링크된 스타일 가이드의 규칙을 준수해야 합니다. Kramdown 특정 마크업(예: {:.class})을 사용할 수 없습니다.

Kramdown 전체 참조는 GitLab Markdown 가이드를 참조하십시오.

Markdown 형식은 markdownlint 및 Vale를 사용하여 테스트됩니다.

Markdown에서의 HTML

하드코딩된 HTML은 유효하지만 사용을 자제해야 합니다. HTML은 다음 경우에 허용됩니다.

Markdown에 해당하는 마크업이 없는 경우.
고급 테이블이 필요한 경우.
특별한 스타일이 필요한 경우.
기술 작성자가 검토 및 승인한 경우.

Markdown에서의 제목 레벨

각 문서 페이지는 레벨 1 제목(#)로 시작합니다. 이것은 페이지를 HTML로 렌더링할 때 h1 요소가 됩니다. 페이지당 하나의 레벨 1 제목만 가능합니다.

각 하위 섹션에 대해 제목 레벨을 증가합니다. 즉, 주제 제목 앞에 있는 # 문자의 수를 증가시킵니다.
H5(#####)보다 큰 제목 레벨은 피합니다. 다섯 개 이상의 제목 레벨이 필요한 경우 해당 주제를 새 페이지로 이동합니다. H5보다 큰 제목 레벨은 오른쪽 사이드바 탐색에 표시되지 않습니다.
레벨을 건너뛰지 마십시오. 예를 들어: ## > ####.
주제 제목 앞뒤로 한 줄을 비워둡니다.
주제 제목에 코드를 사용하는 경우 코드가 역따옴표에 있도록 합니다.
제목에서 굵은 텍스트를 사용하지 마십시오.

언어

GitLab 설명서는 명확하고 이해하기 쉬워야 합니다.

불필요한 단어는 피하십시오.
목적을 명확히하고 간결하게 작성하십시오.
미국 영어와 미국식 문법으로 작성하십시오. (British.yml에서 테스트됨).

능동태

대부분의 경우, 수동태 대신 능동태를 사용하면 텍스트를 이해하고 번역하기 쉬워집니다.

예를 들어, 사용하세요:

개발자는 응용 프로그램을 위해 코드를 작성합니다.

대신에:

응용 프로그램 코드는 개발자에 의해 작성됩니다.

때로는 GitLab을 주어로 사용하는 것이 어색할 수 있습니다. 예를 들어 GitLab이 보고서를 내보냅니다 이 경우 수동태 대신에 사용할 수 있습니다. 예를 들어, 보고서가 내보내집니다.

고객 관점

고객 관점에서 GitLab이 제공하는 기능과 이점에 초점을 맞추십시오, GitLab이 작성한 것 대신에.

예를 들어, 사용하세요:

병합 요청을 사용하여 소스 및 대상 브랜치에 있는 코드를 비교합니다.

대신에:

GitLab은 코드 비교를 허용합니다.
GitLab은 코드를 비교할 수 있도록 만들었습니다.
병합 요청을 사용하여 코드를 비교할 수 있습니다.

고객 관점에서 쓴 것이 아님을 나타내는 단어들은 허용 및 사용합니다. 대신에 당신을 사용하여 사용자에게 직접적으로 말할 수 있습니다.

신뢰 구축

제품 설명서는 판매나 마케팅 텍스트를 추가하지 않고 명확하고 간결한 정보에 중점을 두어야 합니다.

쉽게나 간단히와 같은 단어를 사용하지 마십시오.
“이 기능은 시간과 돈을 절약할 것입니다”와 같은 마케팅 구문을 사용하지 마십시오.

대신에 사실과 실현 가능한 목표에 초점을 맞추십시오. 구체적으로 말하십시오. 예를 들어:

이 기능을 사용하면 빌드 시간을 줄일 수 있습니다.
프로젝트를 만들 때 이 기능을 사용하여 시간을 절약할 수 있습니다. API가 파일을 생성하고 수동적으로 개입할 필요가 없습니다.

대문자

회사로서 우리는 소문자를 선호합니다.

주제 제목

주제 제목에는 문장 케이스를 사용하십시오. 예를 들어:

# 변수를 사용하여 파이프라인 구성
## 할 일 목록 사용하기

UI 텍스트

특정 사용자 인터페이스 텍스트(버튼 라벨, 페이지, 탭, 메뉴 항목 등)를 참조할 때는 사용자 인터페이스에 표시된 캐피털라이제이션을 사용하십시오.

사용자 인터페이스 텍스트에 스타일 오류가 있다고 생각되는 경우, 사용자 인터페이스 텍스트에 변경 제안을 하기 위해 이슈나 MR을 만드십시오.

기능 이름

기능 이름은 소문자여야 합니다.

그러나 몇 가지 드문 경우에는 기능 이름을 대문자로 표기할 수 있습니다. 이러한 예외 사항들은 다음과 같습니다:

markdownlint에 proper name으로 추가되어 있기 때문에 모든 문서에 일관되게 적용할 수 있습니다.
word list에 추가되어 있습니다.

단어 목록에 없는 경우, GitLab 기술 작성자에게 조언을 구하십시오.

기본적으로 기능 페이지나 features.yml의 용어나 구문에 캐피털라이제이션을 맞추지 마십시오.

다른 용어들

대문자로 쓰는 용어들:

GitLab 제품 계층. 예를 들어, GitLab 무료 및 GitLab 얼티밋.
제3자 조직, 소프트웨어, 제품 이름. 예를 들어, 프로메테우스, 쿠버네티스, Git, 더 리눅스 재단.
방법 또는 방법론들. 예를 들어, 지속적 통합, 지속적 배포, 스크럼 및 애자일.

해당 엔티티에 대한 권위 있는 소스의 대문자 케이스 스타일을 따르십시오. 이때 사용하는 사례의 정보원이 주체의 공식 스타일을 사용할 수 있습니다. 예를 들어: GitLab과 npm.

가짜 사용자 정보

REST 호출 또는 사용자 프로필과 같은 항목에 가짜 사용자 정보를 포함해야 할 수 있습니다. GitLab 설명서에 실제 사용자 정보나 이메일 주소를 사용하지 마십시오.

이메일 주소와 이름에 대해서는 다음을 사용하십시오:

이메일 주소: example.com로 끝나는 이메일 주소를 사용하십시오.
이름: example_username과 같은 문자열을 사용하십시오. 또는 일반성 있거나 성별이나 국가에 따라 다를 수 있는 일반적인 성에 함께 사용되는 이름을 사용하십시오. 예를 들어 Sidney Jones, Zhang Wei, 또는 Alex Garcia 등을 사용하십시오.

가짜 URL

설명서에 샘플 URL을 포함할 때 다음을 사용하십시오:

일반적인 도메인 이름인 경우 example.com을 사용하십시오.
자체 관리형 GitLab 인스턴스에만 해당되는 경우 gitlab.example.com을 사용하십시오. GitLab SaaS 인스턴스의 경우 gitlab.com을 사용하십시오.

가짜 토큰

cURL을 사용하여 API 호출을 보여주거나 CI에서 사용되는 변수를 보여주기 위해 가짜 토큰이 필요할 수 있습니다. 낮은 확률로 토큰이 악용되더라도 문서에 실제 토큰을 사용하는 것은 강력히 권장하지 않습니다.

다음과 같은 가짜 토큰을 예로 사용할 수 있습니다:

토큰 유형	토큰 값
개인 엑세스 토큰	`<your_access_token>`
애플리케이션 ID	`2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6`
애플리케이션 시크릿	`04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df`
CI/CD 변수	`Li8j-mLUVA3eZYjPfd_H`
프로젝트 러너 토큰	`yrnZW46BrtBFqM7xDzE7dddd`
공유 러너 토큰	`6Vk7ZsosqQyfreAxXTZr`
트리거 토큰	`be20d8dcc028677c931e04f3871a9b`
웹훅 시크릿 토큰	`6XhDroRcYPM5by_h-HLY`
헬스 체크 토큰	`Tu7BgjR9qeZTEyRzGG2P`

줄임말

줄임말은 장려되며 튜토리얼, 교육 문서 및 사용자 인터페이스에서 편안하고 비공식적인 어조를 만들 수 있습니다.

그러나 일부 줄임말은 피해야 합니다:

줄임말 사용 금지	예	대신 사용
명사과 동사를 함께 사용할 때 줄임말 사용	Terraform’s a helpful tool.	Terraform is a helpful tool.
부정을 강조하기 위해 사용하는 경우	Don’t install X with Y.	Do not install X with Y.
참조 문서에서 사용하는 경우	Don’t set a limit.	Do not set a limit.
오류 메시지에서 사용하는 경우	Requests to localhost aren’t allowed.	Requests to localhost are not allowed.

소유격

프로퍼 네임(예: 조직이름 또는 제품명)에 대한 소유격('s) 사용을 피하십시오.

예: Docker's CLI 대신 the Docker CLI를 사용하세요.

자세한 내용은 Google 문서 스타일 가이드를 참조하세요.

전치사

필요한 경우 문장 끝에 전치사를 사용하세요. 문단 맨 끝에 놔두거나 떨어뜨린 전치사를 사용하는 것도 좋습니다.

예: - 그룹을 떠날 수 있습니다. - 액세스를 부여하려는 사용자와 자격 증명을 공유하세요.

이러한 구조는 대안에 비해 좀 더 캐주얼합니다.

그룹을 탈퇴할 수 있습니다.
액세스를 부여하고 싶은 사용자들과 자격 증명을 공유하세요.

약어

약어를 사용하는 경우 페이지에서 처음 사용할 때 이를 전체 단어로 풀어쓰세요. 한 페이지에서 한 번 이상 이를 다시 풀어쓸 필요는 없습니다.

제목: 특히 널리 사용되지 않는 경우 약어를 토픽 제목에서 피하세요.
복수: 약어를 복수로 만들지 마십시오. 예를 들어 YAML files 대신 YAMLs를 사용하지 마십시오. 반드시 약어를 복수로 만들어야 하는 경우 아포스트로피를 사용하지 마십시오. 예를 들어 APIs 대신 API's를 사용하지 마십시오.
소유격: 약어를 소유격으로 만들 때 주의하세요. 가능하다면 소유격이 되지 않도록 문장을 작성하세요. 만약 약어를 소유격으로 만들어야 한다면 단어를 완전히 풀어서 쓰는 것을 고려하세요.

숫자

텍스트에서 숫자를 표현할 때 0부터 9까지는 숫자로 표기하고, 10 이상은 숫자로 표기하세요. 자세한 내용은 Microsoft 스타일 가이드를 참조하세요.

텍스트

Markdown으로 작성.
새 단락을 나타내려면 빈 줄을 삽입하세요.
서로 다른 마크업 사이(예: 각 문단, 제목, 목록 등 뒤)에 빈 줄을 삽입하세요. 예:
```
## 제목

문단.

- 목록 항목 1
- 목록 항목 2
```

줄 길이

소스 콘텐츠를 읽기 쉽게 만들고 변경 사항을 쉽게 비교하기 위해 가능한 경우 다음과 같은 가이드라인을 따르세요.

긴 줄은 대략 100자로 분리하세요.
각 새로운 문장을 새 줄에 시작하세요.

코멘트

Markdown 내에서 코멘트를 삽입하려면 게시될 때 렌더링되지 않는 표준 HTML 주석을 사용하세요. 예시:

<!-- 이것은 렌더링되지 않는 코멘트입니다 -->

구두점

구두점을 사용할 때 다음 가이드라인을 따르세요.

문장 끝에는 마침표를 찍으며, 테이블의 전체 문장도 마침표를 찍으세요.
세 개 이상의 항목 목록에서 마지막 and 또는 or 앞에 Oxford 쉼표(시리얼 쉼표)를 사용하세요. OxfordComma.yml에서 테스트됨.

콘텐츠 간격을 조정할 때:

문장 사이에는 한 칸의 공백을 사용하세요. (한 칸 이상의 공백 사용은 SentenceSpacing.yml에서 테스트됨.)
줄 띄우기에는 준위 공백을 사용하지 마세요. 대신 일반 공백을 사용하세요. (스크립트 lint-doc.sh에서 테스트됨.)
들여쓰기에 탭 대신 일반 공백을 사용하세요. 코드 편집기를 구성하여 Tab 키를 누르면 탭 대신 공백이 출력되도록 할 수 있습니다.

다음 구두점 문자를 사용하지 마십시오.

; (세미콜론): 두 문장으로 대체하세요.
–(엔 대쉬) 또는 — (엠 대쉬): 대신 각각 문장으로, 또는 쉼표로 사용하세요.
“ ” ‘ ’: 곧은 따옴표 대신 곡선 따옴표(“curly quotation marks”)를 사용하지 마십시오. NonStandardQuotes.yml에서 테스트됨.

자리 표시자 텍스트

코드 블록 내에서 독자가 특정 값으로 텍스트를 교체해야 할 경우, < and >를 사용하여 표시하세요.

예를 들어:

cp <your_source_directory> <your_destination_directory>

플레이스홀더가 코드 블록 내에 없는 경우, < 와 >를 사용하고 플레이스홀더를 역작은따옴표(`)로 감싸세요.

**<application_name>에 대한 관리자 동의 부여** 선택하세요.

따옴표

따옴표는 직접적인 텍스트를 인용할 때에만 사용하고, 이중 따옴표(")를 사용하세요. UI 요소와 인라인 코드에 대한 가이드는 Text formatting를 참조하세요.

인용된 텍스트가 아닌 경우 구두점을 따옴표 안으로 넣지 마세요.

텍스트 형식

텍스트 형식을 지정할 때 다음을 사용하세요:

UI 요소와 페이지에 대한 볼드.
입력, 출력, 코드 등에 대한 인라인 코드 스타일.
명령어 라인 예제 및 멀티라인 입력, 출력, 코드 등에 대한 코드 블록.
키보드 명령어에 대한 <kbd>.

볼드

다음에 대해 볼드를 사용하세요:

눈에 띄는 라벨을 가진 UI 요소. 라벨의 텍스트와 대소문자가 일치해야 합니다.
네비게이션 경로.

UI 요소로는 다음을 포함합니다:

버튼
체크박스
설정
메뉴
페이지
탭

예를 들어:

취소를 선택하세요.
이슈 페이지에서…
파이프라인 탭에서…

텍스트를 볼드체로 만들려면 텍스트를 이중 별표(**)로 감싸세요. 예:

1. **취소**를 선택하세요.

인라인 코드

인라인 코드는 다음에 사용하세요:

UI에 입력되는 텍스트.
true, false, 작업 성공과 같은 짧은 입력 및 출력.
파일 이름, 설정 매개변수, 키워드 및 코드. 예를 들어: .gitlab-ci.yml, --version, 또는 rules:.
작은 오류 메시지.
API 및 HTTP 메소드 (POST).
HTTP 상태 코드. 전체(404 File Not Found) 및 약식(404).

예:

이름 텍스트 상자에 test를 입력하세요.
rules: CI/CD 키워드를 사용하여 파이프라인에 작업을 추가할 때 통제하세요.
Runner를 삭제하려면 DELETE 요청을 보내세요. Runner를 생성하려면 POST 요청을 보내세요.
작업 로그에 작업 성공이 표시됩니다.

인라인 코드를 사용하려면 텍스트를 역작은따옴표 하나로 감싸세요. 예:

**이름** 텍스트 상자에 `test`를 입력하세요.

코드 블록

코드 블록은 일반 텍스트와 코드 텍스트를 구분하며 사용자가 복사하여 붙일 수 있습니다.

코드 블록 사용 사례:

CLI 및 cURL 명령어.
여러 줄의 입력, 출력 및 코드 샘플을 인라인 코드로 표현하기에 너무 큰 경우.

코드 블록을 추가하려면 위와 아래에 삼중 역따옴표 (```)를 추가하고, 적절한 구문 이름을 작성합니다. 예를 들면:

```markdown
이것은 Markdown을 사용하여 **굵은** 및 `백틱`을 나타내는 코드 블록입니다.
```

코드 블록 사용 시:

코드 블록 위와 아래에 공백 라인을 추가합니다.
지원되는 구문 이름 중 하나를 사용합니다. 더 나은 옵션이 없는 경우 plaintext를 사용합니다.
코드 블록에 이미 삼중 역따옴표가 포함된 경우, 해당 코드 블록에 대한 콘텐츠를 나타내기 위해 삼중 역따옴표가 이미 있는 (중첩된) 코드 블록이 포함된 경우 사중 역따옴표 (````)를 사용합니다. 위의 예제는 코드 블록 형식을 설명하기 위해 내부적으로 사중 역따옴표를 사용합니다.

키보드 명령

키보드 키를 누르는 경우 HTML <kbd> 태그를 사용합니다. 예를 들면:

명령을 중지하려면 <kbd>Control</kbd>+<kbd>C</kbd>를 누르세요.

이 예제는 다음과 같이 렌더링됩니다:

명령을 중지하려면 Control+C를 누르세요.

이탤릭체와 강조

제품 설명서에서 강조에 이탤릭체 사용을 피합니다. 대신 강조가 필요하지 않은 명확한 콘텐츠를 작성합니다. GitLab 및 https://docs.gitlab.com은 산세리프 글꼴을 사용하지만, 이탤릭체 텍스트는 산세리프 글꼴을 사용한 페이지에서 돋보이지 않습니다.

정보를 쉽게 스캔할 수 있는 형식으로 제시하기 위해 목록을 사용합니다.

목록에서 모든 항목을 평행하게 작성합니다. 예를 들어, 일부 항목을 명사로 시작하고 다른 항목을 동사로 시작하지 않습니다.
모든 항목을 대문자로 시작합니다.
모든 항목에 동일한 구두점을 사용합니다.
항목이 완전한 문장이 아닌 경우 마침표를 사용하지 않습니다.
모든 완전한 문장 뒤에 마침표를 붙입니다. 세미콜론이나 쉼표를 사용하지 않습니다.

소개 구문 뒤에 콜론(:)을 추가합니다. 예를 들어:

다음을 할 수 있습니다:

- 이 작업을 수행합니다.
- 다른 작업을 수행합니다.

정렬 목록 또는 비정렬 목록 선택

단계의 시퀀스를 나타내려면 정렬된 목록을 사용합니다. 예를 들어:

무언가를 수행하려면 다음 단계를 따르세요.

먼저, 첫 번째 단계를 수행합니다.
그런 다음, 다음 단계를 수행합니다.
마지막으로, 마지막 단계를 수행합니다.

단계를 순서대로 수행할 필요가 없는 경우 비정렬 목록을 사용합니다. 예를 들어:

다음 항목이 가져옵니다:

- 항목 1
- 항목 2
- 항목 3

목록 마크업

별표(*) 대신 대시(-)를 사용하여 비정렬 목록을 나타냅니다.
정렬된 목록의 각 항목을 1.로 시작합니다. 렌더링될 때 목록 항목이 시퀀셜하게 표시됩니다.
목록 앞뒤로 공백 라인을 남깁니다.
들여쓴 하위 항목을 나타내기 위해 줄을 시작할 때 공백(탭이 아님)을 사용합니다.

목록 항목 내의 중첩

목록 항목 아래에 아이템을 중첩하여 동일한들여쓰기로 렌더링할 수 있습니다. 이를 위해 다음을 사용할 수 있습니다:

코드 블록
인용구
알림 상자
일러스트레이션
탭

중첩된 항목은 항상 목록 항목의 첫 번째 문자와 정렬해야 합니다. 비정렬 목록(대시(-) 사용)의 경우 각 인덴트 수준에 2개의 공백을 사용합니다:

- 비정렬 목록 항목 1

  `U`와 정렬하기 위해 2개의 공백을 사용하여 중첩된 줄입니다.

- 비정렬 목록 항목 2

  > 목록 항목 2에 중첩될 인용 블록
  > 입니다.

- 비정렬 목록 항목 3

  ```plaintext
  목록 항목 3에 중첩될 코드 블록
  ```

- 비정렬 목록 항목 4

  ![목록 항목 4에 중첩될 이미지](image.png)

정렬된 목록의 경우 각 인덴트 수준에 3개의 공백을 사용합니다:

1. 정렬된 목록 항목 1

   `O`와 정렬하기 위해 3개의 공백을 사용하여 중첩된 줄입니다.

목록 내에 목록을 중첩할 수 있습니다.

1. 정렬된 목록 항목 1.
1. 정렬된 목록 항목 2.
   - 중첩된 비정렬 목록 항목 1.
   - 중첩된 비정렬 목록 항목2.
1. 정렬된 목록 항목 3.

- 비정렬 목록 항목 1.
- 비정렬 목록 항목 2.
  1. 중첩된 정렬 목록 항목 1.
  1. 중첩된 정렬 목록 항목 2.
- 비정렬 목록 항목 3.

테이블

테이블은 복잡한 정보를 간단하게 설명하기 위해 사용되어야 합니다. 많은 경우, 단일 간단한 설명을 가진 항목 목록을 설명하기에 비정렬 목록이 충분하지만, 매트릭스로 설명하는 것이 가장 적합한 데이터가 있다면 테이블을 사용합니다.

생성 가이드라인

비어 있는 셀이 없도록하여 테이블이 접근하기 쉽고 스캔하기 쉽도록 해야 합니다. 셀에 의미가 없는 경우 ‘해당 없음’을 나타내는 N/A 또는 None을 입력하는 것을 고려합니다.

테이블을 유지 보수하기 쉽게 하기 위해 열 너비를 일관되게 만들기 위해 추가 공백을 추가할 수 있습니다. 예를 들어:

  | 앱 이름 | 설명               | 요구 사항      |
  |--------|---------------------|--------------|
  | 앱 1   | 설명 텍스트 1.     | A, B 및 C.    |
  | 앱 2   | 설명 텍스트 2.     | 해당 없음      |

매우 넓은 테이블의 경우 오른쪽 열에 추가 공백을 건너뛸 수 있습니다. 예를 들어:

  | 설정     | 기본값 | 설명                    |
  |---------|---------|-----------------------|
  | 설정 1  | `1000`  | 간단한 설명         |
  | 설정 2  | `2000`  | 이 열의 각 셀이 정렬된 경우 테이블이 너무 넓어지고 공백이 너무 많이 추가되므로 추가 공백을 건너뛸 수 있습니다.  |
  | 설정 3  | `0`     | 다른 간단한 설명   |

테이블 형식 지정을 위한 에디터 확장 기능

모든 Markdown 파일에서 일관된 테이블 형식을 보장하려면 VS Code Markdown Table Formatter를 사용하여 테이블을 형식화하는 것을 고려해보세요. 이 기능을 위해, 다음 가이드라인을 따르도록 이 확장을 구성하세요: Follow header row length 설정을 활성화하세요.

설정을 활성화하려면:

UI에서:
1. VS Code 메뉴에서 Code > Settings > Settings로 이동하세요.
2. Limit Last Column Length를 검색하세요.
3. 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 Command Palette에서 Markdown Table Formatter를 선택하세요.

또는, Sublime Text를 사용하는 경우 Markdown Table Formatter 플러그인을 시도해볼 수 있지만, Follow header row length 설정은 없습니다.

기존 테이블 업데이트

기존 테이블에 행을 추가하거나 편집할 때 새로운 행의 셀이 더 넓을 수 있습니다. 너비를 고려하여 열을 다시 정렬하면, 전체 테이블이 수정된 것으로 표시되어 diff를 읽기 어려워집니다.

Markdown 테이블은 시간이 지남에 따라 자연스럽게 정렬이 어긋날 수 있지만, 여전히 docs.gitlab.com에 올바르게 렌더링됩니다. 기술 문서 작성 팀은 페이지가 다음에 리팩터링될 때 셀을 재정렬할 수 있습니다.

테이블 머리글

테이블 머리글에는 문장 케이스를 사용하세요. 예를 들면, Keyword value 또는 Project name과 같이요.

기능 테이블

기능(예: 권한 페이지에서 각 역할에 대한 사용 가능한 기능 목록의 테이블)의 목록 테이블을 만들 때, 다음 구문을 사용하세요:

옵션	마크다운	표시 결과
아니오	`{dotted-circle} 아니오`	아니오
예	`{check-circle} 예`	예

API 문서에서 **{dotted-circle}** 및 **{check-circle}**를 사용하지 마세요. 대신, API 주제 템플릿을 따르세요.

각주

테이블 자체에 내용을 포함할 수 없는 경우에만 테이블 아래에 각주를 사용하세요. 예를 들어, 다음과 같은 경우에 각주를 사용하세요:

여러 테이블 셀에서 동일한 정보를 제공해야 하는 경우.
테이블 레이아웃을 방해할 수 있는 콘텐츠를 포함해야 하는 경우.

각주 형식

테이블에서 각주를 사용하려면, 각주를 위해 HTML 슈퍼스크립트 태그 <sup>을 사용하세요. 문장 끝에 태그를 넣으세요. 문장과 태그 사이에 한 칸의 공백을 남겨주세요.

예를 들어:

| 앱 이름  | 설명                           |
|:--------|:------------------------------|
| 앱 A    | 설명 텍스트. <sup>1</sup>     |
| 앱 B    | 설명 텍스트. <sup>2</sup>     |

각주를 추가할 때는 기존의 태그를 재정렬하지 마세요.

테이블 아래에 각주를 추가할 때, **각주:** 다음에 정렬된 목록을 사용하세요.

예를 들어:

**각주:**

1. 이것은 첫 번째 각주입니다.
1. 이것은 두 번째 각주입니다.

테이블과 각주는 다음과 같이 렌더링됩니다:

앱 이름	설명
앱 A	설명 텍스트. ¹
앱 B	설명 텍스트. ²

각주:

이것은 첫 번째 각주입니다.
이것은 두 번째 각주입니다.

다섯 개 이상의 각주

테이블 자체에 포함할 수 없는 다섯 개 이상의 각주가 있는 경우, 목록 항목에 연속된 번호를 사용할 수 있습니다. 연속된 번호를 사용하는 경우, Markdown rule 029를 비활성화해야 합니다:

**각주:**

<!-- Markdown 규칙 https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029 비활성화 -->
<!-- markdownlint-disable MD029 -->

1. 이것은 첫 번째 각주입니다.
2. 이것은 두 번째 각주입니다.
3. 이것은 세 번째 각주입니다.
4. 이것은 네 번째 각주입니다.
5. 이것은 다섯 번째 각주입니다.

<!-- markdownlint-enable MD029 -->

링크

링크는 문서가 단일 진실의 근원 원칙을 준수하는 데 도움이 됩니다.

다만 한 페이지에 너무 많은 링크를 넣는 것은 피해야 합니다. 너무 많은 링크는 가독성을 해치게 됩니다.

같은 페이지에서 링크를 중복해서 사용하지 마세요. 예를 들어, 페이지 A에서 페이지 B를 여러 번 링크하지 마세요.
제목에 링크를 사용하지 마세요. 소제목은 링크로 렌더링되며, 링크가 포함된 소제목은 오류를 발생시킵니다.
한 단락에 여러 개의 링크를 사용하지 마세요.
한 작업에서 여러 링크를 사용하지 마세요.
한 페이지에서 다른 페이지로의 링크가 15개를 넘지 않도록 하세요.
관련 주제를 사용하여 작업 흐름을 방해하는 링크를 줄이세요.
같은 페이지의 섹션에 앵커 링크를 사용하지 마세요. 사용자가 오른쪽 탐색을 의존하도록 하세요.

동일 저장소 내의 링크

동일 저장소의 다른 문서(.md) 파일에 링크하려면:

상대 파일 경로를 사용한 인라인 링크를 사용하세요. 예를 들어, [GitLab.com 설정](../user/gitlab_com/index.md)와 같이요.
링크가 아주 길어지더라도 링크 전체를 한 줄에 넣으세요. (Vale 규칙: SubstitutionWarning.yml).

문서 파일 외부의 파일에 링크하려면, 예를 들어 개발 문서에서 특정 코드 파일로 링크하려면:

전체 URL을 사용하세요. 예를 들어: [`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/help/show.html.haml)
(선택 사항) 특정 ref가 포함된 전체 URL을 사용하세요. 예를 들어: [`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/6d01aa9f1cfcbdfa88edf9d003bd073f1a6fff1d/app/views/help/show.html.haml)

서로 다른 저장소에 있는 링크

다른 저장소의 페이지에 링크하려면 전체 URL을 사용합니다. 예를 들어, GitLab 저장소의 페이지에서 Charts 저장소로 링크하려면 [GitLab Charts documentation](https://docs.gitlab.com/charts/)와 같은 URL을 사용하십시오.

앵커 링크

각 주제 제목에는 앵커 링크가 있습니다. 예를 들어, 제목이 ## This is an example인 주제에는 #this-is-an-example 앵커가 있습니다.

페이지의 첫 번째 주제 제목( h1)에는 앵커 링크가 있지만 사용하지 마십시오. 대신 페이지에 링크합니다.

Kramdown을 사용하면 HTML 요소에 사용자 정의 ID를 추가할 수 있지만, 이러한 ID는 /help에서 작동하지 않으므로 사용하지 마십시오.

주제 제목 텍스트를 변경하면 앵커 링크도 변경됩니다. 링크가 깨지지 않도록 하려면:

주제 제목에 단계 번호를 사용하지 마십시오.
가능한 경우, 미래에 변경될 수 있는 단어를 사용하지 마십시오.

링크와 제목 변경

주제 제목을 변경하면 앵커 링크도 변경됩니다. 관련된 링크를 업데이트하려면 다음 디렉토리에서 검색하십시오:

doc/*
app/views/*
ee/app/views/*

이러한 링크를 수정하지 않으면, 병합 요청에서의 ui-docs-lint 작업이 실패할 수 있습니다.

링크 텍스트

링크 텍스트에 대해 다음 지침을 따르십시오.

표준 텍스트

가능한 한 다음 중 하나의 패턴을 따르는 텍스트를 사용하십시오:

자세한 정보는 [링크 텍스트](link.md)를 참조하십시오.
이 작업을 하려면 [링크 텍스트](link.md)를 참조하십시오.

예를 들어:

자세한 정보는 [병합 요청](link.md)을 참조하십시오.
리뷰 앱을 만들려면 [리뷰 앱](link.md)을 참조하십시오.

이러한 텍스트를 사용하여 “이 기능에 대한 자세한 정보는…“과 같은 구문을 사용하여 텍스트를 확장할 수 있습니다.

다음 구조를 사용하지 마십시오:

“더 알아보기…”
“더 읽기…”
“자세한 정보는 병합 요청 페이지를 참조하십시오.”
“자세한 정보는 병합 요청 문서를 참조하십시오.”

`here`보다 서술적인 텍스트 사용

링크에 대해 here나 이 페이지와 같은 단어 대신 서술적인 텍스트를 사용하십시오.

예를 들어, 다음 대신:

자세한 정보는 [이 페이지](link.md)를 참조하십시오.
자세한 정보는 [여기](link.md)를 방문하십시오.

다음을 사용하십시오:

자세한 정보는 [병합 요청](link.md)을 참조하십시오.

이슈에 대한 링크

이슈에 링크를 걸 때, 링크에 이슈 번호를 포함하십시오. 예를 들어:

자세한 정보는 [이슈 12345](link.md)를 참조하십시오.

issue #12345와 같이 샵 기호(#)를 사용하지 마십시오.

외부 문서에 대한 링크

가능한 경우, 외부 문서에 대한 링크를 피하십시오. 이러한 링크는 쉽게 오래된 상태가 되며 유지 관리가 어렵습니다.

링크로트로 이어집니다.
유지 관리에 문제점을 만듭니다.

때로는 링크가 필요할 수 있습니다. 이는 문제 해결 단계를 명확히하는 데 도움이 되거나 콘텐츠의 중복을 방지하는 데 도움이 될 수 있습니다. 때로는 더 정확하고 더 활발하게 유지될 수 있습니다.

추가하는 각 외부 링크에 대해 고객 이점을 유지 관리의 어려움과 저울질하십시오.

기밀 또는 제한된 액세스 링크

다음에 직접 링크하지 마십시오:

기밀적인 이슈.
내부 핸드북 페이지.
특별한 권한이 필요한 프로젝트 기능을 보려면.

이러한 링크는 충분한 권한이 없는 사용자나 자동화된 링크 확인자에게 실패할 수 있습니다.

이러한 링크 중 하나를 사용해야 하는 경우:

링크가 기밀적인 이슈나 내부 핸드북 페이지에 대한 것이라면 해당 이슈나 페이지가 GitLab 팀 멤버에게만 표시된다는 사실을 언급하십시오.
링크가 특정 역할이나 권한이 필요하다면 해당 정보를 언급하십시오.
링크를 역따옴표 안에 넣어서 링크 확인자가 실패하지 않도록 하십시오.

예시:

GitLab 팀 멤버들은 이 기밀적인 이슈에서 더 많은 정보를 확인할 수 있습니다:
`https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>`

GitLab 팀 멤버들은 이 내부 핸드북 페이지에서 더 많은 정보를 확인할 수 있습니다: https://internal.gitlab.com/handbook/<link>

이 프로젝트의 Maintainer 역할을 가진 사용자는 파이프라인 편집기를 사용할 수 있습니다:
`https://gitlab.com/gitlab-org/gitlab/-/ci/editor`

코드의 특정 라인에 대한 링크

특정 파일의 특정 라인에 링크할 때, 브랜치 대신 커밋에 링크하십시오. 코드 라인은 시간이 지남에 따라 변경됩니다. 커밋 링크를 사용하여 특정 코드 라인에 유저가 참조할 수 있도록 하십시오. 프로젝트의 파일을 볼 때 표시되는 퍼머링크 버튼을 클릭하면 해당 파일의 가장 최근 커밋에 대한 링크가 제공됩니다.

올바른 사용법: [3번 라인에 대한 링크](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
잘못된 사용법: [3번 라인에 대한 링크](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).

만약 해당 링크된 표현이 추가적인 커밋으로 인해 라인 번호가 변경된 경우, 그 쿼리에 대해 파일을 여전히 검색할 수 있습니다. 이 경우 문서를 업데이트하여 해당 파일의 가장 최신 버전에 대한 링크가 되도록 하십시오.

항상 위치를 먼저, 그런 다음 동작을 사용하십시오.
- 가시성 드롭다운 목록(위치)에서 공개를 선택합니다(동작).
간결하고 구체적으로 해야 합니다. 예를 들어:
- 할 때: 저장을 선택합니다.
- 하지 말아야 할 것: 변경 사항을 적용하려면 저장을 선택합니다.
단계가 이유를 포함해야 하는 경우, 단계를 이유부터 시작하십시오. 이것은 사용자가 빨리 스캔할 수 있도록 도와줍니다.
- 할 때: 변경 사항을 보려면, 병합 요청에서 링크를 선택합니다.
- 하지 말아야 할 것: 변경 사항을 보려면 병합 요청에서 링크를 선택합니다.

메뉴 이름

메인 GitLab 사용자 인터페이스 요소를 참조할 때 다음 용어를 사용하십시오.

왼쪽 사이드바: 사용자 인터페이스의 왼쪽에 있는 탐색 사이드바입니다.
- context switcher 또는 switch contexts 구문을 사용하지 마세요. 대신, 일련의 반복 가능한 단계로 사용자를 정확한 위치로 안내하십시오.
- 탐색 메뉴나 작업내역 사이드바와 같은 구문 대신에 왼쪽 사이드바를 사용하십시오.
오른쪽 사이드바: 열린 이슈, 병합 요청 또는 에픽에 특정한 사용자 인터페이스의 오른쪽에 있는 탐색 사이드바입니다.

UI 요소의 이름

모든 UI 요소는 굵게 표시되어야 합니다.

개별 UI 요소에 대한 지침은 단어 목록에 있습니다.

탐색 작업 단계 작성 방법

일관성을 유지하기 위해, 작업 주제의 탐색 단계를 작성하는 데 이러한 예제를 사용하십시오. 대체 단계가 있을 수 있지만, 기본적으로 고정된 항목을 포함하여 이러한 단계를 사용하십시오.

프로젝트 설정 열기:

왼쪽 사이드바에서 **검색 또는 이동**을 선택하고 프로젝트를 찾습니다.
**설정 > CI/CD**를 선택합니다.
**일반 파이프라인**을 확장합니다.

그룹 설정 열기:

왼쪽 사이드바에서 **검색 또는 이동**을 선택하고 그룹을 찾습니다.
**설정 > CI/CD**를 선택합니다.
**일반 파이프라인**을 확장합니다.

프로젝트 또는 그룹 설정 열기:

왼쪽 사이드바에서 **검색 또는 이동**을 선택하고 프로젝트 또는 그룹을 찾습니다.
**설정 > CI/CD**를 선택합니다.
**일반 파이프라인**을 확장합니다.

프로젝트 만들기:

1. 왼쪽 사이드바에서 맨 위에서 **새로 만들기** (**{plus}**)를 선택하고 **새 프로젝트/저장소**를 선택합니다.

그룹 만들기:

1. 왼쪽 사이드바에서 맨 위에서 **새로 만들기** (**{plus}**)를 선택하고 **새 그룹**을 선택합니다.

관리자 영역 열기:

1. 왼쪽 사이드바에서 맨 아래에서 **관리자**를 선택합니다.
1. **설정 > CI/CD**를 선택합니다.

두 번째 단계에서는 왼쪽 사이드바를 반복할 필요가 없습니다.

작업내역 메뉴 항목 열기:

1. 왼쪽 사이드바에서 **검색 또는 이동**을 선택합니다.
1. **작업내역**을 선택합니다.

아바타 선택하기:

1. 왼쪽 사이드바에서 아바타를 선택합니다.

드롭다운 목록에서 선택 저장하기:

이슈로 이동합니다.
**오른쪽 사이드바**에서 **이터레이션** 섹션에서 **편집**을 선택합니다.
드롭다운 목록에서 이 문제를 연결할 이터레이션을 선택합니다.
드롭다운 목록 외부 영역을 선택합니다.

모든 프로젝트 보기:

1. 왼쪽 사이드바에서 **검색 또는 이동**을 선택합니다.
1. **내 프로젝트 모두 보기**를 선택합니다.

모든 그룹 보기:

1. 왼쪽 사이드바에서 **검색 또는 이동**을 선택합니다.
1. **내 그룹 모두 보기**를 선택합니다.

선택적인 단계

단계가 선택적인 경우, 해당 단계를 Optional 단어로 시작한 후 마침표를 붙입니다.

예:

1. 선택적. 작업에 설명을 입력합니다.

권장 단계

단계가 권장되는 경우, 해당 단계를 Recommended 단어로 시작한 후 마침표를 붙입니다.

예:

1. 권장됨. 작업에 설명을 입력합니다.

여러 필드 동시에 문서화

UI 텍스트가 섹션의 필드를 충분히 설명하는 경우, 각 필드에 대한 작업 단계를 모두 포함시키지 않습니다. 대신 필드를 작성 구문으로 여러 필드를 요약하십시오.

예:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
설정 > 저장소를 선택합니다.
푸시 규칙을 확장합니다.
필드를 작성합니다.

여러 필드를 문서화하고 하나의 필드만 설명이 필요한 경우 같은 단계에서 처리하십시오:

푸시 규칙을 확장합니다.
필드를 작성합니다. 브랜치 이름은 정규 표현식이어야 합니다.

여러 필드를 설명하기 위해 점 목록 항목을 사용하십시오:

일반 파이프라인을 확장합니다.
필드를 작성합니다.
- 브랜치 이름은 정규 표현식이어야 합니다.
- 사용자는 적어도 유지자 역할을 가진 사용자여야 합니다.

일러스트레이션

GitLab 문서는 두 가지 유형의 일러스트레이션을 사용합니다.

스크린샷은 GitLab 사용자 인터페이스의 일부를 보여주는 데 사용됩니다.
다이어그램은 프로세스나 엔티티 간의 관계를 설명하기 위해 사용됩니다.

일러스트레이션은 복잡한 프로세스나 어플리케이션과의 상호작용 방법을 이해하는 데 도움이 될 수 있습니다. 그러나:

이들은 빠르게 노포더아웃될 수 있습니다.
로컬화하는 데 어려울 수 있습니다.
스크린 리더에서 읽히지 않을 수 있습니다.

문서에서 일러스트레이션을 사용해야 하는 경우 다음 지침을 따라야 합니다:

텍스트를 보완하도록 하십시오. 일러스트레이션만으로 필요한 정보를 확보할 수 없도록 하십시오.
앞 문장에 설명이 있어야 합니다. 예를 들어, 다음 다이어그램은 제품 분석 흐름을 보여줍니다.
접근 가능해야 합니다. 자세한 내용은 스크린샷 및 다이어그램에 대한 가이드라인을 참조하십시오.
개인을 식별할 수 있는 정보는 제외되어야 합니다.

스크린샷

텍스트로 충분히 전달할 수 없는 경우에만 GitLab 사용자 인터페이스의 일부를 보여주기 위해 스크린샷을 사용하십시오.

스크린샷 캡처

스크린샷을 찍을 때:

가치를 제공해야 합니다. lorem ipsum 텍스트를 사용하지 마십시오. 실제 사용되는 호환 텍스트를 사용하고 가능한 실제 사용 시나리오를 복제하려고 하십시오.
관련 UI만을 캡처해야합니다. 불필요한 여백이나 포인트를 설명하지 않는 UI 영역을 포함하지 마십시오. GitLab의 사이드바는 변경될 수 있기 때문에 반드시 필요한 경우가 아니라면 스크린샷에 포함하지 마십시오.
크기를 작게 유지하십시오. 전체 화면을 보여줄 필요가 없는 경우에는 최대한 줄이십시오. 브라우저 창의 크기를 최소화하여 요소를 가깝게 유지하고 빈 공간을 줄이십시오. 스크린샷 크기를 최소화하십시오.
페이지에서 이미지 렌더링을 미리 미리보기하십시오. 로컬 피리뷰를 통해 이미지가 흐릿하지 않고 지나치게 크지 않은지 확인하십시오.
일관성을 유지해야 합니다. 일관된 검토 경험을 위해 문서 페이지에 이미지가 있는지 확인하기 전에 스크린샷을 조정하십시오. 내비게이션 테마 및 구문 강조 테마를 Indigo 및 Light로 설정하십시오. 이것이 기본 설정입니다.

강조 추가

스크린샷에서 특정 영역을 강조해야 하는 경우 화살표를 사용합니다.

색상은 #EE2604를 사용합니다. macOS의 Preview 애플리케이션을 사용하는 경우, 이것이 기본 빨강입니다.
선 두께는 3 pt를 사용합니다. macOS의 Preview 애플리케이션을 사용하는 경우, 이것이 목록의 세 번째 선입니다.
다음 이미지에 표시된 화살표 스타일을 사용합니다.
여러 개의 화살표가 있는 경우, 가능한 경우 병렬로 만듭니다.

이미지 요구 사항

넓거나 긴 스크린샷을 리사이즈합니다.
- 너비는 1000 픽셀 이하여야 합니다.
- 높이는 500 픽셀 이하여야 합니다.
- 리사이즈 및 압축 후에도 스크린샷이 여전히 선명한지 확인하세요.
모든 이미지는 100 KB 이하로 압축되어야만 합니다. 많은 경우, 이미지 품질을 낮추지 않고 25-50 KB 이하로 가능합니다.
이미지는 이미지의 기능이나 컨셉을 설명하는 소문자 파일 이름으로 저장해야 합니다:
- 이미지가 GitLab 인터페이스의 스크린샷인 경우, 파일 이름에 GitLab 버전을 추가합니다. 이 때의 형식은 image_name_vX_Y.png입니다. 예를 들어, GitLab 11.1의 파이프라인 페이지에서 캡처된 스크린샷의 유효한 이름은 pipelines_v11_1.png입니다.
- 사용자 인터페이스의 부분을 포함하지 않는 치명적 설명을 추가하는 경우, 해당 이미지가 추가된 릴리스 번호를 추가합니다. 11.1의 마일스톤에 추가된 MR의 경우, 유효한 일러스트레이션 이미지의 이름은 devops_diagram_v11_1.png입니다.
이미지는 작업 중인 .md 문서가 있는 디렉토리와 동일한 위치의 img/라는 별도의 디렉토리에 배치합니다.
JPEG 대신 PNG 이미지를 사용하는 것을 고려해보세요.
GIF를 ezgif.com/optimize 또는 유사한 툴로 압축합니다.

동영상을 나타내기 위해 동영상 링크하고 삽입하는 방법도 참고하세요.

이미지 압축

문서에 추가하는 모든 새 이미지를 항상 압축해야 합니다. 알려진 도구 중 하나는 cross-platform이고 오픈 소스인 pngquant입니다. 공식 웹사이트를 방문하여 OS에 따른 지침을 따라 설치하세요.

macOS를 사용하고 모든 스크린샷을 자동으로 압축하려면 스크린샷을 80% 더 작게 만드는 간단한 꿀팁을 참조하세요.

GitLab에는 수동 프로세스를 단순화하기 위해 사용할 수 있는 Ruby script가 있습니다. 로컬 복사본의 루트 디렉터리에서 터미널을 통해 다음을 실행하세요.

압축하기 전에 원한다면 모든 문서 PNG 이미지가 압축되었는지 확인하세요:
```
bin/pngquant lint
```
pngquant를 사용하여 모든 문서 PNG 이미지를 압축합니다:
```
bin/pngquant compress
```

특정 파일을 압축합니다:

bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png

특정 디렉터리의 모든 PNG 파일을 압축합니다:
```
bin/pngquant compress doc/user/img
```

동적 이미지

동적 이미지(예: GIF)를 사용하는 것을 피하세요. 이는 사용자에게 혼란을 줄 수 있습니다.

사용자 인터페이스의 복잡한 상호 작용을 설명하고 독자가 이해하는 데 도움을 주기 위해 시각적 표현을 포함하려면 다음을 할 수 있습니다:

정적 이미지(스크린샷)를 사용하고 필요한 경우 화살표를 추가하여 화면의 특정 영역을 강조합니다.
짧은 인터랙션 비디오를 만들고 링크합니다.

컨텐츠에 이미지 링크 추가

문서에 이미지를 포함하는 Markdown 코드는: ![alt 태그로 사용되는 이미지 설명](img/document_image_title_vX_Y.png)

대체 텍스트

대체 텍스트는 접근성 있는 경험을 제공합니다. 스크린 리더는 이미지를 설명하기 위해 대체 텍스트를 사용하고, 이미지를 다운로드하지 못할 경우 대체 텍스트가 표시됩니다.

대체 텍스트는 이미지의 컨텍스트를 설명합니다. 이미지의 콘텐츠가 아닌 이미지에 관련된 컨텍스트를 추가합니다. 만약 누군가가 이미지를 보거나 상호 작용하는 데 도움을 받아야 하는 경우 이미지에 대해 무엇을 말할지를 고려하세요.

다음과 같이 하세요:

![러너가 Docker API에 요청을 보내는 모습](img/document_image_title_vX_Y.png)

다음과 같이 하지 마세요:

![러너와 Docker 아키텍처](img/document_image_title_vX_Y.png)

대체 텍스트를 작성할 때:

155자 이하로 짧고 설명적인 대체 텍스트를 작성하세요. 대부분의 스크린 리더는 이만큼의 문자를 읽은 후에 멈춥니다.
이미지에 워크플로 다이어그램과 같은 복잡한 정보가 있다면 간결한 대체 텍스트로 이미지를 식별하고 텍스트에 상세 정보를 포함하세요.
문장 부호를 사용하세요.
텍스트가 전체 문장이 아닌 경우 마침표를 사용하지 마세요.
모든 전체 문장 뒤에 마침표를 사용하세요.
문장 케이스를 사용하고 모두 대문자를 사용하지 마세요. 일부 스크린 리더는 대문자를 개별 문자로 읽습니다.
이미지나 그래픽과 같은 구절을 사용하지 마세요.
키워드를 나열하는 것을 피하세요. 텍스트에 컨텍스트를 더하기 위해 키워드를 포함하세요.
이미지를 선보이는 것이 아니라 이미지의 주제를 소개하세요.
이미 사용한 텍스트를 반복하는 것을 피하세요.
볼드체, 이탤릭체, 역따옴표와 같은 인라인 스타일을 사용하지 마세요. 스크린 리더는 **텍스트**를 별표 별표 텍스트 별표 별표로 읽습니다.

자동 스크린샷 생성기

자동 스크린샷 생성기를 사용하여 스크린샷을 찍고 압축할 수 있습니다.

GitLab Development Kit (GDK)를 설정하세요.
복제한 GitLab 저장소의 하위 디렉토리, 일반적으로 gdk/gitlab으로 이동하세요.
GDK 데이터베이스가 완전히 마이그레이션되었는지 확인하세요: bin/rake db:migrate RAILS_ENV=development.
pngquant를 설치하고 더 많은 정보를 원하면 도구 웹사이트를 참조하세요: pngquat
scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>을 실행하세요.
it 매개변수로 정의된 gitlab/doc 위치에 따라 스크린샷의 위치를 식별하세요.
새롭게 생성된 스크린샷을 커밋하세요.

도구 확장

추가 스크린샷 생성기를 추가하려면:

spec/docs_screenshots 디렉토리에 _docs.rb 확장자의 새 파일을 추가하십시오.

파일에 다음 정보를 추가하십시오:

require 'spec_helper'

RSpec.describe '<스크린샷을 찍는 대상>', :js do
  include DocsScreenshotHelpers # 스크린샷 촬영 메커니즘을 활성화하는 도우미

  before do
    page.driver.browser.manage.window.resize_to(1366, 1024) # 페이지의 길이와 너비
  end

각 it 블록에 스크린샷이 저장된 경로를 추가하십시오:
```
it '<이미지/디렉토리/경로>'
```

visit <경로>를 사용하여 페이지의 스크린샷을 찍을 수 있습니다. 콘텐츠가 로드될 때까지 기다리려면 expect를 사용하여 빈 스크린샷을 피하십시오.

단일 요소 스크린샷

단일 요소의 스크린샷을 찍을 수 있습니다.

스크린샷 생성기 파일에 다음을 추가하십시오:

screenshot_area = find('<요소>') # 요소 찾기
scroll_to screenshot_area # 요소로 스크롤
expect(screenshot_area).to have_content '<콘텐츠>' # 캡처할 콘텐츠가 로드될 때까지 기다립니다.
set_crop_data(screenshot_area, <패딩>) # 패딩을 추가하여 요소 캡처

spec/docs_screenshots/container_registry_docs.rb를 사용하여 자체 스크립트를 만드는 데 참고하십시오.

다이어그램

텍스트 만으로 이해하기에 너무 복잡한 경우 프로세스나 엔티티 간의 관계를 보여주기 위해 다이어그램을 사용하십시오.

다이어그램을 만들려면 Mermaid를 사용하십시오. Mermaid의 다음 장점이 있습니다:

Mermaid 포맷은 다음과 같은 이유로 유지 관리가 쉽습니다:
- 다이어그램 정의가 문서의 Markdown 소스에 코드 블록으로 저장됩니다.
- 다이어그램이 실행시 동적으로 렌더링됩니다.
- 다이어그램의 텍스트 콘텐츠(예: 기능 이름)는 텍스트 검색 도구로 찾을 수 있고 편집할 수 있습니다.
다이어그램은 크기 조절 가능한 이미지로 렌더링되어 다양한 출력 장치와 크기에 더 적합합니다.

Mermaid 구문으로 다이어그램을 만드는 방법을 알아보려면, Mermaid Mermaid 사용자 가이드와 Mermaid 사이트의 예제를 참고하십시오.

지침

접근성이 좋고 유지 관리가 쉬운 다이어그램을 만들려면 다음 지침을 따르십시오:

다이어그램을 간단하고 중심으로 유지하십시오. 필수 요소와 정보만 포함하십시오.
다른데서 일관된 비주얼 신호(예: 모양, 색상, 글꼴)를 사용하여 구분하십시오:
- 프로세스나 단계에 대한 직사각형.
- 결정 지점에 대한 다이아몬드.
- 요소 간의 직접 관계에 대한 실선.
- 요소 간의 간접 관계에 대한 점선.
- 프로세스의 흐름이나 방향에 대한 화살표.
- GitLab Sans 글꼴.
다이어그램 요소에 명확한 레이블과 간단한 설명을 추가하십시오.
다이어그램에 제목과 간단한 설명을 포함하십시오.
복잡한 프로세스의 경우 하나의 큰 다이어그램 대신 여러 간단한 다이어그램을 만드는 것을 고려하십시오.
다양한 장치와 화면 크기에서 볼 때 다이어그램이 잘 작동하는지 확인하십시오.
프로세스가 변경되면 문서나 코드와 함께 다이어그램을 업데이트하여 정확도를 유지하십시오.

다이어그램 만들기

GitLab 문서를 위해 다이어그램을 만들려면:

Mermaid Live Editor에서 다이어그램을 만듭니다.
Code 패인의 내용을 복사하여 Markdown 파일에 붙여넣고 mermaid 코드 블록으로 감싸십시오. 자세한 내용은 GitLab Flavored Markdown for Mermaid을 참조하십시오.
다이어그램 유형을 선언하는 mermaid 코드 블록 선언과 사이에 다음 줄을 추가하여 GitLab 글꼴 스타일을 추가하십시오:
```
%%{init: { "fontFamily": "GitLab Sans" }}%%
```
(대체 텍스트) 그림 제목 뒤에 다음 줄에 접근성을 위해 다음 라인을 추가하십시오:
```
accTitle: 여기에 다이어그램 제목
accDescr: 한 문장으로 다이어그램의 기능을 설명합니다. 줄 바꿈 없이 작성하십시오.
```
제목과 설명이 대체 텍스트 지침을 따르는지 확인하십시오.

예를 들어, 이 플로우차트에는 접근성과 글꼴 정보가 모두 포함되어 있습니다:

```mermaid
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
    accTitle: 예제 다이어그램 제목
    accDescr: 다이어그램 설명

    A[여기에서 시작] -->|액션| B[다음 단계]
```
``` 


## 동영상

GitLab YouTube 비디오 자습서를 문서에 추가하는 것을 적극 권장합니다.
비디오가 오래되었을 때만 제외하고 말이죠. 비디오는 문서를 대체해서는 안 되며, 보충하거나 설명하는 데 사용해야 합니다. 비디오의 내용이 기능과 주요 사용 사례에 필수적이지만 문서에서 충분히 다루지 않는 경우 다음을 수행해야 합니다.

- 이 세부사항을 문서 텍스트에 추가합니다.
- 비디오 검토 및 페이지 업데이트를 위한 문제를 만듭니다.

제품 저장소에 비디오를 업로드하지 마십시오. [링크](#link-to-video) 또는
대신에 임베드](#embed-videos)하십시오.

### 비디오 링크

비디오에 링크하려면 독자가 동영상을 보기 전에 페이지를 스캔할 수 있도록 YouTube 아이콘을 포함합니다. 동영상의 게시 날짜를 링크 뒤에 표시하여 오래 된 동영상을 식별하는 데 도움이 되도록 합니다.

```markdown
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
개요는 [동영상 제목](https://link-to-video)을(를) 참조하십시오.
<!-- 동영상은 YYYY-MM-DD에 공개되었습니다 -->
```

GitLab 사용자에게 유용한 최신 비디오에 링크할 수 있습니다.

### 동영상 임베드

[GitLab 설명서 사이트](https://docs.gitlab.com)에서는 임베드된 동영상을 지원합니다.

[GitLab의 공식 YouTube 계정](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)의 비디오만 임베드할 수 있습니다.
다른 소스의 비디오는 [링크](#link-to-video)해야 합니다.

대부분의 경우 임베드된 동영상은 페이지의 공간을 많이 차지하고 독자들에게 방해가 될 수 있기 때문에 [비디오 링크](#link-to-video)를하는 것이 좋습니다.

동영상을 임베딩하려면:

1. 이 절차에서 코드를 복사하여 Markdown 파일에 붙여 넣으십시오. 위와 아래에 빈 줄을 남겨 두십시오. 코드를 수정하지 마십시오(공백을 제거하거나 추가하지 마십시오).
1. YouTube에서 표시하려는 비디오 URL을 방문하십시오. 브라우저에서 정규 URL(`https://www.youtube.com/watch?v=VIDEO-ID`)을 복사하고, 빈칸의 `<div class="video-fallback">` 아래에 비디오 제목과 링크를 대체하십시오.
1. YouTube에서 **공유**을 선택한 다음 **임베드**를 선택하십시오.
1. `<iframe>` 소스(`src`) **URL만** (`https://www.youtube-nocookie.com/embed/VIDEO-ID`)을 복사하여 `iframe` 태그의 `src` 필드의 내용을 대체하십시오.
1. 오래된 동영상을 식별하는 데 도움이 되도록 링크 아래에 동영상을 게시한 날짜를 포함하십시오.

```html
여기에 빈 줄을 남겨 두십시오
<div class="video-fallback">
  동영상 보기: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">동영상 제목</a>.
</div>
<figure class="video-container">
  <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>
<!-- 동영상은 YYYY-MM-DD에 공개되었습니다 -->
여기에 빈 줄을 남겨 두십시오
```

GitLab 설명서 사이트에서는 이를 보겠습니까.

<div class="video-fallback">
  동영상 보기: <a href="https://www.youtube.com/watch?v=enMumwvLAug">GitLab은 무엇인가요</a>.
</div>
<figure class="video-container">
  <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>

이 형식으로:

- `figure` 태그는 의미론적 SEO를 위해 필요하며, `video-container` 클래스는 비디오가 반응하고 다양한 모바일 장치에 표시되도록 하기 위해 필요합니다.
- `<div class="video-fallback">`는 GitLab Markdown 프로세서에서 iframe을 지원하지 않기 때문에 `/help`에는 필수적이지만 문서 사이트에는 표시되지 않습니다.
- `www.youtube-nocookie.com` 도메인은 YouTube의 임베드된 플레이어의 [개인 정보 고강화 모드](https://support.google.com/youtube/answer/171780?hl=ko#zippy=%2Cturn-on-privacy-enhanced-mode)를 활성화합니다. 이 모드를 사용하면 제한된 쿠키 기본 설정을 가진 사용자도 임베드된 비디오를 볼 수 있습니다.

## 클릭 스루 데모에 대한 링크

클릭 스루 데모에 링크하는 것은 [비디오](#videos)와 유사한 지침을 따라야 합니다.

```markdown
클릭 스루 데모를 보려면 [데모 제목](https://link-to-demo)을(를) 참조하십시오.
<!-- 데모는 YYYY-MM-DD에 발행되었습니다 -->
```

## 알림 상자

정보를 강조하기 위해 알림 상자를 사용하십시오. 이를 절약해서 사용하고, 다른 알림 상자 바로 뒤에 바로오지 않도록 하십시오.

알림 상자는 이러한 단어 뒤에 줄 바꿈이 이어질 때 생성됩니다.

- `FLAG:`
- `NOTE:`
- `WARNING:`
- `DISCLAIMER:`
- `DETAILS:`

예를 들어:

```markdown
NOTE:
이것은 유의할 사항입니다.
```

여러 단락, 목록 또는 제목에 대한 알림 상자를 표시하려면 [블록 인용](#blockquotes)을 대신 사용하십시오.

알림 상자는 GitLab 문서 사이트(<https://docs.gitlab.com>)에서만 렌더링됩니다.
GitLab 제품 도움말에서 알림 상자는 일반 텍스트로 나타납니다.

### Flag

기능의 이용 가능성을 설명하는 데 이 알림 유형을 사용하십시오. `FLAG` 알림을 어떻게 서식하는지에 대한 정보는 [기능 플래그 뒤에 배포된 기능 문서](../feature_flags.md)를 참고하십시오.

### Note

노트를 절약해서 사용하십시오. 많은 노트는 주제를 스캔하기 어렵게 할 수 있습니다.

노트를 추가하는 대신:

- 문장을 단락의 일부로 다시 작성하십시오.
- 정보를 별도의 단락으로 넣으십시오.
- 콘텐츠를 새로운 주제 제목 아래에 넣으십시오.

노트를 사용해야 하는 경우 다음 형식을 사용하십시오.

```markdown
NOTE:
이것은 유의할 사항입니다.
```

GitLab 설명서 사이트에는 다음과 같이 렌더링됩니다.

NOTE:
이것은 유의할 사항입니다.

### Warning

폐기된 기능을 나타내거나 데이터 손실 가능성에 대한 경고를 제공하려면 경고를 사용하십시오.

```markdown
WARNING:
이것은 경고할 사항입니다.
```

GitLab 설명서 사이트에는 다음과 같이 렌더링됩니다.

WARNING:
이것은 경고할 사항입니다.

### Disclaimer

아직 제공하지 않은 기능에 대해 작성해야 하는 경우 해당 내용과 함께 다음 명시적인 부인 사항을 입력하십시오.

```markdown
DISCLAIMER:
이 페이지에는 예정 된 제품, 기능 및 기능과 관련된 정보가 포함되어 있습니다.
표시된 정보는 정보 목적으로만 제공되었음을 유의하십시오.
이 정보를 구매 또는 계획 목적으로 의존하지 마십시오.
모든 제품, 기능 또는 기능의 개발, 출시 및 시기는 변경 또는 지연될 수 있으며
GitLab Inc의 단독 재량에 달려 있습니다.
```

GitLab 설명서 사이트에는 다음과 같이 렌더링됩니다.

DISCLAIMER:
이 페이지에는 예정 된 제품, 기능 및 기능와 관련된 정보가 포함되어 있습니다.
표시된 정보는 정보 목적으로만 제공되었음을 유의하십시오.
이 정보를 구매 또는 계획 목적으로 의존하지 마십시오.
모든 제품, 기능 또는 기능의 개발, 출시 및 시기는 변경 또는 지연될 수 있으며
GitLab Inc의 단독 재량에 달려 있습니다.

페이지의 모든 내용을 사용할 수 없는 경우 페이지 상단에 앞으로의 전망에 대한 부인 사항을 한 번 사용하십시오.

토픽의 내용이 준비되지 않은 경우 해당 토픽에 부인 사항을 사용하십시오.

자세한 내용은 [미래 버전의 유망한 기능](#promising-features-in-future-versions)을 참조하십시오.

### 세부 정보

`DETAILS:` 알림 상자는 [제품 가용성 세부 정보](#product-availability-details)를 위해 사용됩니다.

## 인용구

텍스트를 강조하기 위해 블록 인용구 내에서 이 형식을 사용하세요:

```markdown
> This is a blockquote.
```

GitLab 문서 사이트에 다음과 같이 렌더링됩니다:

> This is a blockquote.

텍스트가 여러 줄에 걸친 경우, 그것들을 나눌 수 있습니다.

여러 단락의 경우, 각 줄 앞에 기호 `>`를 사용하세요:

```markdown
> This is the first paragraph.
>
> This is the second paragraph.
>
> - This is a list item
> - Second item in the list
```

GitLab 문서 사이트에 다음과 같이 렌더링됩니다:

> This is the first paragraph.
>
> This is the second paragraph.
>
> - This is a list item
> - Second item in the list

## 탭

문서 사이트에서 텍스트를 탭으로 표시할 수 있습니다.

탭 세트를 만들려면 다음 예시를 따르세요:

```plaintext
::Tabs

:::TabTitle 탭 1

탭 1에 포함된 내용입니다.

:::TabTitle 탭 2

탭 2에 포함된 다른 내용입니다.

::EndTabs
```

이 코드는 GitLab 문서 사이트에서 다음과 같이 렌더링됩니다:

::Tabs

:::TabTitle 탭 1

탭 1에 포함된 내용입니다.

:::TabTitle 탭 2

탭 2에 포함된 다른 내용입니다.

::EndTabs

탭 제목은 간단하고 일관적이어야 합니다. 이들이 평행하고 각각의 첫 글자가 대문자로 시작되도록 해야 합니다.
예를 들어:

- `Linux package (Omnibus)`, `Helm chart (Kubernetes)`(구성 편집 방법에 대한 문서화 시, [구성 편집 가이드](#how-to-document-different-installation-methods)를 따르세요)
- `버전 15.1 이전`, `버전 15.2 이후`

탭에 대한 링크를 직접적으로 연결하지 말고 각각 독특한 URL 매개변수를 가지고 있더라도 ([Issue 1355](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1355) 참조) 탭에 대한 링크를 걸지 마세요.

더 자세한 내용은 [Pajamas](https://design.gitlab.com/components/tabs/#guidelines)를 참조하세요.

## 표절

다른 소스에서 내용을 복사하여 붙이지 마세요. 원천이 인용된 경우에는 한정된 인용 구문으로 복사해야 합니다. 관련 정보를 여러분의 말로 나타내거나 다른 원천으로 링크하는 것이 더 나은 방법입니다.

## 미래 버전의 유망한 기능

미래 릴리즈에서 기능을 제공할 것이라고 약속하지 마세요. 예를 들어, "이 기능을 지원하는 것이 계획되어 있습니다."와 같은 구문을 피하세요.

우리는 미래의 기능 작업을 보장할 수 없으며, 이러한 약속은 법적 문제를 유발할 수 있습니다. 대신, 문제가 존재한다고 말하세요.
예를 들어:

- 개선사항에 대한 지원은 `[issue <issue_number>](https://link-to-issue)`에서 제안됩니다.
- 여러분은 이 일을 할 수 없지만, `[issue 12345](https://link-to-issue)`에서 이 동작을 변경하도록 제안됩니다.

기능을 제거할 계획이라고 할 수 있습니다.

미래의 기능을 문서화해야 하는 경우 [배려사항](#disclaimer)을 사용하세요.

## 제품 및 기능

GitLab 제품 문서에서 제품 및 기능을 설명할 때는 이 섹션의 정보를 참조하세요.

### 이름에 줄 바꿈 삽입하지 않기

기능 또는 제품 이름에 공백이 포함된 경우 이름을 줄 바꿈하지 마세요. 이름이 변경되면 줄 바꿈이 있는 텍스트를 검색하거나 grep 하는 것이 더 복잡해집니다.

### 제품 가용성 세부 정보

제품 가용성 세부 정보는 기능에 대한 정보를 제공하며 주제 제목 아래에 표시됩니다.

더 자세한 내용은 [제품 가용성 세부 정보](availability_details.md)를 읽어보세요.

## 특정 섹션

특정 센션이 적용되어야 하는 스타일을 알아보세요. 특정 섹션에 대한 스타일은 이 섹션에서 개요가 제공됩니다.

### 도움 및 피드백 섹션

이 섹션은 각 문서의 끝에 표시되며 front matter에 있는 필드를 추가함으로써 생략할 수 있습니다:

```yaml
---
feedback: false
---
```

기본값으로 이것을 그대로 둘 것입니다. 문서에서 이것을 생략하려면 반드시 기술 작성자와 상의해야 합니다.

피드백 섹션의 클릭 이벤트는 Google Tag Manager로 추적됩니다. 변환은 Google Analytics에서 **행동 > 이벤트 > 상위 이벤트 > docs**로 이동하여 볼 수 있습니다.

### GitLab 재시작

GitLab의 재시작이나 재구성이 필요한 경우, 'reconfigure'를 필요에 따라 'restart'로 대체하여 다음과 같이 [`doc/administration/restart_gitlab.md`](../../../administration/restart_gitlab.md)에 링크 추가를 피하세요:

```markdown
파일을 저장하고 [GitLab을 다시 구성하세요](../../../administration/restart_gitlab.md) 변경 사항이 적용되도록 합니다.
```

만약 문서가 `doc/` 디렉토리 외부에 있다면 상대 링크 대신 전체 경로를 사용하세요:
`https://docs.gitlab.com/ee/administration/restart_gitlab.html`.

### 다양한 설치 방법 문서화하기

GitLab은 다섯 가지의 공식적인 설치 방법을 지원합니다. 텍스트로 참조할 때 다음 구문을 사용하세요:

- 리눅스 패키지
- Helm 차트
- GitLab Operator
- Docker
- 자체 컴파일

탭을 [사용할 때](#use-tabs-to-describe-a-self-managed-configuration-procedure) 괄호로 설명을 추가하는 것이 괜찮습니다:

- 리눅스 패키지 (Omnibus)
- Helm 차트 (Kubernetes)
- GitLab Operator (Kubernetes)
- Docker
- 자체 컴파일 (원본)

### 자체 컴파일 구성 절차를 설명하기 위해 탭 사용

구성 절차는 사용자로 하여금 구성 파일을 편집하거나 GitLab을 재구성하거나 재시작하도록 요구할 수 있습니다. 이 경우:

- [탭](#tabs)을 사용하여 여러 설치 방법을 구별하세요.
- 이전 목록에서 정확히 설명된 설치 방법 이름을 사용하세요.
- 아래 설명된 순서대로 사용하세요.
- 코드 블록을 해당 목록 항목에 일치시키도록 들여쓰세요.
- 각 코드 블록에 적합한 구문 강조 기능을 사용하세요(`ruby`, `shell`, 또는 `yaml`).
- YAML 파일의 경우 항상 상위 설정을 포함시키세요.
- GitLab을 다시 구성하거나 다시 시작하는 마지막 단계는 동일하므로 정확하게 그대로 사용할 수 있습니다.

구성 편집을 설명할 때 다음 스니펫을 사용하거나 원하는 대로 편집할 수 있습니다:

<!-- markdownlint-disable tabs-blank-lines -->
````markdown
::Tabs

:::TabTitle 리눅스 패키지 (Omnibus)

1. `/etc/gitlab/gitlab.rb`을 편집하세요:

   ```ruby
   external_url "https://gitlab.example.com"
   ```

1. 파일을 저장하고 GitLab을 다시 구성하세요:

   ```shell
   sudo gitlab-ctl reconfigure
   ```

:::TabTitle Helm 차트 (Kubernetes)

1. Helm 값들을 내보내세요:

   ```shell
   helm get values gitlab > gitlab_values.yaml
   ```

1. `gitlab_values.yaml`을 편집하세요:

   ```yaml
   global:
     hosts:
       gitlab:
         name: gitlab.example.com
   ```

1. 파일을 저장하고 새로운 값들을 적용하세요:

   ```shell
   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   ```

:::TabTitle Docker

1. `docker-compose.yml`을 편집하세요:

   ```yaml
   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           external_url "https://gitlab.example.com"
   ```

1. 파일을 저장하고 GitLab을 재시작하세요:

   ```shell
   docker compose up -d
   ```

:::TabTitle 자체 컴파일 (원본)

1. `/home/git/gitlab/config/gitlab.yml`을 편집하세요:

   ```yaml
   production: &base
     gitlab:
       host: "gitlab.example.com"
   ```

1. 파일을 저장하고 GitLab을 재시작하세요:

   ```shell
   # systemd를 실행하는 시스템의 경우
   sudo systemctl restart gitlab.target

   # SysV init를 실행하는 시스템의 경우
   sudo service gitlab restart
   ```

::EndTabs

위의 코드는 다음과 같이 렌더링됩니다:

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb을 편집하세요:

external_url "https://gitlab.example.com"

파일을 저장하고 GitLab을 다시 구성하세요:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

Helm 값들을 내보내세요:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집하세요:

global:
  hosts:
    gitlab:
      name: gitlab.example.com

파일을 저장하고 새로운 값들을 적용하세요:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집하세요:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url "https://gitlab.example.com"

파일을 저장하고 GitLab을 재시작하세요:
```
docker compose up -d
```

자체 컴파일 (원본)

/home/git/gitlab/config/gitlab.yml을 편집하세요:

production: &base
  gitlab:
    host: "gitlab.example.com"

파일을 저장하고 GitLab을 재시작하세요:

# systemd를 실행하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init를 실행하는 시스템의 경우
sudo service gitlab restart

GitLab 문서 스타일 가이드

GitLab 음성

문서는 단일 정보 원천(SSoT)입니다

주제 유형

문서 우선 방법론

지역화 작성

Markdown

Markdown에서의 HTML

Markdown에서의 제목 레벨

언어

능동태

고객 관점

신뢰 구축

대문자

주제 제목

UI 텍스트

기능 이름

다른 용어들

가짜 사용자 정보

가짜 URL

가짜 토큰

줄임말

소유격

전치사

약어

숫자

텍스트

줄 길이

코멘트

구두점

자리 표시자 텍스트

따옴표

텍스트 형식

볼드

인라인 코드

코드 블록

키보드 명령

이탤릭체와 강조

목록

정렬 목록 또는 비정렬 목록 선택

목록 마크업

목록 항목 내의 중첩

테이블

생성 가이드라인

테이블 형식 지정을 위한 에디터 확장 기능

기존 테이블 업데이트

테이블 머리글

기능 테이블

각주

각주 형식

다섯 개 이상의 각주

링크

동일 저장소 내의 링크

서로 다른 저장소에 있는 링크

앵커 링크

링크와 제목 변경

링크 텍스트

표준 텍스트

here보다 서술적인 텍스트 사용

이슈에 대한 링크

외부 문서에 대한 링크

기밀 또는 제한된 액세스 링크

코드의 특정 라인에 대한 링크

내비게이션

메뉴 이름

UI 요소의 이름

탐색 작업 단계 작성 방법

선택적인 단계

권장 단계

여러 필드 동시에 문서화

일러스트레이션

스크린샷

스크린샷 캡처

강조 추가

이미지 요구 사항

이미지 압축

동적 이미지

컨텐츠에 이미지 링크 추가

대체 텍스트

자동 스크린샷 생성기

`here`보다 서술적인 텍스트 사용