GitLab 음성
문서는 진실의 단일 출처(SSoT)
주제 유형
Docs-first 방법론
현지화를 위한 글쓰기
마크다운
- 마크다운의 HTML
- 마크다운의 제목 수준
언어
- 능동태
- 고객 관점
- 신뢰 구축
- 대문자 표기
- 가짜 사용자 정보
- 가짜 URL
- 가짜 토큰
- 축약형
- 소유격
- 전치사
- 약어
- 숫자
텍스트
- 줄 길이
- 주석
- 구두점
- 자리 표시자 텍스트
- 인용 부호
텍스트 형식 지정
- 굵게
- 인라인 코드
- 코드 블록
- 키보드 명령
- 기울임체 및 강조
목록
- 정렬 목록 또는 비정렬 목록 선택
- 목록 마크업
- 목록 항목 안에 중첩하기
테이블
- 생성 지침
- 테이블 형식을 위한 편집기 확장
- 기존 테이블 업데이트
- 테이블 헤더
- 기능 테이블
- 각주
  - 각주 형식
    - 다섯 개 이상의 각주
링크
- 같은 저장소의 링크
- 별도의 저장소의 링크
- 앵커 링크
  - 링크 및 제목 변경
- 링크 텍스트
- 외부 문서 링크
- 기밀 또는 제한 액세스 링크
- 특정 코드 줄 링크
탐색
- 메뉴 이름
- UI 요소 이름
- 탐색 작업 단계 작성 방법
- 선택적 단계
- 권장 단계
- 여러 필드를 동시에 문서화하기
삽화
- 스크린샷
- 다이어그램
  - 가이드라인
  - 다이어그램 만들기
이모지
GitLab SVG 아이콘
비디오
- 비디오 링크
- 비디오 임베드
클릭-투-데모 링크
경고 박스
- 플래그
- 노트
- 경고
- 면책 조항
- 세부 정보
인용문
탭
표절
향후 버전의 유망한 기능
제품 및 기능
- 이름에 줄 바꿈 피하기
- 제품 가용성 세부정보
특정 섹션
- 도움말 및 피드백 섹션
- GitLab 재시작
- 다양한 설치 방법 문서화 방법
- 셀프 관리 구성 절차를 설명하기 위해 탭 사용하기

문서 스타일 가이드

이 문서는 GitLab 문서의 표준을 정의하며, 문법, 형식 및 기타 사항을 포함합니다.

특정 단어에 대한 가이드라인은 단어 목록을 참조하세요.

GitLab 음성

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

그 지침을 바탕으로, GitLab 문서의 음성은 간결하고,
직접적이며, 정확성을 추구합니다. 목표는 쉽게 검색하고 스캔할 수 있는 정보를 제공하는 것입니다.

문서의 음성은 대화체지만 간결하고, 친근하지만 요점을 잘 전달해야 합니다.

문서는 진실의 단일 출처(SSoT)

GitLab 문서는 구현, 사용 및 문제 해결과 관련된 모든 제품 정보를 위한 SSoT입니다.

문서는 지속적으로 발전합니다. 새로운 제품과 기능에 따라
업데이트되며, 명확성, 정확성 및 완전성을 위한 개선이 포함됩니다.

이 정책은 정보 저장소를 방지하여, GitLab 제품에 대한 정보를 더 쉽게 찾을 수 있도록 합니다.

또한 문서에 포함된 콘텐츠 유형에 대한 결정을 알립니다.

주제 유형

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

주제 유형은 사용자가 정보를 더 빨리 소화할 수 있도록 돕습니다. 이들은 다음과 같은 문제를 해결하는 데 도움이 됩니다:

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

Docs-first 방법론

제품 문서는 완전하고 신뢰할 수 있는 자원이 되어야 합니다.

질문에 대한 답이 문서에 존재한다면,
정보를 재구성하는 대신 문서의 링크를 공유하세요.
GitLab 문서에서 사용 가능한 정보가 없는 경우,
해당 정보를 문서에 추가하기 위해 병합 요청(MR)을 작성하세요. 그런 다음 정보를 전달하기 위해 MR을 공유하세요.

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

현지화를 위한 글쓰기

GitLab 문서는 현지화되어 있지 않지만, 글로벌 청중을 위해 글을 쓸 수 있도록 돕는 가이드라인을 따릅니다.

GitLab 음성은 우리가 번역을 염두에 두고 명확하고 직접적으로 글을 쓰도록 요구합니다.

우리의 스타일 가이드, 단어 목록, 그리고 Vale 규칙은 문서의 일관성을 보장합니다.

문서가 다른 언어로 번역될 때, 각 단어의 의미는 명확해야 합니다.
기계 번역, GitLab Duo Chat 및 기타 AI 도구의 사용 증가는 일관성이 더욱 중요하다라는 것을 의미합니다.

다음 규칙은 문서가 더 효율적으로 번역될 수 있도록 도와줄 수 있습니다.

피해야 할 것:

there is 및 there are와 같은 주제를 숨기는 구문.
it과 같은 애매한 대명사.
-ing로 끝나는 단어.
서로 혼동될 수 있는 since 및 because와 같은 단어.
e.g. 및 i.e.와 같은 라틴어 약어.
두 마리 토끼를 한 번에 죽인다와 같은 문화 특유의 참조.

사용할 것:

링크를 위한 표준 텍스트.
복잡한 문장과 단락 대신 목록 및 표.
AI 및
CI/CD와 같은 일반 약어 및 이전에 풀어 쓴 약어.

또한 다음 지침을 염두에 두세요:

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

마크다운

모든 GitLab 문서는 마크다운으로 작성됩니다.

문서 웹사이트는 GitLab Kramdown을 사용하여, 마크다운에서 HTML로 페이지를 렌더링하는 “플레이버드” Kramdown 엔진입니다. Kramdown 기능의 사용은 우리의 린터에 의해 제한되므로, 일반 마크다운을 사용하고 링크된 스타일 가이드의 규칙을 따르세요. Kramdown 전용 마크업은 사용할 수 없습니다 (예: {:.class}).

완전한 Kramdown 참조는 GitLab Markdown 가이드를 참조하세요.

마크다운 형식은 markdownlint와 Vale를 사용하여 테스트됩니다.

마크다운의 HTML

하드코딩된 HTML은 유효하지만 사용이 권장되지 않습니다. HTML은 다음과 같은 경우에 허용됩니다:

마크다운에 동등한 마크업이 없는 경우.
고급 테이블이 필요한 경우.
특별한 스타일링이 필요한 경우.
기술 작가의 검토 및 승인을 받은 경우.

마크다운의 제목 수준

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

각 하위 섹션에 대해 제목 수준을 증가시킵니다. 다시 말해, 주제 제목 앞의 # 문자 수를 증가시키세요.
H5(#####)보다 큰 제목 수준은 피하세요. 다섯 개 이상의 제목 수준이 필요한 경우, 주제를 새 페이지로 이동하세요. H5보다 큰 제목 수준은 오른쪽 사이드바 탐색에 표시되지 않습니다.
제목 수준을 건너뛰지 마세요. 예: ## > ####.
주제 제목 앞과 뒤에 빈 줄을 하나 남겨두세요.
주제 제목에 코드를 사용할 경우, 코드는 백틱( )으로 감싸야 합니다.
주제 제목에서 굵은 텍스트를 사용하지 마세요.

언어

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

불필요한 단어는 피하세요.
명확하고 간결하게 작성하며 주제의 목표에 집중하세요.
미국 영어 및 미국 문법으로 작성하세요. (테스트됨 British.yml.)

능동태

대부분의 경우, 능동태를 사용하면 텍스트가 이해하기 쉽고 번역하기도 용이합니다.

예를 들어, 다음과 같이 사용하세요:

개발자는 애플리케이션을 위한 코드를 작성합니다.

대신에:

애플리케이션 코드가 개발자에 의해 작성됩니다.

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

고객 관점

GitLab이 고객에게 가져다주는 기능과 이점에 집중하세요, GitLab이 무엇을 만들었는지에 대해서는 피하세요.

예를 들어, 다음과 같이 사용하세요:

소스 및 대상 브랜치에서 코드를 비교하기 위해 병합 요청을 사용하세요.

대신에:

GitLab은 코드를 비교할 수 있게 해줍니다.
GitLab은 코드를 비교할 수 있는 기능을 만들었습니다.
병합 요청은 코드를 비교할 수 있게 해줍니다.

고객 관점에서 작성하고 있지 않음을 나타내는 단어는 allow 및 enable입니다. 대신 you를 사용하여 사용자에게 직접 이야기하세요.

신뢰 구축

제품 문서는 판매 또는 마케팅 텍스트를 추가하지 않고 명확하고 간결한 정보를 제공하는 데 초점을 두어야 합니다.

easily 또는 simply와 같은 단어를 사용하지 마십시오.
“이 기능은 시간과 비용을 절약해 줄 것입니다.”와 같은 마케팅 문구를 사용하지 마십시오.

대신, 사실과 달성 가능한 목표에 초점을 맞추세요. 구체적으로 작성하세요. 예를 들어:

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

대문자 표기

회사를 대표하여 소문자 사용을 지향합니다.

주제 제목

주제 제목은 문장 형태를 사용하십시오. 예를 들어:

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

UI 텍스트

버튼 레이블, 페이지, 탭 또는 메뉴 항목과 같은 특정 사용자 인터페이스 텍스트를 언급할 때는 사용자 인터페이스에 표시된 대로 같은 대문자를 사용하십시오.

사용자 인터페이스 텍스트에 스타일 오류가 있다고 생각되면,

변경 사항을 제안하기 위해 문제를 만들거나 MR을 작성하십시오.

기능 이름

기능 이름은 소문자로 작성해야 합니다.

그러나 극히 드문 경우에는, 기능이 대문자 형태로 작성될 수 있습니다. 이러한 예외는 다음과 같습니다:

markdownlint에 고유 이름으로 추가된 경우, 따라서 모든 문서에서 일관되게 적용할 수 있습니다.
단어 목록에 추가된 경우.

단어 목록에 없는 용어에 대해선 GitLab 기술 작가에게 조언을 요청하십시오.

기본적으로 기능 페이지 또는 features.yml의 용어 또는 문구의 대문자와 맞추지 마십시오.

기타 용어

다음 이름의 첫 글자는 대문자로 작성하십시오:

GitLab 제품 티어. 예: GitLab Free와 GitLab Ultimate.
제3자 조직, 소프트웨어 및 제품. 예: Prometheus, Kubernetes, Git, The Linux Foundation.
방법 또는 방법론. 예: Continuous Integration, Continuous Deployment, Scrum, Agile.

엔티티에 대한 공식 출처에 기재된 대문자 스타일을 따르십시오. 이는 비표준 대문자 스타일을 사용할 수 있습니다. 예: 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을 사용하십시오.

가짜 토큰

API 호출을 시연하는 cURL 또는 CI에서 사용되는 변수를 사용할 때 토큰이 필요할 수 있습니다.

문서에서 실제 토큰을 사용하지 않는 것이 강력히 권장되며, 토큰이 악용될 가능성이 낮더라도 마찬가지입니다.

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

토큰 유형	토큰 값
개인 접근 토큰	`<your_access_token>`
애플리케이션 ID	`2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6`
애플리케이션 비밀	`04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df`
CI/CD 변수	`Li8j-mLUVA3eZYjPfd_H`
프로젝트 러너 토큰	`yrnZW46BrtBFqM7xDzE7dddd`
공유 러너 토큰	`6Vk7ZsosqQyfreAxXTZr`
트리거 토큰	`be20d8dcc028677c931e04f3871a9b`
웹후크 비밀 토큰	`6XhDroRcYPM5by_h-HLY`
상태 확인 토큰	`Tu7BgjR9qeZTEyRzGG2P`

축약형

축약형 사용은 권장되며, 특히 튜토리얼, 설명서 및 사용자 인터페이스에서 친근하고 비공식적인 분위기를 조성할 수 있습니다.

하지만 몇 가지 축약형은 피해야 합니다:

축약형 사용 금지	예시	대신 사용
고유명사와 동사의 조합	Terraform’s 유용한 도구입니다.	Terraform은 유용한 도구입니다.
부정을 강조하기 위해	Don’t X를 Y와 함께 설치하세요.	X를 Y와 함께 설치하지 마세요.
참조 문서에서	Don’t 제한을 설정하세요.	제한을 설정하지 마세요.
오류 메시지에서	로컬호스트에 대한 요청은 aren’t 허용되지 않습니다.	로컬호스트에 대한 요청은 허용되지 않습니다.

소유격

고유 명사에 대해서는 소유격('s) 사용을 피하도록 하세요, 예를 들어 조직이나 제품 이름에 대해서는요.

예를 들어, Docker's CLI 대신 the Docker CLI를 사용하세요.

자세한 정보는 구글 문서 스타일 가이드를 참조하세요.

전치사

필요한 경우 문장의 끝에 전치사를 사용하세요.

덩글링(dangling)이나 스트랜디드(stranded) 전치사도 괜찮습니다. 예시:

당신은 당신이 속한 그룹을 떠날 수 있습니다.
사용자와 자격 증명을 공유하세요.

이러한 표현이 대안보다 더 캐주얼합니다:

당신은 당신이 속한 그룹을 떠날 수 있습니다.
사용자와 자격 증명을 공유하세요.

약어

약어를 사용할 때, 페이지에서 처음 사용할 때는 풀어서 써야 합니다. 페이지에서 한 번 이상 풀어 쓸 필요는 없습니다.

제목: 주제 제목에서 약어는 가급적 피하세요, 특히 약어가 널리 사용되지 않는 경우에는요.
복수형: 약어의 복수형을 만들지 않도록 하세요. 예를 들어, YAML files를 사용하고, YAMLs는 사용하지 마세요. 약어를 복수형으로 만들어야 하는 경우에는, 아포스트로피를 사용하지 마세요. 예를 들어, APIs를 사용하고, API's는 사용하지 마세요.
소유격: 약어의 소유격을 만들 때 주의하세요. 가능한 경우, 문장을 작성하여 약어의 소유격을 피하세요. 약어의 소유격을 만들어야 할 경우, 단어를 풀어서 쓰는 것을 고려하세요.

숫자

본문의 숫자는 0에서 9까지는 철자로 쓰고, 10 이상은 숫자를 사용하세요. 더 많은 정보는 마이크로소프트 스타일 가이드를 참조하세요.

텍스트

Markdown으로 작성하기.
새 단락을 위해 빈 줄 삽입하세요.
서로 다른 마크업 간에는 빈 줄을 삽입하세요 (예: 각 단락, 제목, 목록 후 등). 예시:
```
## 제목

단락입니다.

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

줄 길이

소스 콘텐츠를 쉽게 읽을 수 있도록 하고, diffs를 더 쉽게 비교할 수 있도록, 가능한 경우 다음의 모범 사례를 따르세요.

약 100자에서 긴 줄을 나누세요.
각 새로운 문장은 새로운 줄에서 시작하세요.

주석

Markdown 내에서 주석을 임베드하려면, 발행 시 렌더링되지 않는 표준 HTML 주석을 사용하세요. 예시:

<!-- 이는 렌더링되지 않는 주석입니다 -->

구두점

구두점에 대한 다음 지침을 따르세요.

전체 문장은 마침표로 끝내세요. 표의 전체 문장도 포함됩니다.
세 개 이상의 항목 목록에서 마지막 and 또는 or 앞에 직렬(옥스포드) 쉼표를 사용하세요. ( OxfordComma.yml에서 테스트됨.)

콘텐츠 간격 조정 시:

문장 간에는 한 개의 공백을 사용하세요. (두 개 이상의 공백 사용에 대해서는 SentenceSpacing.yml에서 테스트했습니다.)
줄바꿈이 없는 공백을 사용하지 마세요. 대신 표준 공백을 사용하세요. ( lint-doc.sh에서 테스트됨.)
들여쓰기에 탭을 사용하지 마세요. 대신 공백을 사용하세요. 코드 편집기를 구성하여 Tab 키를 누를 때 공백 대신 탭을 출력하도록 설정할 수 있습니다.

다음 구두점 문자를 사용하지 마세요:

; (세미콜론): 두 개의 문장을 대신 사용하세요.
– (en dash) 또는 — (em dash): 대신 문장 또는 쉼표를 사용하세요.
“ ” ‘ ’: 더블 또는 싱글 타이포그래픽(“곡선”) 인용 부호. 대신 직선을 사용하세요. ( NonStandardQuotes.yml에서 테스트됨.)

자리 표시자 텍스트

코드 블록에서는 특정 값을 사용하는 명령이나 구성을 제공할 수 있습니다.

이 경우 독자가 자신의 값으로 텍스트를 교체해야 할 위치를 식별하기 위해 < 및 >를 사용하세요.

예:

cp <your_source_directory> <your_destination_directory>

자리 표시자가 코드 블록에 있지 않은 경우 < 및 >를 사용하고 자리 표시자를 단일 백틱으로 감싸세요. 예:

Select **Grant admin consent for `<application_name>`**.

인용 부호

직접 텍스트를 인용할 때만 인용 부호를 사용하고, 더블 인용 부호(")를 사용하세요.

UI 요소 및 인라인 코드 작성에 대한 지침은 텍스트 형식 지정을 참조하세요.

인용 부호 내에 문장을 넣지 마세요. 단, 인용한 텍스트의 일부인 경우는 제외합니다.

텍스트 형식 지정

텍스트를 형식화할 때는 다음을 사용하세요:

굵게 UI 요소 및 페이지에 사용.
인라인 코드 스타일 입력, 출력, 코드 및 유사 항목에 사용.
코드 블록 명령줄 예제 및 다중 행 입력, 출력, 코드 및 유사 항목에 사용.
<kbd> 키보드 명령어에 사용.

굵게

다음과 같은 경우에 굵게 사용하세요:

눈에 보이는 레이블이 있는 UI 요소. 레이블의 텍스트 및 대문자와 일치하도록 하세요.
탐색 경로.

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

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

예:

취소 선택.
문제 페이지에서…
파이프라인 탭에서…

텍스트를 굵게 만들려면 두 개의 별표(**)로 감싸세요. 예:

1. **취소** 선택.

인라인 코드

다음 용도로 인라인 코드를 사용하세요:

사용자가 UI에 입력하는 텍스트.
true, false, Job succeeded와 같은 짧은 입력 및 출력.
파일 이름, 구성 매개변수, 키워드 및 코드. 예를 들어: .gitlab-ci.yml, --version, 또는 rules:.
짧은 오류 메시지.
API 및 HTTP 메서드(POST).
HTTP 상태 코드. 전체(404 File Not Found) 및 약어(404).

예를 들어:

Name 텍스트 상자에 test를 입력하세요.
rules: CI/CD 키워드를 사용하여 파이프라인에 작업을 추가할 시기를 제어하세요.
러너를 삭제하려면 DELETE 요청을 보내세요. 하나를 만들려면 POST 요청을 보내세요.
작업 로그는 완료되면 Job succeeded를 표시합니다.

인라인 코드를 사용하려면, 텍스트를 단일 백틱(`)으로 감싸세요. 예를 들어:

**Name** 텍스트 상자에 `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.로 시작합니다. 렌더링될 때 목록 항목은 순차적으로 표시됩니다.
목록의 앞뒤에는 빈 줄을 남깁니다.
목록 항목 안에 중첩 하위 항목을 나타내기 위해서는 공백(탭 아님)으로 줄을 시작합니다.

목록 항목 안에 중첩하기

목록 항목 아래에 항목을 중첩할 수 있으며, 목록 항목과 같은 들여쓰기로 렌더링됩니다. 이를 통해 할 수 있는 중첩 항목은 다음과 같습니다:

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

중첩된 항목은 항상 목록 항목의 첫 번째 문자와 정렬되어야 합니다. 비정렬 목록(대시 사용)의 경우 각 들여쓰기 레벨에 대해 두 개의 공백을 사용하십시오:

- 비정렬 목록 항목 1

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

- 비정렬 목록 항목 2

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

- 비정렬 목록 항목 3

  ```plaintext
  목록 항목 3에 중첩된 코드 블록입니다.
  ```

- 비정렬 목록 항목 4

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

정렬 목록의 경우 각 들여쓰기 수준에 대해 3개의 공백을 사용하십시오:

1. 정렬 목록 항목 1

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

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

1. 정렬 목록 항목 하나.
1. 정렬 목록 항목 두 개.
   - 중첩 비정렬 목록 항목 하나.
   - 중첩 비정렬 목록 항목 두 개.
1. 정렬 목록 항목 세 개.

- 비정렬 목록 항목 하나.
- 비정렬 목록 항목 두 개.
  1. 중첩 정렬 목록 항목 하나.
  1. 중첩 정렬 목록 항목 두 개.
- 비정렬 목록 항목 세 개.

테이블

테이블은 복잡한 정보를 간단한 방식으로 설명하는 데 사용해야 합니다. 많은 경우, 비정렬 목록은 항목당 단일 및 간단한 설명으로 항목 목록을 설명하는 데 충분합니다. 그러나 행렬로 설명하는 것이 가장 좋은 데이터가 있다면, 테이블이 가장 좋은 선택입니다.

생성 지침

테이블은 접근 가능하고 스캔 가능하게 유지하기 위해 비어 있는 셀을 포함해서는 안 됩니다. 셀에 의미 있는 값이 없으면 N/A(해당 없음) 또는 None을 입력하는 것을 고려하십시오.

테이블을 유지 관리하기 쉽게 하려면 다음을 수행할 수 있습니다:

열 너비를 일관되게 만들기 위해 추가 공백을 추가합니다. 예를 들어:

| 앱 이름 | 설명               | 요구 사항     |
|---------|-------------------|----------------|
| 앱 1    | 설명 텍스트 1.    | A, B, C.      |
| 앱 2    | 설명 텍스트 2.    | None          |

매우 넓은 테이블의 경우, 오른쪽 열의 추가 공백을 생략할 수 있습니다. 예를 들어:

| 설정      | 기본값 | 설명                      |
|-----------|--------|--------------------------|
| 설정 1    | `1000` | 짧은 설명입니다.         |
| 설정 2    | `2000` | 이 열의 모든 셀을 정렬하면 테이블이 너무 넓어지고 빈 공간이 너무 많아지는 긴 설명입니다. |
| 설정 3    | `0`    | 또 다른 짧은 설명입니다. |

테이블 형식을 위한 편집기 확장

모든 Markdown 파일에서 일관된 테이블 형식을 보장하기 위해, VS Code의 Markdown Table Formatter로 테이블을 형식화하는 것을 고려하세요.

위의 가이드라인을 따르도록 이 확장을 구성하려면, 헤더 행 길이 따르기 설정을 활성화하세요.

설정을 활성화하려면:

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 명령 팔레트에서 Markdown Table Formatter를 선택하세요.

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

기존 테이블 업데이트

기존 테이블에 행을 추가하거나 편집하면, 새 행의 셀 너비가 더 넓어질 수 있습니다.

너비를 고려하여 열을 다시 정렬하면, diff가 읽기 어려워지는데, 이는 전체 테이블이 수정된 것으로 표시되기 때문입니다.

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

테이블 헤더

테이블 헤더에는 문장 대문자를 사용하세요. 예: Keyword value 또는 Project name.

기능 테이블

기능 목록의 테이블을 생성할 때 (예를 들어, Permissions 페이지에서 각 역할에 대해 제공되는 기능), 다음 문구를 사용하세요:

옵션	Markdown	표시된 결과
아니요	`{dotted-circle} No`	No
예	`{check-circle} Yes`	Yes

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

각주

테이블 아래에 각주는 테이블에 내용을 포함할 수 없을 때만 사용하세요.

예를 들어, 다음과 같은 경우에 각주를 사용하세요:

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

각주 형식

테이블에서 각주는 HTML 슈퍼스크립트 태그 <sup>를 사용하세요.

문장 끝에 태그를 넣고, 문장과 태그 사이에 한 칸의 공백을 두세요.

예를 들어:

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

각주를 추가할 때, 테이블에 기존 태그를 재정렬하지 마세요.

테이블 아래의 각주에는 **Footnotes:** 후에 정렬된 목록을 사용하세요.

예를 들어:

**Footnotes:**

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

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

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

Footnotes:

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

다섯 개 이상의 각주

다섯 개 이상의 각주를 테이블 자체에 포함할 수 없는 경우,

연속 번호를 목록 항목으로 사용할 수 있습니다.

연속 번호를 사용하는 경우, Markdown 규칙 029를 비활성화해야 합니다:

**각주:**

<!-- 비활성화된 정렬 목록 규칙 https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix -->
<!-- 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 저장소로 링크하려면, 다음과 같은 URL을 사용하세요: [GitLab Charts 문서](https://docs.gitlab.com/charts/).

앵커 링크

각 주제 제목에는 앵커 링크가 있습니다. 예를 들어, 제목이 ## 이것은 예시입니다인 주제는 앵커 #이것은-예시입니다를 가집니다.

페이지의 첫 번째 주제 제목(h1)에는 앵커 링크가 있지만, 사용하지 마세요. 대신 페이지로 링크하세요.

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

주제 제목 텍스트를 변경하면, 앵커 링크가 변경됩니다. 링크가 끊어지는 것을 피하려면:

주제 제목에 단계 번호를 사용하지 마세요.
가능하면 향후 변경될 수 있는 단어는 사용하지 마세요.

링크 및 제목 변경

주제 제목을 변경하면 앵커 링크도 변경됩니다. 관련 링크를 업데이트하도록 다음 디렉토리를 검색하세요:

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

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

링크 텍스트

링크 텍스트에 대한 가이드라인을 따르세요.

표준 텍스트

가능한 한 다음 패턴 중 하나를 따르는 텍스트를 사용하세요:

자세한 내용은 [링크 텍스트](link.md)를 참조하세요.
[이 작업 수행하기]를 보려면 [링크 텍스트](link.md)를 참조하세요.

예를 들어:

자세한 내용은 [병합 요청](link.md)을 참조하세요.
리뷰 앱을 생성하려면 [리뷰 앱](link.md)을 참조하세요.

이 기능에 대한 자세한 내용은 다음을 참조하세요...와 같은 문구를 사용하여 이 텍스트를 확장할 수 있습니다.

다음과 같은 표현은 사용하지 마세요:

자세한 내용을 알아보세요...
더 읽어보려면...
자세한 내용은 [병합 요청](link.md) 페이지를 참조하세요.
자세한 내용은 [병합 요청](link.md) 문서를 참조하세요.

`여기`보다는 설명적인 텍스트

링크에 ‘여기’ 또는 ‘이 페이지’와 같은 단어보다 설명적인 텍스트를 사용하세요.

예를 들어, 다음과 같은 대신:

자세한 내용은 [이 페이지](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`

특정 코드 줄 링크

파일의 특정 줄에 링크할 때, 브랜치가 아닌 커밋에 링크하십시오. 코드 줄은 시간이 지남에 따라 변경됩니다. 커밋 링크를 사용하여 줄에 링크하면 사용자가 참조하는 줄로 이동할 수 있습니다. 프로젝트에서 파일을 볼 때 표시되는 Permalink 버튼은 해당 파일의 최신 커밋에 대한 링크를 제공합니다.

해야 하는 것: [line 3에 연결하기](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
하지 말아야 할 것: [line 3에 연결하기](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).

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

탐색

GitLab UI 탐색 방법을 문서화할 때:

항상 위치, 다음 작업 순서로 사용하십시오.
- Visibility 드롭다운 목록(위치)에서 Public(작업)을 선택하십시오.
간결하고 구체적이어야 합니다. 예를 들어:
- 해야 하는 것: Save를 선택하십시오.
- 하지 말아야 할 것: 변경 사항이 적용되도록 Save를 선택하십시오.
단계에 이유를 포함해야 하는 경우, 해당 단계의 시작 부분에 이유를 적으십시오. 이렇게 하면 사용자가 더 빠르게 스캔할 수 있습니다.
- 해야 하는 것: 변경 사항을 보려면 병합 요청에서 링크를 선택하십시오.
- 하지 말아야 할 것: 변경 사항을 보려면 병합 요청에서 링크를 선택하십시오.

메뉴 이름

GitLab 사용자 인터페이스 주요 요소를 언급할 때 다음 용어를 사용하십시오:

왼쪽 사이드바: 사용자 인터페이스 왼쪽의 탐색 사이드바입니다.
- context switcher 또는 switch contexts라는 문구를 사용하지 마십시오. 대신, 반복 가능한 단계 세트를 사용하여 사용자에게 정확한 위치로 안내하십시오.
- the **Explore** menu 또는 the **Your work** sidebar라는 문구를 사용하지 마십시오. 대신 the left sidebar를 사용하십시오.
오른쪽 사이드바: 열린 이슈, 병합 요청 또는 에픽에 특정한 사용자 인터페이스의 탐색 사이드바입니다.

UI 요소 이름

모든 UI 요소는 굵게 작성해야 합니다.

개별 UI 요소에 대한 안내는 단어 목록에 있습니다.

탐색 작업 단계 작성 방법

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

프로젝트 설정을 열려면:

왼쪽 사이드바에서 **Search or go to**를 선택하고 프로젝트를 찾으십시오.
**Settings > CI/CD**를 선택하십시오.
**General pipelines**을 확장하십시오.

그룹 설정을 열려면:

왼쪽 사이드바에서 **Search or go to**를 선택하고 그룹을 찾으십시오.
**Settings > CI/CD**를 선택하십시오.
**General pipelines**을 확장하십시오.

프로젝트 또는 그룹 설정을 열려면:

왼쪽 사이드바에서 **Search or go to**를 선택하고 프로젝트 또는 그룹을 찾으십시오.
**Settings > CI/CD**를 선택하십시오.
**General pipelines**을 확장하십시오.

프로젝트를 만들려면:

1. 왼쪽 사이드바에서 상단의 **Create new** (**{plus}**)를 선택하고 **New project/repository**를 선택하십시오.

그룹을 만들려면:

1. 왼쪽 사이드바에서 상단의 **Create new** (**{plus}**)를 선택하고 **New group**을 선택하십시오.

Admin 영역을 열려면:

1. 왼쪽 사이드바에서 하단의 **Admin**을 선택하십시오.
1. **Settings > CI/CD**를 선택하십시오.

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

Your work 메뉴 항목을 열려면:

1. 왼쪽 사이드바에서 **Search or go to**를 선택하십시오.
1. **Your work**를 선택하십시오.

아바타를 선택하려면:

1. 왼쪽 사이드바에서 아바타를 선택하십시오.

일부 드롭다운 목록에서 선택을 저장하려면:

이슈로 이동하십시오.
오른쪽 사이드바의 **Iteration** 섹션에서 **Edit**를 선택하십시오.
드롭다운 목록에서 이 이슈와 연결할 반복을 선택하십시오.
드롭다운 목록 외부의 영역을 선택하십시오.

모든 프로젝트를 보려면:

1. 왼쪽 사이드바에서 **Search or go to**를 선택하십시오.
1. **View all my projects**를 선택하십시오.

모든 그룹을 보려면:

1. 왼쪽 사이드바에서 **Search or go to**를 선택하십시오.
1. **View all my groups**를 선택하십시오.

선택적 단계

단계가 선택 사항인 경우, 해당 단어로 시작하십시오. Optional 다음에 문장을 작성합니다.

예를 들어:

1. Optional. 작업에 대한 설명을 입력합니다.

권장 단계

단계가 권장되는 경우, 해당 단어로 시작하십시오. Recommended 다음에 문장을 작성합니다.

예를 들어:

1. Recommended. 작업에 대한 설명을 입력합니다.

여러 필드를 동시에 문서화하기

UI 텍스트가 섹션의 필드를 충분히 설명하는 경우, 각 필드에 대한 작업 단계를 포함하지 마십시오.

대신, 여러 필드를 단일 작업 단계로 요약합니다.

필드를 완료합니다라는 문구를 사용하십시오.

예를 들어:

왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > Repository를 선택합니다.
Push rules를 확장합니다.
필드를 완료합니다.

여러 필드를 문서화하되 설명이 필요한 필드가 하나뿐인 경우, 같은 단계에서 설명합니다:

Push rules를 확장합니다.
필드를 완료합니다. Branch name은 정규 표현식이어야 합니다.

여러 필드를 설명할 경우, 순서 없는 목록 항목을 사용하십시오:

General pipelines를 확장합니다.
필드를 완료합니다.
- Branch name은 정규 표현식이어야 합니다.
- User는 최소한 Maintainer 역할을 가진 사용자여야 합니다.

삽화

GitLab 문서는 두 가지 삽화 유형을 사용합니다:

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

삽화는 독자가 개념을 이해하는 데 도움이 되며, 복잡한 프로세스 내에서 자신의 위치를 파악하거나 애플리케이션과 상호작용하는 방법을 이해하는 데 도움이 됩니다. 삽화는 다음과 같은 이유로 드물게 사용해야 합니다:

구식이 될 수 있습니다.
지역화가 어렵고 비용이 많이 듭니다.
스크린 리더가 읽을 수 없습니다.

문서에서 삽화를 사용해야 하는 경우, 그것들은 다음과 같아야 합니다:

텍스트를 보완해야 하며, 대체해서는 안 됩니다. 독자는 필요한 정보를 얻기 위해 삽화에만 의존해서는 안 됩니다.
앞선 텍스트에 소개 문장이 있어야 합니다. 예를 들어, 다음 다이어그램은 제품 분석 흐름을 보여줍니다:.
접근 가능해야 합니다. 자세한 내용은 스크린샷 및 다이어그램에 대한 특정 지침을 참조하십시오.
개인 식별 정보를 제외하십시오.

스크린샷

관련 정보가 텍스트로 전달될 수 없는 경우, GitLab 사용자 인터페이스의 특정 부분을 보여주기 위해 스크린샷을 사용하십시오.

스크린샷 캡처

스크린샷을 찍을 때:

가치를 제공해야 합니다. lorem ipsum 텍스트를 사용하지 마십시오. 기능이 실제 시나리오에서 어떻게 사용될지를 복제하려고 하고, 현실적인 텍스트 사용을 시도하십시오.
관련 UI만 캡처하십시오. 불필요한 여백이나 포인트를 설명하는 데 도움이 되지 않는 UI 영역을 포함하지 마십시오. GitLab의 사이드바는 변경될 수 있으니, 꼭 필요한 경우가 아니면 스크린샷에 포함하지 마십시오.
작게 유지하십시오. 화면의 전체 너비를 보여줄 필요가 없는 경우, 그럴 필요가 없습니다. 브라우저 창의 크기를 가능한 한 줄여 요소를 가깝게 유지하고 빈 공간을 줄입니다. 스크린샷 치수를 가능한 작게 유지하려고 하십시오.
이미지가 페이지에서 어떻게 렌더링되는지 검토하십시오. 이미지를 로컬에서 미리 보거나, 병합 요청의 검토 앱을 사용하여 미리 보십시오. 이미지가 흐릿하거나 과도하게 복잡하지 않은지 확인하십시오.
일관성을 유지하십시오. 문서 페이지에 이미 있는 다른 스크린샷과 조정하여 일관된 읽기 경험을 제공합니다. 내비게이션 테마가 Indigo이고, 문법 강조 테마가 Light인지 확인하십시오. 이들이 기본 설정입니다.

호출 추가하기

스크린샷의 특정 영역을 강조할 필요가 있다면 화살표를 사용하세요.

색상은 #EE2604를 사용하세요. macOS에서 미리보기 애플리케이션을 사용할 경우 기본 빨간색입니다.
선의 두께는 3 pt를 사용하세요. macOS에서 미리보기 애플리케이션을 사용할 경우 목록의 세 번째 선입니다.
다음 이미지에 표시된 화살표 스타일을 사용하세요.
여러 개의 화살표가 있을 경우 가능하면 평행하게 만드세요.

이미지 요구 사항

모든 넓거나 긴 스크린샷의 크기를 조정하세요.
- 너비는 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는 https://ezgif.com/optimize 또는 비슷한 도구로 압축하세요.

문서를 설명하기 위해 비디오를 링크하거나 임베드하는 방법도 참조하세요.

이미지 압축

문서에 추가하는 새로운 이미지는 항상 압축해야 합니다. 알려진 도구는 pngquant로, 플랫폼 간 호환되고 오픈 소스입니다. 공식 웹사이트를 방문하고 OS에 대한 지침에 따라 설치하세요.

macOS를 사용하고 모든 스크린샷이 자동으로 압축되기를 원한다면 스크린샷을 80% 더 작게 만드는 간단한 요령을 읽어보세요.

GitLab에는 수동 과정을 간소화하는 데 사용할 수 있는 Ruby 스크립트가 있습니다. 로컬 https://gitlab.com/gitlab-org/gitlab 복사본의 루트 디렉토리에서 터미널에 다음을 실행하세요:

압축하기 전에 원한다면 모든 문서 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 코드는 다음과 같습니다:

![이미지 설명, 대체 태그로 사용](img/document_image_title_vX_Y.png)

대체 텍스트

대체 텍스트는 접근 가능한 경험을 제공합니다.

스크린 리더는 대체 텍스트를 사용하여 이미지를 설명하며, 이미지를 다운로드하지 못할 경우 대체 텍스트가 표시됩니다.

대체 텍스트는 이미지의 내용을 설명하는 것이 아니라 이미지의 맥락을 설명해야 합니다. 페이지나 섹션의 주제와 관련된 컨텍스트를 추가하세요. 이미지를 보고 페이지와 상호작용하는 데 도움을 주고 싶은 경우, 어떻게 설명할 것인지 고려해 보세요.

Do:

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

Do not:

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

대체 텍스트를 작성할 때:

155자 이하의 짧고 설명적인 대체 텍스트를 작성하세요.

스크린 리더는 일반적으로 이만큼의 문자 이후에 읽기를 멈춥니다.
이미지에 복잡한 정보(예: 워크플로우 다이어그램)가 있는 경우, 짧은 대체 텍스트를 사용하여 이미지를 식별하고 텍스트에 자세한 정보를 포함하세요.
문장부호를 사용하세요.
텍스트가 완전한 문장이 아닌 경우 마침표를 사용하지 마세요.
모든 완전한 문장 뒤에 마침표를 사용하세요.
문장 대문자를 사용하고 모든 대문자 사용을 피하세요.

일부 스크린 리더는 대문자를 개별 문자로 읽습니다.
이미지의 또는 그래픽의와 같은 구문을 사용하지 마세요.
키워드를 나열하는 문자열을 사용하지 마세요.

컨텍스트를 향상시키기 위해 텍스트에 키워드를 포함하세요.
주제에서 이미지를 소개하고 대체 텍스트에서 소개하지 마세요.
이미지를 주제에서 반복하는 것을 피하세요.
굵게, 이탤릭체 또는 백틱과 같은 인라인 스타일링을 사용하지 마세요.

스크린 리더는 **text**를 별 별 text 별 별로 읽습니다.

자동 스크린샷 생성기

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

GitLab Development Kit (GDK)를 설정하세요.
복제한 GitLab 리포지토리가 있는 하위 디렉토리로 이동하세요. 일반적으로 gdk/gitlab입니다.
GDK 데이터베이스가 완전히 마이그레이션되었는지 확인하세요: bin/rake db:migrate RAILS_ENV=development.
pngquant를 설치하세요. 도구 웹사이트에서 자세한 정보를 참조하세요: pngquant
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 '<path/to/images/directory>'
```

페이지의 스크린샷을 찍으려면 visit <path>를 사용하세요.

빈 스크린샷을 피하기 위해 expect를 사용하여 콘텐츠가 로드될 때까지 기다리세요.

단일 요소 스크린샷

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

스크린샷 생성기 파일에 다음을 추가하세요:

screenshot_area = find('<element>') # 요소 찾기
scroll_to screenshot_area # 요소로 스크롤
expect(screenshot_area).to have_content '<content>' # 캡처하려는 콘텐츠를 기다림
set_crop_data(screenshot_area, <padding>) # 여백을 추가하여 요소를 캡처

spec/docs_screenshots/container_registry_docs.rb를 가이드로 사용하여 자신의 스크립트를 만드세요.

다이어그램

정보가 텍스트로만 이해하기에는 너무 복잡한 경우, 프로세스 또는 엔티티 간의 관계를 설명하기 위해 다이어그램을 사용하세요.

다이어그램을 만들기 위해 Mermaid를 사용하세요. Mermaid는 다음과 같은 장점이 있습니다:

Mermaid 포맷은 문서의 Markdown 소스에 코드 블록으로 저장되므로 유지 관리가 더 쉽습니다.
다이어그램은 런타임에 동적으로 렌더링됩니다.
다이어그램의 텍스트 콘텐츠(예: 기능 이름)는 텍스트 검색 도구로 찾을 수 있으며, 편집할 수 있습니다.
다이어그램은 확장 가능한 이미지로 렌더링됩니다. 다양한 출력 장치 및 크기에 더 적합합니다.

Mermaid 문법으로 다이어그램을 만드는 방법을 배우고 싶다면 Mermaid 사용자 가이드와 Mermaid 사이트의 예제를 참조하세요.

가이드라인

접근 가능하고 쉽게 유지 관리할 수 있는 다이어그램을 만들기 위해 다음 가이드라인을 따르세요:

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

다이어그램 만들기

GitLab 문서용 다이어그램을 만들기 위해:

Mermaid Live Editor에서 다이어그램을 만드세요.
코드 패널의 내용을 복사하여 Markdown 파일에 붙여넣고, mermaid 코드 블록으로 감싸세요. 자세한 내용은 Mermaid용 GitLab Flavored Markdown를 참조하세요.
다이어그램에 GitLab 글꼴 스타일을 추가하려면, Mermaid 코드 블록 선언과 다이어그램 유형 사이에 다음 줄을 추가하세요:
```
%%{init: { "fontFamily": "GitLab Sans" }}%%
```
다이어그램 유형 선언 다음 줄에 접근성을 위한 다음 줄을 추가하세요:
```
accTitle: your diagram title here
accDescr: describe what your diagram does in a single sentence, with no line breaks.
```
제목과 설명이 대체 텍스트 가이드라인을 따르도록 하세요.

예를 들어, 이 흐름도는 접근성과 글꼴 정보를 모두 포함하고 있습니다:

```mermaid
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
    accTitle: 예제 다이어그램 제목
    accDescr: 다이어그램의 설명을 한 문장으로 작성하세요.

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

이모지

Markdown 이모지 형식, 예를 들어 :smile:를 어떤 목적으로도 사용하지 마십시오. 대신 GitLab SVG 아이콘을 사용하세요.

Markdown에서 이모지를 사용하려면 GitLab Flavored Markdown이 필요하며, 이는 GitLab 문서에 사용되는 Markdown 렌더링 엔진인 Kramdown에서 지원되지 않습니다.

GitLab SVG 아이콘

문서에서 GitLab SVG 라이브러리의 아이콘을 직접 사용할 수 있습니다. 예를 들어, **{tanuki}**는 다음과 같이 렌더링됩니다: .

대부분의 경우 텍스트 안에서 아이콘을 사용하는 것을 피해야 합니다.

그러나 UI 요소를 설명하는 유일한 방법이 호버 텍스트인 경우 아이콘을 사용할 수 있습니다. 예를 들어, 삭제 또는 편집 버튼은 종종 호버 텍스트만 가집니다.

아이콘을 사용할 때는 호버 텍스트로 시작하고 그 뒤에 괄호 안에 SVG 참조를 따라야 합니다.

피하십시오: Select **{pencil}** **Edit**. 이로 인해 생성됩니다: Select Edit.
대신 사용하십시오: Select **Edit** (**{pencil}**). 이로 인해 생성됩니다: Select Edit ().

아이콘을 설명하기 위해 단어를 사용하지 마십시오:

피하십시오: Select **Erase job log** (the trash icon).
대신 사용하십시오: Select **Erase job log** (**{remove}**). 이로 인해 생성됩니다: Select Erase job log ().

버튼에 호버 텍스트가 없는 경우 아이콘을 설명할 수 있습니다. 이후 UX 버그 문제를 생성하여 버튼에 호버 텍스트를 추가하여 접근성을 개선하세요.

피하십시오: Select **{ellipsis_v}**.
대신 사용하십시오: Select the vertical ellipsis (**{ellipsis_v}**). 이로 인해 생성됩니다: Select the vertical ellipsis ().

비디오

문서에 GitLab YouTube 비디오 튜토리얼을 추가하는 것이 적극 권장됩니다. 단, 비디오가 구식인 경우는 제외입니다. 비디오는 문서를 대체하는 것이 아니라 보완하거나 설명해야 합니다. 비디오의 내용이 기능과 주요 사용 사례에 근본적이지만 문서에서 충분히 다루어지지 않은 경우, 다음을 수행해야 합니다:

이 세부정보를 문서 텍스트에 추가합니다.
비디오를 검토하고 페이지를 업데이트하기 위해 문제를 생성합니다.

비디오를 제품 저장소에 업로드하지 마십시오. 대신 링크하거나 임베드하십시오.

비디오 링크

비디오에 링크하려면 독자가 비디오를 읽기 전에 페이지에서 스캔할 수 있도록 YouTube 아이콘을 포함하세요. 링크 뒤에 비디오의 게시 날짜를 포함하여 구식일 수 있는 비디오를 식별하는 데 도움이 됩니다.

<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
개요에 대한 자세한 내용은 [비디오 제목](https://link-to-video)을 참조하세요.
<!-- 비디오 게시 날짜: YYYY-MM-DD -->

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

비디오 임베드

GitLab 문서 사이트는 임베드 비디오를 지원합니다.

다른 소스의 비디오는 링크해야 하며, GitLab의 공식 YouTube 계정에서만 비디오를 임베드할 수 있습니다.

대부분의 경우, 비디오에 링크하는 것이 좋습니다. 임베드된 비디오는 페이지에서 많은 공간을 차지하고 독자에게 방해가 될 수 있기 때문입니다.

비디오를 임베드하려면:

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

여기에 빈 줄을 남기세요
<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 문서 사이트에서 다음과 같이 렌더링되는 방식입니다:

비디오 보기: GitLab이란?.

이 형식으로:

figure 태그는 의미론적 SEO를 위해 필수이며 video-container 클래스는 비디오가 반응형으로 표시되고 다양한 모바일 장치에서 표시되도록 보장합니다.
<div class="video-fallback">은 /help에 필요하며, GitLab Markdown 프로세서가 iframes를 지원하지 않기 때문에 필요합니다. 이는 문서 사이트에서는 숨겨지지만 /help에서는 표시됩니다.
www.youtube-nocookie.com 도메인은 YouTube 임베드 플레이어의 Privacy Enhanced Mode를 활성화합니다. 이 모드는 제한된 쿠키 환경 설정을 가진 사용자가 임베드된 비디오를 볼 수 있도록 합니다.

클릭-투-데모 링크

클릭-투-데모에 대한 링크는 비디오와 유사한 지침을 따라야 합니다.

클릭-투-데모의 경우 [데모 제목](https://link-to-demo)을 참조하세요.
<!-- 데모는 YYYY-MM-DD에 게시됨 -->

경고 박스

정보에 주의를 끌기 위해 경고 박스를 사용하세요.

간헐적으로 사용하고, 다른 경고 박스 바로 뒤에 경고 박스가 오도록 하지 마세요.

경고 박스는 다음 단어들 중 하나가 줄 바꿈 뒤에 올 때 생성됩니다:

FLAG:
NOTE:
WARNING:
DISCLAIMER:
DETAILS:

예를 들어:

NOTE:
이것은 주목해야 할 사항입니다.

여러 단락, 목록 또는 헤딩에 대한 경고 박스를 표시하려면 대신 인용문을 사용하세요.

경고 박스는 GitLab 문서 사이트(https://docs.gitlab.com)에서만 렌더링됩니다. GitLab 제품 도움말에서는 경고 박스가 일반 텍스트로 표시됩니다.

플래그

이 경고 유형을 사용하여 기능의 가용성을 설명하세요.

FLAG 경고를 형식화하는 방법에 대한 정보는 기능 플래그 뒤에 배포된 기능 문서를 참조하세요.

노트

노트는 간헐적으로 사용하세요. 너무 많은 노트는 주제를 스캔하기 어렵게 만들 수 있습니다.

노트를 추가하는 대신:

문장을 단락의 일부로 다시 작성하세요.
정보를 자체 단락에 넣으세요.
내용을 새로운 주제 제목 아래에 넣으세요.

노트를 반드시 사용해야 하는 경우, 다음 형식을 사용하세요:

NOTE:
이것은 주목해야 할 사항입니다.

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

이것은 주목해야 할 사항입니다.

경고

경고를 사용하여 더 이상 지원하지 않는 기능을 나타내거나 데이터 손실 가능성이 있는 절차에 대한 경고를 제공합니다.

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

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

이것은 경고해야 할 사항입니다.

면책 조항

아직 제공되지 않은 기능에 대해 반드시 작성해야 하는 경우, 해당 내용 근처에 이 정확한 미래 지향적 진술에 대한 면책 조항을 넣으세요.

DISCLAIMER:
이 페이지에는 향후 제품, 기능 및 기능에 대한 정보가 포함되어 있습니다.
제공된 정보는 정보 제공 목적으로만 제공된다는 점에 유의하시기 바랍니다.
구매 또는 계획 목적으로 이 정보를 의존하지 마십시오.
제품, 기능 또는 기능의 개발, 출시 및 타이밍은 변경 또는 지연될 수 있으며 GitLab Inc.의 단독 재량에 따라 결정됩니다.

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

이 페이지에는 향후 제품, 기능 및 기능에 대한 정보가 포함되어 있습니다.
제공된 정보는 정보 제공 목적으로만 제공된다는 점에 유의하시기 바랍니다.
구매 또는 계획 목적으로 이 정보를 의존하지 마십시오.
제품, 기능 또는 기능의 개발, 출시 및 타이밍은 변경 또는 지연될 수 있으며 GitLab Inc.의 단독 재량에 따라 결정됩니다.

페이지의 모든 내용이 사용 가능하지 않은 경우, 페이지 상단에 한 번만 미래 지향적 진술에 대한 면책 조항을 사용하세요.

주제의 내용이 준비되지 않은 경우 주제 내에서 면책 조항을 사용하세요.

자세한 내용은 향후 버전에서 기대되는 기능을 참조하세요.

세부 정보

DETAILS: 경고 박스는 제품 가용성 세부 정보에 사용됩니다.

인용문

인용문 내의 텍스트를 강조하려면 다음 형식을 사용하세요:

> 이것은 인용문입니다.

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

이것은 인용문입니다.

텍스트가 여러 줄에 걸쳐 있는 경우, 줄을 나눌 수 있습니다.

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

> 이것은 첫 번째 단락입니다.
>
> 이것은 두 번째 단락입니다.
>
> - 이것은 목록 항목입니다.
> - 목록의 두 번째 항목입니다.

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

이것은 첫 번째 단락입니다.

이것은 두 번째 단락입니다.

이것은 목록 항목입니다.

목록의 두 번째 항목입니다.

탭

문서 사이트에서는 텍스트를 형식화하여 탭으로 표시할 수 있습니다.

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

::Tabs

:::TabTitle Tab One

탭 1의 내용입니다.

:::TabTitle Tab Two

탭 2의 다른 내용입니다.

::EndTabs

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

Tab One

탭 1의 내용입니다.

Tab Two

탭 2의 다른 내용입니다.

탭 제목은 간결하고 일관되게 작성하세요. 그들은 평행해야 하며 각 제목의 첫 글자는 대문자로 시작해야 합니다.

예를 들어:

Linux package (Omnibus), Helm chart (Kubernetes) (구성 수정 문서를 작성할 때, 구성 수정 가이드를 따르세요)
15.1 and earlier, 15.2 and later

탭에 대한 고유한 URL 매개변수가 있음에도 불구하고, 단일 탭에 직접 링크하는 것을 피하세요 (Issue 1355).

탭에 대한 자세한 내용은 Pajamas를 참조하세요.

표절

출처가 인용된 제한된 인용을 제외하고는 다른 출처의 내용을 복사하여 붙여넣지 마세요. 일반적으로 관련 정보를 자신의 말로 재진술하거나 다른 출처로 연결하는 것이 더 좋습니다.

향후 버전의 유망한 기능

향후 릴리스에서 기능을 제공하겠다고 약속하지 마세요. 예를 들어, “이 기능에 대한 지원이 계획되고 있습니다.”와 같은 문구를 피하세요.

우리는 향후 기능 작업을 보장할 수 없으며, 이러한 약속은 법적 문제를 일으킬 수 있습니다. 대신, 문제가 있음을 언급하세요. 예를 들어:

개선 사항에 대한 지원은 [issue <issue_number>](https://link-to-issue)에서 제안됩니다.
이 작업을 수행할 수는 없지만, [issue 12345](https://link-to-issue)가 이 동작을 변경하자고 제안합니다.

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

향후 기능을 문서화해야 하는 경우 면책 조항을 사용하세요.

제품 및 기능

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

이름에 줄 바꿈 피하기

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

제품 가용성 세부정보

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

제품 가용성 세부정보에 대해 자세히 읽어보세요.

특정 섹션

특정 섹션에는 특정 스타일이 적용되어야 합니다. 특정 섹션에 대한 스타일은 이 섹션에 설명되어 있습니다.

도움말 및 피드백 섹션

이 섹션은 각 문서의 끝에 표시되며, 다음과 같이 프런트 매터에 키를 추가하여 생략할 수 있습니다:

---
feedback: false
---

기본값은 그 자리에 두는 것입니다. 문서에서 생략하려는 경우, 사전 기술 작가와 확인해야 합니다.

피드백 섹션의 클릭 이벤트는 Google 태그 관리자(Google Tag Manager)로 추적됩니다. 전환은 Behavior > Events > Top events > docs에서 Google Analytics를 통해 확인할 수 있습니다.

GitLab 재시작

GitLab의 재시작 또는 재구성이 필요할 때, 중복을 피하기 위해 다음과 같이 doc/administration/restart_gitlab.md로 링크하세요. 여기서 ‘reconfigure’를 필요에 따라 ‘restart’로 교체하세요:

파일을 저장하고 [재구성 GitLab](../../../administration/restart_gitlab.md)하여 변경 사항을 적용하세요.

문서가 doc/ 디렉토리 외부에 위치한 경우, 상대 링크 대신 전체 경로를 사용하세요: https://docs.gitlab.com/ee/administration/restart_gitlab.html.

다양한 설치 방법 문서화 방법

GitLab은 다섯 가지 공식 설치 방법을 지원합니다. 문장 및 제목의 일부로 단어를 사용할 때는 다음 문구를 사용하십시오:

Linux 패키지
Helm 차트
GitLab 운영자
Docker
사용자 컴파일

설명용 괄호를 추가하는 것은 괜찮습니다. 탭을 사용하는 경우:

Linux 패키지 (Omnibus)
Helm 차트 (Kubernetes)
GitLab 운영자 (Kubernetes)
Docker
사용자 컴파일 (source)

셀프 관리 구성 절차를 설명하기 위해 탭 사용하기

구성 절차는 사용자가 구성 파일을 편집하고, GitLab을 재구성하거나, GitLab을 다시 시작해야 할 수 있습니다. 이 경우:

탭을 사용하여 다양한 설치 방법을 구분합니다.
이전 목록에서 설명한 설치 방법 이름을 정확히 사용합니다.
아래 설명된 순서대로 사용합니다.
코드 블록이 목록 항목과 일치하도록 들여쓰기합니다.
각 코드 블록에 대해 적절한 구문 강조를 사용합니다 (ruby, shell, 또는 yaml).
YAML 파일의 경우 항상 부모 설정을 포함합니다.
GitLab을 재구성하거나 다시 시작하는 마지막 단계는 매번 동일하므로 그대로 사용할 수 있습니다.

구성 편집을 설명할 때, 다음 스니펫을 자유롭게 사용하고 편집할 수 있습니다:

::Tabs

:::TabTitle Linux 패키지 (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 사용자 컴파일 (source)

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

다음과 같이 렌더링됩니다:

Linux 패키지 (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
```

사용자 컴파일 (source)

/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 음성

문서는 진실의 단일 출처(SSoT)

주제 유형

Docs-first 방법론

현지화를 위한 글쓰기

마크다운

마크다운의 HTML

마크다운의 제목 수준

언어

능동태

고객 관점

신뢰 구축

대문자 표기

주제 제목

UI 텍스트

기능 이름

기타 용어

가짜 사용자 정보

가짜 URL

가짜 토큰

축약형

소유격

전치사

약어

숫자

텍스트

줄 길이

주석

구두점

자리 표시자 텍스트

인용 부호

텍스트 형식 지정

굵게

인라인 코드

코드 블록

키보드 명령

기울임체 및 강조

목록

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

목록 마크업

목록 항목 안에 중첩하기

테이블

생성 지침

테이블 형식을 위한 편집기 확장

기존 테이블 업데이트

테이블 헤더

기능 테이블

각주

각주 형식

다섯 개 이상의 각주

링크

같은 저장소의 링크

별도의 저장소의 링크

앵커 링크

링크 및 제목 변경

링크 텍스트

표준 텍스트

여기보다는 설명적인 텍스트

이슈 링크

외부 문서 링크

기밀 또는 제한 액세스 링크

특정 코드 줄 링크

탐색

메뉴 이름

UI 요소 이름

탐색 작업 단계 작성 방법

선택적 단계

권장 단계

여러 필드를 동시에 문서화하기

삽화

스크린샷

스크린샷 캡처

호출 추가하기

이미지 요구 사항

이미지 압축

애니메이션 이미지

이미지 링크를 콘텐츠에 추가

대체 텍스트

자동 스크린샷 생성기

`여기`보다는 설명적인 텍스트