문서 스타일 가이드#

  이 문서는 문법, 서식 등 GitLab 문서의 표준을 정의합니다.

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

GitLab의 목소리#

GitLab 브랜드 가이드라인은 조직 전체에서 사용하는 목소리를 정의합니다.

이 가이드라인을 바탕으로, GitLab 문서의 목소리는 간결하고 직접적이며 정확하게 작성하려 합니다. 목표는 검색하고 훑어보기 쉬운 정보를 제공하는 것입니다.

문서의 목소리는 대화체이되 간략하고, 친근하되 간명해야 합니다.

문서는 단일 진실 공급원(Single Source Of Truth, SSOT)#

GitLab 문서는 구현, 사용, 트러블슈팅과 관련된 모든 제품 정보의 SSOT입니다. 문서는 지속적으로 발전합니다. 새로운 제품과 기능이 추가되고, 명확성·정확성·완전성을 위한 개선이 이루어집니다.

이 정책은:

• 정보 사일로를 방지하고 GitLab 제품 정보를 더 쉽게 찾을 수 있도록 합니다.

• 문서의 여러 위치에 콘텐츠가 중복될 수 없다는 의미가 아닙니다.

주제 유형#

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

주제 유형은 사용자가 정보를 더 빠르게 이해하는 데 도움이 됩니다. 또한 다음 문제를 해결하는 데 도움이 됩니다:

• 콘텐츠를 찾기 어렵습니다. GitLab 문서는 방대하며 유용한 정보를 대량으로 포함합니다. 주제 유형은 콘텐츠를 더 쉽게 훑어보고 파악할 수 있도록 반복 가능한 패턴을 만들어냅니다.

• 콘텐츠가 기여자의 관점에서 작성되는 경우가 많습니다. GitLab 문서는 다양한 기여자들이 작성합니다. 주제 유형(특히 task)은 기능이 어떻게 구현되었는지를 문서화하는 것이 아니라, 다른 사람들을 돕는 데 초점을 맞춘 형식으로 정보를 구성하는 데 도움을 줍니다.

Docs-first 방법론#

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

• 질문에 대한 답변이 문서에 있는 경우, 정보를 다시 설명하는 대신 문서 링크를 공유하세요.

• GitLab 문서에서 제공되지 않는 정보를 발견한 경우, 해당 정보를 문서에 추가하는 머지 리퀘스트(MR)를 생성하세요. 그런 다음 MR을 공유하여 정보를 전달하세요.

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

현지화를 위한 작성#

우리는 글로벌 독자를 위해 작성하는 데 도움이 되는 가이드라인을 따릅니다.

GitLab의 목소리는 번역을 고려하여 명확하고 직접적으로 작성할 것을 요구합니다. 스타일 가이드, 단어 목록, Vale 규칙은 문서의 일관성을 보장합니다.

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

다음 규칙은 문서를 더 효율적으로 번역하는 데 도움이 됩니다.

피해야 할 사항:

• there is 및 there are와 같이 주어를 숨기는 표현.

• it과 같은 모호한 대명사.

• -ing으로 끝나는 단어.

• since와 because처럼 혼동될 수 있는 단어.

• e.g. 및 i.e.와 같은 라틴어 약어.

• kill two birds with one stone과 같은 문화별 표현.

사용해야 할 사항:

• 표준 링크 텍스트.

• 복잡한 문장과 단락 대신 목록 및 표.

• AI 및 CI/CD와 같은 일반적인 약어와 이미 풀어 쓴 약어.

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

• 기능 이름 및 해당 기능과 상호작용하는 방법에 대해 일관성을 유지하세요.

• 명사 나열을 분리하세요. 예를 들어 project integration custom settings 대신 custom settings for project integrations를 사용하세요.

• 날짜 및 시간을 일관되게, 그리고 국제 독자를 고려하여 형식화하세요.

• 스크린샷을 포함한 일러스트레이션은 최소한으로 사용하세요.

• UI 텍스트의 경우 번역 시 최대 30%까지 늘어나거나 줄어들 수 있다는 점을 허용하세요. 문자열이 다른 언어에서 얼마나 늘어나거나 줄어드는지 확인하려면 해당 문자열을 Google Translate에 붙여넣고 결과를 검토하세요. 해당 언어를 사용하는 동료에게 번역이 명확한지 확인을 요청하세요.

Markdown#

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

문서 웹사이트는 기본 Markdown 엔진인 Goldmark를 사용하는 Hugo 정적 사이트 생성기를 사용합니다.

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

Markdown의 HTML#

하드코딩된 HTML은 유효하지만, 몇 가지 이유로 권장하지 않습니다:

• 커스텀 마크업은 향후 사이트 전체 변경 또는 디자인 시스템 업데이트를 방해할 수 있습니다.

• 커스텀 마크업은 사이트 전체의 일관성을 보장하는 테스트 커버리지가 없습니다.

• 커스텀 마크업은 반응형이거나 접근성을 갖추지 못할 수 있습니다.

• 커스텀 마크업은 Pajamas 가이드라인을 따르지 않을 수 있습니다.

• Markdown의 HTML 및 CSS는 /help에서 렌더링되지 않습니다.

• HTML을 직접 코딩하면 오류가 발생하기 쉽습니다. 잘못된 HTML로 페이지 레이아웃이나 다른 컴포넌트가 깨질 수 있습니다.

다음의 경우 HTML을 사용할 수 있습니다:

• Markdown에 동등한 기능이 없는 경우.

• 콘텐츠가 기술 작가의 검토 및 승인을 받은 경우.

• 커스텀 요소가 긴급하게 필요하여 Technical Writing 엔지니어의 구현을 기다릴 수 없는 경우.

HTML <a> 태그로 생성된 링크는 href 속성에 절대 URL을 사용해야 합니다. 일반 링크와 달리 Markdown 파일에 상대 링크를 사용하지 마세요. Hugo는 Markdown 형식의 링크만 처리하고 변환할 수 있습니다.

문서 사이트에 유용한 새 요소에 대한 아이디어나 요청이 있다면 기능 요청을 제출하세요.

Markdown의 제목 레벨#

각 문서 페이지는 메타데이터에 title 속성을 포함해야 합니다. title은 HTML로 렌더링될 때 H1 요소가 됩니다. 각 페이지에 하나만 있을 수 있으므로 Markdown에 H1 제목을 추가하지 마세요.

• 각 하위 섹션에서 제목 레벨을 증가시키세요. 즉, 토픽 제목 앞에 # 문자 수를 늘리세요.

• H5 (#####)보다 높은 제목 레벨은 피하세요. 다섯 단계 이상의 제목 레벨이 필요하다면 토픽을 새 페이지로 이동하세요. H4보다 높은 제목 레벨은 오른쪽 사이드바 내비게이션에 표시되지 않습니다.

• 레벨을 건너뛰지 마세요. 예를 들어 ## > ####.

• 토픽 제목 앞뒤로 빈 줄을 하나씩 두세요.

• 토픽 제목에 코드를 사용하는 경우 코드를 백틱으로 감싸세요.

• 토픽 제목에 굵은 텍스트를 사용하지 마세요.

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.

단축 코드#

단축 코드(Shortcodes)는 템플릿 코드의 스니펫으로, 가용성 세부 정보나 탭과 같이 페이지에서 비표준 요소를 표시하기 위해 Markdown 콘텐츠에 포함할 수 있습니다.

GitLab 문서는 다음 단축 코드를 사용합니다:

• 가용성 세부 정보

• 접을 수 있는 패널

• 버전 히스토리

• 아이콘

• 탭

• 카드

• 유지 관리되는 버전

• 가이드

• 기능 테이블

예

• 아니요

• 용어 설명 툴팁

언어#

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

• 불필요한 단어를 피합니다.

• 명확하고 간결하게 작성하며, 주제의 목적에 집중합니다.

• 미국 영어 및 미국식 문법으로 작성합니다. (British.yml에서 검증됨.)

능동태#

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

예를 들어, 다음과 같이 작성합니다:

• The developer writes code for the application.

다음 대신에:

• Application code is written by the developer.

때로는 GitLab을 주어로 사용하면 어색할 수 있습니다. 예를 들어, GitLab exports the report처럼요. 이 경우에는 수동태를 사용합니다. 예를 들어, The report is exported처럼 작성합니다.

고객 관점#

GitLab이 만들어 낸 것에 초점을 맞추기보다, GitLab이 고객에게 제공하는 기능과 혜택에 집중합니다.

예를 들어, 다음과 같이 작성합니다:

• Use merge requests to compare code in the source and target branches.

다음 대신에:

• GitLab allows you to compare code.

• GitLab created the ability to let you compare code.

• Merge requests let you compare code.

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

신뢰 구축#

제품 문서는 영업 또는 마케팅 문구를 추가하지 않고, 명확하고 간결한 정보 제공에 집중해야 합니다.

• easily나 simply 같은 단어를 사용하지 마세요.

• “이 기능을 사용하면 시간과 비용을 절약할 수 있습니다.”와 같은 마케팅 문구를 사용하지 마세요.

대신, 사실과 달성 가능한 목표에 집중합니다. 구체적으로 작성하세요. 예를 들어:

• 이 기능을 사용하면 빌드 시간을 줄일 수 있습니다.

• 이 기능을 사용하여 프로젝트 생성 시 시간을 절약하세요. API가 파일을 생성하므로 수동으로 개입하지 않아도 됩니다.

자기 참조 서술#

문서 자체에 대해 서술하는 방식을 피합니다. 예를 들어, 다음과 같이 사용하지 마세요:

• This page shows…

• This guide explains…

이러한 표현은 사용자의 흐름을 방해합니다. 대신, 바로 본론으로 들어갑니다. 예를 들어, 다음 대신에:

• This page explains different types of pipelines.

다음과 같이 사용합니다:

• GitLab has different types of pipelines to help address your development needs.

SelfReferential.yml에서 검증됩니다.

대문자 표기#

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

주제 제목#

주제 제목에는 문장식 대문자 표기를 사용합니다. 예를 들어:

• # Use variables to configure pipelines

• ## Use the To-Do List

UI 텍스트#

버튼 라벨, 페이지, 탭, 메뉴 항목 등 특정 사용자 인터페이스 텍스트를 참조할 때는 사용자 인터페이스에 표시된 것과 동일한 대문자 표기를 사용합니다.

유일한 예외는 모두 대문자로 된 텍스트(예: RECENT FLOWS)입니다. 이 경우에는 문장식 대문자 표기를 사용합니다.

사용자 인터페이스 텍스트에 스타일 오류가 있다고 생각되면, 사용자 인터페이스 텍스트 변경을 제안하는 이슈 또는 머지 리퀘스트를 생성하세요.

기능 이름#

기능 이름은 소문자를 사용해야 합니다.

단, 드문 경우에는 기능 이름에 제목 표기법(Title Case)을 사용할 수 있습니다. 예외 사항은 다음과 같습니다:

• markdownlint에 고유명사로 추가되어, 모든 문서에 일관되게 적용할 수 있는 경우.

• 단어 목록에 추가된 경우.

해당 용어가 단어 목록에 없는 경우, GitLab 기술 작성자(Technical Writer)에게 조언을 구하세요. 기능 이름 지정 및 GitLab 표준 준수 여부 확인에 대한 도움은 핸드북을 참조하세요.

Features 페이지나 features.yml에 있는 용어나 문구의 대소문자 표기를 기본적으로 따르지 마세요.

Other terms#

다음 이름은 대문자로 시작합니다:

• GitLab 제품 티어. 예: GitLab Free 및 GitLab Ultimate.

• 서드파티 조직, 소프트웨어, 제품. 예: Prometheus, Kubernetes, Git, The Linux Foundation.

• 방법론 또는 방법. 예: Continuous Integration, Continuous Deployment, Scrum, Agile.

비표준 대소문자 스타일을 사용할 수 있는 해당 엔터티의 권위 있는 출처에 나열된 대소문자 표기 방식을 따르세요. 예: GitLab 및 npm.

Fake user information#

문서에 실제 사용자 이름이나 이메일 주소를 포함하지 마세요.

텍스트의 경우:

• Sidney Jones, Zhang Wei, Alex Garcia와 같이 다양하거나 성별 중립적인 이름을 일반적인 성과 함께 사용하세요.

• 가짜 이메일 주소는 example.com으로 끝나도록 하세요.

스크린샷의 경우:

스크린샷을 찍기 전에 페이지를 임시로 편집하세요:

변경하려는 텍스트를 마우스 오른쪽 버튼으로 클릭하세요.

• Inspect를 선택하세요.

• Elements 대화 상자에서 HTML을 편집하여 실제 사용자 정보가 포함된 텍스트를 예시 데이터로 교체하세요.

• 대화 상자를 닫으세요. 웹 페이지의 모든 사용자 데이터가 입력한 예시 데이터로 교체되어야 합니다.

• 스크린샷을 찍으세요.

또는 테스트 환경에서 예시 계정을 만들고 해당 환경에서 스크린샷을 찍으세요.

환경을 재현할 수 없는 경우, macOS의 Preview와 같은 이미지 편집 도구를 사용하여 사용자 데이터를 흐리게 처리하세요.

Fake URLs#

문서에 샘플 URL을 포함할 때는 다음을 사용하세요:

• 도메인 이름이 일반적인 경우 example.com.

• GitLab Self-Managed만 언급하는 경우 gitlab.example.com. GitLab.com에는 gitlab.com을 사용하세요.

Fake tokens#

문서에 실제 토큰을 사용하지 마세요.

다음 가짜 토큰을 예시로 사용하세요:

Contractions#

축약형 사용을 권장하며, 특히 튜토리얼, 지침 문서, 사용자 인터페이스에서 친근하고 비공식적인 어조를 만들 수 있습니다.

단, 다음과 같은 일부 축약형은 피해야 합니다:

Possessives#

GitLab과 같은 조직명이나 제품명 등 고유명사에는 소유격('s)을 사용하지 마세요.

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

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

Prepositions#

필요한 경우 문장 끝에 전치사를 사용하세요. 매달린(dangling) 또는 분리된(stranded) 전치사는 괜찮습니다. 예를 들면:

• You can leave the group you’re a member of.

• Share the credentials with users you want to give access to.

이러한 구문은 다음 대안보다 좀 더 일상적입니다:

• You can leave the group of which you’re a member.

• Share the credentials with users to which you want to give access.

약어#

약어를 사용할 경우, 페이지에서 처음 사용할 때 풀어서 표기하세요. 한 페이지에서 두 번 이상 풀어 쓰지 마세요.

• 제목: 특히 약어가 널리 사용되지 않는 경우, 주제 제목에서 약어 사용을 피하세요.

• 복수형: 약어를 복수형으로 만들지 않도록 하세요. 예를 들어 YAMLs 대신 YAML files를 사용하세요. 약어를 복수형으로 만들어야 할 경우, 아포스트로피를 사용하지 마세요. 예를 들어 API's 대신 APIs를 사용하세요.

• 소유격: 약어를 소유격으로 만들 때는 주의하세요. 가능하면, 약어를 소유격으로 만들지 않도록 문장을 작성하세요. 약어를 소유격으로 만들어야 할 경우, 단어를 풀어서 표기하는 것을 고려하세요.

숫자#

텍스트에서 숫자를 사용할 경우, 0부터 9까지는 문자로 표기하고 10 이상은 숫자로 표기하세요. 자세한 내용은 Microsoft Style Guide를 참조하세요.

UI에서의 숫자는 Pajamas를 참조하세요.

날짜와 시간#

날짜는 월 일, 연도 형식을 사용하고, 시간에는 AM과 PM을 사용하세요. 예를 들면:

January 3, 2026 at 10:30 AM

추가 세부 정보는 Microsoft Style Guide를 참조하세요.

UI에서의 날짜와 시간은 Pajamas를 참조하세요.

텍스트#

Markdown으로 작성하세요.

새 단락에는 빈 줄을 삽입하세요.

서로 다른 마크업 사이에 빈 줄을 삽입하세요(예: 모든 단락, 제목, 목록 이후). 예시:

## Heading

Paragraph.

- List item 1
- List item 2

줄 길이#

소스 콘텐츠를 읽기 쉽게 하고 diff를 비교하기 쉽게 하려면 다음 모범 사례를 따르세요.

• 긴 줄은 약 100자에서 분리하세요. (예외: 링크는 분리하지 마세요.)

• 새 문장은 새 줄에서 시작하세요.

주석#

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 앞에 쉼표(Oxford 쉼표)를 사용하세요. (OxfordComma.yml에서 테스트됩니다.)

콘텐츠 간격을 조정할 때:

• 문장 사이에는 공백 하나를 사용하세요. (공백을 두 개 이상 사용하는 경우 SentenceSpacing.yml에서 테스트됩니다.)

• 줄 바꿈 없는 공백을 사용하지 마세요. 대신 표준 공백을 사용하세요. (lint-doc.sh에서 테스트됩니다.)

• 들여쓰기에 탭을 사용하지 마세요. 대신 공백을 사용하세요. Tab 키를 누를 때 탭 대신 공백을 출력하도록 코드 편집기를 설정하는 것을 고려하세요.

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

• ; (세미콜론): 대신 두 개의 문장으로 나누세요.

• – (en 대시) 또는 — (em 대시): 대신 별도의 문장이나 쉼표를 사용하세요.

• " " ' ': 이중 또는 단일 타이포그래퍼’s (“곱슬”) 인용 부호. 대신 직선 따옴표를 사용하세요. (NonStandardQuotes.yml에서 테스트됩니다.)

자리 표시자 텍스트#

코드 블록에서 사용자가 자신의 값으로 대체해야 하는

특정 값을 사용합니다.

이 경우, 독자가 자신의 값으로 텍스트를 교체해야 하는 위치를 나타내기 위해 < 및 >를 사용하세요.

예를 들면:

cp <your_source_directory> <your_destination_directory>

플레이스홀더가 코드 블록 안에 없을 경우, <와 >를 사용하고 플레이스홀더를 단일 백틱으로 감싸세요. 예를 들면:

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

따옴표#

따옴표에 대한 Microsoft 가이드를 따르세요.

사용자 입력에는 따옴표 사용을 피하고, 대신 백틱을 사용하세요.

텍스트 서식#

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

• 굵게 — UI 요소 및 페이지에 사용.

• 인라인 코드 스타일 — 입력, 출력, 코드 등에 사용.

• 코드 블록 — 커맨드 라인 예시, 여러 줄의 입력, 출력, 코드 등에 사용.

• <kbd> — 키보드 명령에 사용.

굵게#

다음에 굵게를 사용하세요:

• 보이는 라벨이 있는 UI 요소. 라벨의 텍스트와 대소문자를 그대로 사용하세요.

• 탐색 경로.

키워드 강조나 일반 강조에는 굵게를 사용하지 마세요.

UI 요소에는 다음이 포함됩니다:

• 버튼

• 체크박스

• 설정

• 메뉴

• 페이지

• 탭

예를 들면:

• Cancel을 선택합니다.

• Issues 페이지에서…

• Pipelines 탭에서…

텍스트를 굵게 하려면 이중 별표(**)로 감싸세요. 예를 들면:

1. Select **Cancel**.

UI 요소에 굵게 서식을 사용할 때는 구두점을 굵은 태그 밖에 위치시키세요. 이 규칙은 마침표, 쉼표, 콜론, 오른쪽 꺾쇠 괄호(>)를 포함합니다.

구두점은 강조하는 UI 요소가 아닌 문장 구조의 일부입니다.

구두점이 UI 요소 자체의 일부인 경우에는 굵은 태그 안에 구두점을 포함하세요.

예를 들면:

• **Start a review**: This is a description of the button that starts a review.

• Select **Overview** > **Users**.

인라인 코드#

인라인 코드는 단일 백틱(```)으로 감싼 텍스트입니다. 예를 들면:

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>. 꺾쇠 괄호를 포함하세요.

예를 들면:

• Name 텍스트 상자에 test를 입력합니다.

• rules: CI/CD 키워드를 사용하여 파이프라인에 job을 추가할 시점을 제어하세요.

• DELETE 요청을 보내 러너를 삭제하세요. POST 요청을 보내 러너를 생성하세요.

• job 로그는 완료되면 Job succeeded를 표시합니다.

코드 블록#

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

코드 블록을 사용하는 경우:

• CLI 및 cURL 명령어.

• 인라인 코드에 담기에는 너무 큰 여러 줄 입력, 출력, 코드 샘플.

코드 블록을 추가하려면 텍스트 위아래에 백틱 세 개(`````)를 추가하고, 올바른 구문 강조를 위해 상단에 구문 이름을 지정하세요. 예:

```markdown
This is a code block that uses Markdown to demonstrate **bold** and `backticks`.

코드 블록 사용 시:

- 코드 블록 위아래에 빈 줄을 추가하세요.

- [지원되는 구문 이름](https://gohugo.io/content-management/syntax-highlighting/#languages) 중 하나를 사용하세요.
더 적합한 옵션이 없으면 `plaintext`를 사용하세요.

- 코드 블록 안에 백틱 세 개가 이미 포함된 다른(중첩된) 코드 블록이 있는 경우 백틱 네 개(``````)를 사용하세요. 위의 예시는 코드 블록 형식을 설명하기 위해 내부적으로 백틱 네 개를 사용합니다.

코드 블록에서 누락된 정보를 표현하려면 주석 또는 [줄임표](/19.1/development/documentation/styleguide/word_list/#ellipsis-ellipses)를 사용하세요. 예:

- `# Removed for readability`

- `// ...`

### 키보드 명령

키 입력에 대해 작성할 때:

- HTML `<kbd>` 태그를 사용하세요.

- 키 조합에서 `<kbd>` 태그 사이에 공백을 사용하지 마세요.

- `Alt`를 제외하고 키의 전체 이름을 표기하세요([Vale](/19.1/development/documentation/testing/vale/) 규칙: [`SubstitutionWarning.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/SubstitutionWarning.yml)).

- 키가 동작 키인 경우 첫 글자를 대문자로 표기하세요. 예: `Shift`, `Command`, `Delete`.

- 키가 문자인 경우 대문자를 사용하세요.

- 방향키에는 `↑`, `↓`, `←`, `→`를 사용하세요.

예:

  

To stop the command, press Control+C.

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

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

### 이탤릭체와 강조

제품 문서에서는 [강조를 위한 이탤릭체](/19.1/user/markdown/#emphasis) 사용을 피하세요.
대신, 강조가 필요 없을 만큼 명확한 콘텐츠를 작성하세요. GitLab과
[https://docs.gitlab.com](https://docs.gitlab.com)은 산세리프(sans-serif) 폰트를 사용하지만, 이탤릭체 텍스트는 [산세리프를 사용하는 페이지에서 눈에 띄지 않습니다](https://practicaltypography.com/bold-or-italic.html).

## 목록

목록을 사용하여 정보를 더 쉽게 훑어볼 수 있는 형식으로 제시하세요.

- 
목록의 모든 항목을 병렬 구조로 만드세요.
예를 들어, 일부 항목은 명사로 시작하고 다른 항목은 동사로 시작하지 않도록 하세요.

- 
모든 항목을 대문자로 시작하세요.

- 
모든 항목에 동일한 구두점을 사용하세요.

- 
항목이 완전한 문장이 아닌 경우 마침표를 사용하지 마세요.

- 
모든 완전한 문장 뒤에, 또는 목록 항목이 소개 문구와 결합하여 완전한 문장을 이룰 때 마침표를 사용하세요.
세미콜론이나 쉼표를 사용하지 마세요.

- 
소개 문구 뒤에 콜론(`:`)을 추가하세요.
예:

  

The basket contains these fruits:

• Bananas
• Apples

- 
목록에서 키워드나 개념을 정의하기 위해 [볼드](/19.1/development/documentation/styleguide/#bold) 서식을 사용하지 마세요. 볼드는 UI 요소 레이블에만 사용하세요. 예:

`**Start a review**: This is a description of the button that starts a review.`

- `Offline environments: This is a description of offline environments.`

키워드와 개념에 대해서는 대안 서식으로 [참조 토픽](/19.1/development/documentation/topic_types/reference/) 또는
[설명 목록](/19.1/development/documentation/styleguide/#description-lists-in-markdown)을 고려하세요.

- 

목록 항목을 사용하여 도입 문장을 완성하는 방식은 피하세요. 이 형식은 다른 문장 구조를 사용하는 언어로 현지화하기 어려울 수 있습니다.
예를 들어, 다음과 같이 사용하세요:

  

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.
2. Then, do the next step.
3. Finally, do the last step.

순서에 관계없이 완료할 수 있는 항목에는 순서 없는 목록을 사용하세요. 예를 들어:

  

These things are imported:

• Thing 1
• Thing 2
• Thing 3

### 목록 마크업

- 순서 없는 목록에는 별표(`*`) 대신 대시(`-`)를 사용하세요.

- 순서 있는 목록의 모든 항목은 `1.`로 시작하세요. 렌더링 시 목록 항목이 순서대로 표시됩니다.

- 목록 앞뒤에 빈 줄을 하나씩 남기세요.

- [중첩 하위 항목](/19.1/development/documentation/styleguide/#nesting-inside-a-list-item)을 나타내려면 탭 대신 공백으로 줄을 시작하세요.

### 목록 항목 내부 중첩

다음 항목들은 목록 항목 아래에 중첩할 수 있으며, 목록 항목과 동일한 들여쓰기로 렌더링됩니다:

- [코드 블록](/19.1/development/documentation/styleguide/#code-blocks)

- [인용 블록](/19.1/development/documentation/styleguide/#blockquotes)

- [알림 박스](/19.1/development/documentation/styleguide/#alert-boxes)

- [일러스트레이션](/19.1/development/documentation/styleguide/#illustrations)

- [탭](/19.1/development/documentation/styleguide/#tabs)

중첩 항목은 항상 목록 항목의 첫 번째 문자와 정렬되어야 합니다. 순서 없는 목록(`-` 사용)의 경우 들여쓰기 수준마다 공백 두 개를 사용하세요:

  

• 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

  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.
2. Ordered list item two.
   • Nested unordered list item one.
   • Nested unordered list item two.
3. Ordered list item three.

• Unordered list item one.
• Unordered list item two.
  1. Nested ordered list item one.
  2. Nested ordered list item two.
• Unordered list item three.

## Guide

`guide` 단축 코드를 사용하여 스타일이 적용된 단계별 순서 목록을 만들 수 있습니다.
guide 안에 다른 단축 코드(예: 알림)를 중첩할 수 있습니다.
단, 렌더링된 스타일링이 콘텐츠를 훑어보기 어렵게 만들 수 있으므로 이 방식은 되도록 자제하세요.

guide 안에 guide를 사용하지 마세요.

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

  

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

- 
      
Guide item with text.

An item with text only.- 
      
Guide item with alert.

An item with an alert.

    
    This is a note.

  
guide 스타일링은 GitLab 문서 사이트(`https://docs.gitlab.com`)에서만 렌더링됩니다.
GitLab 제품 도움말에서는 guide가 일반 순서 목록으로 표시됩니다.

튜토리얼에만 guide를 사용하세요. 대부분의 작업에는 순서 목록을 사용하세요.

## Tables

테이블은 복잡한 정보를 간결하게 설명하는 데 사용해야 합니다.
많은 경우, 각 항목에 대한 단일 설명이 있는 항목 목록을 설명하는 데는 순서 없는 목록으로 충분합니다.
그러나 행렬 형태로 나타내는 것이 가장 적합한 데이터가 있다면 테이블을 선택하는 것이 좋습니다.

### Creation guidelines

테이블의 접근성과 가독성을 유지하기 위해 빈 셀을 사용하지 마세요. [기능 테이블](/19.1/development/documentation/styleguide/#feature-tables)의 경우 단축 코드를 사용하여 기능 가용성을 표시하세요.
그 외에 셀에 적합한 값이 없는 경우 **None**을 사용하세요.

테이블을 더 쉽게 유지 관리하려면:

- 
테이블에 `Description` 칼럼이 있다면, 가능한 한 가장 오른쪽 칼럼으로 배치하세요.

- 
칼럼 너비를 일정하게 맞추기 위해 추가 공백을 넣으세요. 예시:

  

- 
매우 넓은 테이블의 경우 맨 오른쪽 칼럼에는 추가 공백을 생략하세요.
예시:

  

- 
테이블의 헤더(첫 번째) 행과 구분자(두 번째) 행의 길이는 동일해야 합니다.
`|-|-|-|` 또는 `|--|--|`와 같이 줄인 구분자 행을 사용하지 마세요.

- 
대형 테이블이 자동 서식으로 잘 맞지 않는 경우 자동 서식을 건너뛸 수 있지만, 다음 사항을 지켜야 합니다:

처음 두 행의 길이를 동일하게 만드세요.

- `|` 문자와 셀 내용 사이에 공백을 넣으세요.
예: `| Cell 1 | Cell 2 |`, `|Cell1|Cell2|`가 아닌 형태로 작성하세요.

### Options for large tables

[Hugo 클래스 속성](https://gohugo.io/content-management/markdown-attributes/)을 사용하여 테이블을 축소하거나 펼칠 수 있습니다.
테이블에 린팅 오류가 발생하지 않도록, 모든 규칙이 활성화된 상태에서 로컬로 테이블을 테스트하세요.

Hugo 클래스 속성은 GitLab 문서 사이트(`https://docs.gitlab.com`)에서만 렌더링됩니다.

#### Condensed tables

축소된(condensed) 테이블은 필요에 따라 수직 및 수평으로 스크롤이 가능하며, 높이가 제한됩니다.
기본적으로 페이지에 맞지 않는 넓은 테이블은 자동으로 축소됩니다. 긴 테이블은 축소되지 않습니다. 선택적으로
`condensed` 클래스 속성을 추가하여 테이블이 페이지에서 차지하는 공간을 줄일 수 있습니다.

  

또는

  

#### 확장 가능한 테이블

확장 가능한 테이블에는 **표 펼치기** 버튼이 있으며, 선택하면 대화 상자에서 테이블이 열립니다.
확장 가능한 테이블을 만들려면 `expandable` 클래스 속성을 사용하세요.

테이블을 압축형과 확장형 모두로 만들려면 두 속성을 함께 사용하세요. 예:

  

{.condensed .expandable}

또는:

  

{class="condensed expandable"}

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

모든 Markdown 파일에서 일관된 테이블 서식을 유지하려면, VS Code의 [Markdown Table Formatter](https://github.com/fcrespo82/vscode-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](https://packagecontrol.io/packages/Markdown%20Table%20Formatter)
플러그인을 사용해 볼 수 있지만, **Follow header row length** 설정은 지원하지 않습니다.

### 기존 테이블 업데이트

기존 테이블에서 행을 추가하거나 편집하면 일부 행이 더 이상 정렬되지 않을 수 있습니다.
일부 행만 변경하는 경우에는 테이블 전체를 다시 정렬하지 마세요.
너비를 고려하여 칼럼을 다시 정렬하면 테이블 전체가 수정된 것으로 표시되어 diff를 읽기 어려워집니다.

Markdown 테이블은 시간이 지나면서 자연스럽게 정렬이 어긋날 수 있지만,
`docs.gitlab.com`에서는 여전히 올바르게 렌더링됩니다. Technical Writing 팀은
다음 번에 해당 페이지를 리팩토링할 때 셀 정렬을 맞출 수 있습니다.

### 테이블 헤더

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

### 기능 테이블

기능 목록 테이블(예: [권한](/19.1/user/permissions/#project-permissions) 페이지에서
각 권한별로 사용 가능한 기능)을 만들 때는 다음 숏코드를 사용하세요:

  
| Option | Markdown | Renders | Notes |
| --- | --- | --- | --- |
| No | ❌ | No | Renders a hidden span for screen readers: no |
| Yes | ✅ | check-sm | Renders a visible checkmark icon and a hidden span for screen readers: yes |

이러한 숏코드는 API 문서나 인라인 텍스트에서 사용하지 마세요. API 문서에서는
[API 토픽 템플릿](/19.1/development/documentation/restful_api_styleguide/#api-topic-template)을 따르세요.

### 각주

테이블 내에 콘텐츠를 포함할 수 없는 경우에만 테이블 아래에 각주를 사용하세요.
예를 들어, 다음의 경우에 각주를 사용하세요:

- 여러 테이블 셀에 동일한 정보를 제공해야 할 때.

- 테이블 레이아웃을 방해할 수 있는 콘텐츠를 포함해야 할 때.

#### 각주 형식

테이블에서 각 각주에는 HTML 위첨자 태그 `<sup>`를 사용하세요.
태그는 문장 끝에 넣으세요. 문장과 태그 사이에 공백 한 칸을 두세요.

예:

  

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

테이블 아래 각주에는 `**각주**:` 다음에 순서 있는 목록을 사용합니다.

예시:

  

Footnotes:

1. This is the first footnote.
2. This is the second footnote.

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

  
| App name | Description |
| --- | --- |
| App A | Description text. 1 |
| App B | Description text. 2 |

**Footnotes**:

- This is the first footnote.

- This is the second footnote.

##### 각주가 5개 이상인 경우

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

  

Footnotes:

1. This is the first footnote.
2. This is the second footnote.
3. This is the third footnote.
4. This is the fourth footnote.
5. This is the fifth footnote.

## 링크

링크는 독자가 필요한 내용을 찾는 데 도움이 되는 중요한 수단입니다.

그러나 대부분의 콘텐츠는 검색을 통해 찾을 수 있으므로, 페이지에 링크를 너무 많이 추가하는 것은 피해야 합니다.
링크가 너무 많으면 가독성을 저하시킬 수 있습니다.

- 같은 페이지에서 링크를 중복 사용하지 않습니다. 예를 들어, **페이지 A**에서 **페이지 B**로 여러 번 링크하지 않습니다.

- 제목에 링크를 사용하지 않습니다. 링크가 포함된 제목은 오류를 발생시킵니다.

- 링크 내 단어 사이에 강제 줄 바꿈을 사용하지 않습니다.

- 단일 단락 내에서 여러 링크 사용을 피합니다.

- 단일 작업 내에서 여러 링크 사용을 피합니다.

- 한 페이지에서 다른 페이지로의 링크는 15개를 초과하지 않도록 합니다.

- 작업의 흐름을 방해하는 링크를 줄이기 위해 [관련 주제](/19.1/development/documentation/topic_types/#related-topics) 사용을 고려합니다.

- 같은 페이지 섹션으로의 앵커 링크는 가급적 사용하지 않습니다. 사용자가 오른쪽 내비게이션을 활용할 수 있도록 합니다.

### 인라인 링크

참조 링크 대신 인라인 링크를 사용합니다. 인라인 링크는 파싱하고
편집하기 더 쉽습니다.
([Vale](/19.1/development/documentation/testing/vale/) 규칙: [`ReferenceLinks.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_docs/ReferenceLinks.yml))

- 
권장:

  

For more information, see merge requests

- 
비권장:

  

For more information, see merge requests.

### 동일 리포지터리 내 링크

같은 리포지터리 내의 다른 문서(`.md`) 파일에 링크하려면:

- 상대 파일 경로를 사용한 인라인 링크를 사용합니다. 예: `[GitLab.com settings](../user/gitlab_com/_index.md)`.

- 링크가 매우 길더라도 전체 링크를 한 줄에 작성합니다. ([Vale](/19.1/development/documentation/testing/vale/) 규칙: [`MultiLineLinks.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/MultiLineLinks.yml)).

    
    GitLab 리포지터리에서 다른 디렉터리에서 `/development` 디렉터리로 링크하지 않습니다.

  개발 문서에서 특정 코드 파일로 링크하는 경우처럼 문서 파일 외부에 있는 파일에 링크하려면:

- 전체 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`이라는 앵커가 생성됩니다.

토픽 제목 텍스트를 변경하면 앵커 링크도 변경됩니다. 링크 깨짐을 방지하려면:

- 토픽 제목에 단계 번호를 사용하지 마세요.

- 가능하면 나중에 변경될 수 있는 단어는 사용하지 마세요.

#### 링크 및 제목 변경

토픽 제목을 변경하면 앵커 링크가 변경됩니다. 다른 문서 페이지나 코드 파일이 이 앵커에 링크되어 있으면 [파이프라인 job이 실패할 수 있습니다](/19.1/development/documentation/testing/).

변경 사항을 푸시하기 전에 [링크 검사를 로컬에서 실행](/19.1/development/documentation/testing/links/)하여 파이프라인 실패를 방지하는 것을 고려하세요.

### 링크 텍스트

링크 텍스트 작성 시 다음 가이드라인을 따르세요.

UI에서 링크 텍스트 작성에 대한 내용은 [Pajamas](https://design.gitlab.com/patterns/contextual-help#link-text)를 참고하세요.

#### 표준 텍스트

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

- `For more information, see [link text](link.md)`.

- `To [DO THIS THING], see [link text](link.md)`

예:

- `For more information, see [merge requests](link.md).`

- `To create a review app, see [review apps](link.md).`

이 텍스트를 확장하려면 다음과 같은 표현을 사용하세요:
`For more information about this feature, see...`

다음 구성은 사용하지 마세요:

- `Learn more about...`

- `To read more...`.

- `For more information, see the [Merge requests](link.md) page.`

- `For more information, see the [Merge requests](link.md) documentation.`

#### here 대신 설명적인 텍스트 사용

`here`나 `this page`와 같은 단어 대신 링크에 설명적인 텍스트를 사용하세요.
토픽이나 페이지 이름에는 소문자를 사용하세요.
텍스트를 토픽이나 페이지 이름과 정확히 일치시킬 필요는 없습니다.
텍스트를 설명적으로 편집하여 가이드라인에 맞게 작성하세요.

권장:

- `For more information, see [merge requests](link.md)`.

- `For more information, see [roles and permissions](link.md)`.

- `For more information, see [how to configure common settings](link.md)`.

비권장:

- `For more information, see [this page](link.md).`

- `For more information, go [here](link.md).`

- `For more information, see [this documentation](link.md).`

#### 이슈 링크

이슈에 링크할 때는 링크에 이슈 번호를 포함하세요. 예:

- `For more information, see [issue 12345](link.md).`

파운드 기호는 사용하지 마세요 (`issue #12345`).

#### API 링크

API 문서에 링크할 때는 소문자를 사용하세요. 예:

- `To import your GitHub repository, see the [import API](link.md).`

페이지 제목에 맞춰 첫 글자를 대문자로 쓰지 마세요. 예를 들어, 다음과 같이 사용하지 마세요:

- `To import your GitHub repository, see the [Import API](link.md).`

### 외부 문서 링크

가능하면 외부 문서 링크를 사용하지 마세요. 이러한 링크는 오래될 수 있으며 유지 관리가 어렵습니다.

- [링크 부패(link rot)를 유발합니다](https://en.wikipedia.org/wiki/Link_rot).

- [유지 관리 문제를 일으킵니다](https://gitlab.com/gitlab-org/gitlab/-/issues/368300).

때로는 링크가 필요한 경우도 있습니다. 트러블슈팅 단계를 명확히 하거나 콘텐츠 중복을 방지하는 데 도움이 될 수 있습니다.
더 정확하고 더 적극적으로 유지 관리될 수 있는 경우도 있습니다.

외부 링크를 추가할 때마다 유지 관리의 어려움과 사용자 이점을 비교하여 판단하세요.

### 핸드북 링크

핸드북 링크는 최소화하세요. 라이선스 조건, 데이터 사용 및 접근 정책,
테스트 계약, 이용 약관과 같이 불가피한 링크는 허용됩니다.

### 기밀 또는 제한된 접근 링크

다음 항목에는 직접 링크하지 마세요:

- [기밀 이슈](/19.1/user/project/issues/confidential_issues/).

- 내부 핸드북 페이지.

- [특별 권한](/19.1/user/permissions/)이 필요한 프로젝트 기능.

볼 수 있습니다.

다음과 같은 경우에는 이 링크가 실패합니다:

- 충분한 권한이 없는 사용자.

- 자동화된 링크 검사기.

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

- 링크가 기밀 이슈 또는 내부 핸드북 페이지를 가리키는 경우, 해당 이슈 또는 페이지가 GitLab 팀원만 볼 수 있다고 명시합니다.

- 링크에 특정 권한이 필요한 경우, 해당 정보를 명시합니다.

- 링크 검사기가 실패하지 않도록 링크를 백틱으로 감쌉니다.

예시:

- 

  

GitLab team members can view more information in this confidential issue: https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>

- 

  

GitLab team members can view more information in this internal handbook page: https://internal.gitlab.com/handbook/<link>

- 

  

Users with the Maintainer role for the project can use the pipeline editor: https://gitlab.com/gitlab-org/gitlab/-/ci/editor

### 특정 코드 줄에 링크하기

파일의 특정 줄에 링크할 때는 브랜치가 아닌 커밋에 링크합니다.
코드 줄은 시간이 지남에 따라 변경됩니다. 커밋 링크를 사용하여 줄에 링크하면
사용자가 참조한 줄로 정확히 이동합니다.
프로젝트에서 파일을 볼 때 표시되는 줄임표 메뉴의 **Permalink** 드롭다운 항목은
해당 파일의 가장 최근 커밋에 대한 링크를 제공합니다.

- 권장: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)`

- 비권장: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).`

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

## 네비게이션

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

- 항상 위치를 먼저, 그다음 동작을 작성합니다.

**Visibility** 드롭다운 목록(위치)에서 **Public**(동작)을 선택합니다.

- 간결하고 구체적으로 작성합니다. 예를 들면:

권장: **Save**를 선택합니다.

- 비권장: 변경 사항이 적용되도록 **Save**를 선택합니다.

- 단계에 이유를 포함해야 하는 경우, 단계를 이유로 시작합니다. 이렇게 하면 사용자가 더 빠르게 훑어볼 수 있습니다.

권장: 변경 사항을 보려면 머지 리퀘스트에서 링크를 선택합니다.

- 비권장: 변경 사항을 보려면 머지 리퀘스트에서 링크를 선택합니다.

### UI 요소 이름

GitLab UI에서는 다음 이름을 사용합니다:

[
  
](/19.1/development/documentation/styleguide/img/layout_external_names_v18_6.svg)

- **Top bar**

- **Left sidebar**: 사용자 인터페이스 왼쪽의 탐색 사이드바.

`the **Explore** menu` 또는 `the **Your work** sidebar`라는 표현은 사용하지 않습니다. 대신 `the left sidebar`를 사용합니다.

- **… panel**: 기본 컨텍스트에 따라 결정됩니다. 예를 들어, 컨텍스트가 머지 리퀘스트인 경우 **merge request panel**이라고 합니다.

- **Details panel**: 기본 컨텍스트를 지원합니다. 선택한 이슈 또는 에픽에만 해당됩니다.

- **GitLab Duo panel**

- **GitLab Duo sidebar**

**right sidebar**는 열려 있는 이슈, 머지 리퀘스트 또는 에픽에 특화된 사용자 인터페이스 오른쪽의 탐색 사이드바입니다.

**GitLab Duo**를 제외하고는 위의 모든 용어에 소문자를 사용합니다.

모든 UI 요소는 [**굵게** 표시해야 합니다](/19.1/development/documentation/styleguide/#bold). 탐색 경로의 `>`는 굵게 표시하지 않아야 합니다.

개별 UI 요소에 대한 추가 지침은 [단어 목록](/19.1/development/documentation/styleguide/word_list/)에 있습니다.

### 네비게이션 작업 단계 작성 방법

일관성을 유지하기 위해 작업 주제의 탐색 단계를 작성할 때 이 예시를 사용합니다.
기본값으로 고정된 항목을 포함하여 다른 단계가 있을 수 있지만,
대신 이 단계를 사용합니다.

프로젝트 설정을 열려면:

  

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

그룹 설정을 열려면:

  

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

최상위 그룹의 설정을 열려면:

  

1. In the top bar, select Search or go to and find your group. This group must be at the top level.
2. In the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

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

  

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand General pipelines.

프로젝트를 생성하려면:

  

1. In the upper-right corner, select Create new ( ) and New project/repository.

그룹을 생성하려면:

  

1. In the upper-right corner, select Create new ( ) and New group.

**Admin** 영역을 열려면:

  

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > CI/CD.

**Your work** 메뉴 항목을 열려면:

  

1. In the top bar, select Search or go to.
2. Select Your work.

아바타를 선택하려면:

  

1. In the upper-right corner, select your avatar.

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

  

1. Go to your issue.
2. In the right sidebar, in the Iteration section, select Edit.
3. From the dropdown list, select the iteration to associate this issue with.
4. Select any area outside the dropdown list.

모든 프로젝트를 보려면:

  

1. In the top bar, select Search or go to.
2. Select View all my projects.

모든 그룹을 보려면:

  

1. In the top bar, select Search or go to.
2. Select View all my groups.

### 선택적 단계

단계가 선택 사항인 경우, 해당 단계를 `Optional`이라는 단어로 시작하고 마침표를 붙입니다.

예시:

  

1. Optional. Enter a description for the job.

### 권장 단계

단계가 권장 사항인 경우, 해당 단계를 `Recommended`라는 단어로 시작하고 마침표를 붙입니다.

예시:

  

1. Recommended. Enter a description for the job.

### 키보드 단축키 및 명령어 문서화

두 가지 옵션이 모두 있는 경우, 키보드 명령어 대신 UI 지침을 작성합니다.
이 가이드라인은 GitLab과 VS Code 같은 서드파티 애플리케이션에도 적용됩니다.

GitLab의 키보드 명령어는 [GitLab 키보드 단축키](/19.1/user/shortcuts/)에 문서화되어 있습니다.

### 여러 필드를 한 번에 설명하기

섹션 내 필드를 UI 텍스트가 충분히 설명하는 경우, 모든 필드마다 작업 단계를 별도로 작성하지 않아도 됩니다.
대신 여러 필드를 하나의 작업 단계로 요약하세요.

**Complete the fields**라는 문구를 사용하세요.

예를 들어:

- 상단 바에서 **Search or go to**를 선택하고 프로젝트를 찾습니다.

- 왼쪽 사이드바에서 **Settings** > **Repository**를 선택합니다.

- **Push rules**를 펼칩니다.

- Complete the fields.

여러 필드를 설명할 때 한 필드만 설명이 필요하다면, 같은 단계에서 처리하세요:

- **Push rules**를 펼칩니다.

- Complete the fields. **Branch name**은 정규 표현식이어야 합니다.

여러 필드를 설명할 때는 순서 없는 목록 항목을 사용하세요:

- **General pipelines**를 펼칩니다.

- Complete the fields.

**Branch name**은 정규 표현식이어야 합니다.

- **User**는 최소 **Maintainer** 권한이 있는 사용자여야 합니다.

## 일러스트레이션

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

- 스크린샷: GitLab 사용자 인터페이스의 일부를 보여주는 데 사용합니다.

- 다이어그램: 엔티티 간의 프로세스나 관계를 설명하는 데 사용합니다.

일러스트레이션은 독자가 개념을 이해하거나, 복잡한 프로세스에서 현재 위치를 파악하거나,
애플리케이션과 상호작용하는 방법을 이해하는 데 도움이 될 수 있습니다. 다음과 같은 이유로 일러스트레이션은 꼭 필요한 경우에만 사용하세요:

- 시간이 지남에 따라 오래될 수 있습니다.

- 현지화하기 어렵고 비용이 많이 듭니다.

- 스크린 리더가 읽을 수 없습니다.

문서에 일러스트레이션을 반드시 사용해야 한다면, 다음 조건을 충족해야 합니다:

- 텍스트를 대체하는 것이 아니라 텍스트를 보완해야 합니다.
독자가 필요한 정보를 얻기 위해 일러스트레이션에만 의존하지 않아도 되어야 합니다.

- 앞의 텍스트에 소개 문장이 있어야 합니다.
예를 들어, `The following diagram illustrates the product analytics flow:`와 같은 문장입니다.

- 접근성을 갖추어야 합니다. 자세한 내용은 스크린샷 및 다이어그램 관련 지침을 참조하세요.

- 개인 식별 정보를 포함하지 않아야 합니다.

### 스크린샷

텍스트로 전달할 수 없는 관련 정보가 있는 경우, GitLab 사용자 인터페이스의 일부를 보여주기 위해 스크린샷을 사용하세요.

#### 스크린샷 캡처

스크린샷을 찍을 때:

- 스크린샷의 콘텐츠가
[GitLab SAFE 프레임워크](https://handbook.gitlab.com/handbook/legal/safe-framework/)를 준수하는지 확인하세요. 확인하려면
[SAFE 플로차트](https://handbook.gitlab.com/handbook/legal/safe-framework/#safe-flowchart)를 따르세요.

- **가치를 제공하는지 확인하세요.** `lorem ipsum` 텍스트를 사용하지 마세요.
실제 시나리오에서 기능을 사용하는 방식을 재현하고,
[현실적인 텍스트를 사용하세요](/19.1/development/documentation/styleguide/#fake-user-information).

- **관련 UI만 캡처하세요.** 불필요한 여백이나
요점을 설명하는 데 도움이 되지 않는 UI 영역은 포함하지 마세요. GitLab의
사이드바는 변경될 수 있으므로, 꼭 필요한 경우가 아니면
스크린샷에 포함하지 마세요.

- **작게 유지하세요.** 화면 전체 너비를 표시할 필요가 없다면 표시하지 마세요.
요소를 가깝게 유지하고 빈 공간을 줄이기 위해 브라우저 창 크기를 최대한 줄이세요. 스크린샷 크기를 최대한 작게 유지하세요.

- **페이지에서 이미지가 어떻게 렌더링되는지 검토하세요.** 이미지를 로컬에서 미리 보거나 머지 리퀘스트의
리뷰 앱을 사용하세요. 이미지가 흐릿하거나 지나치게 크지 않은지 확인하세요.

- **일관성을 유지하세요.** 일관된 읽기 환경을 위해 문서 페이지에 이미 있는 다른 스크린샷과 조율하세요. 내비게이션 테마가 기본 설정인 **Neutral**로 설정되어 있고 구문 강조 테마도 기본 설정인 **Light**로 설정되어 있는지 확인하세요.

#### 콜아웃 추가

스크린샷에서 특정 영역을 강조하려면 화살표를 사용하세요.

- 색상은 `#EE2604`를 사용하세요. macOS의 Preview 애플리케이션을 사용하는 경우, 이것이 기본 빨간색입니다.

- 선 너비는 3pt를 사용하세요. macOS의 Preview 애플리케이션을 사용하는 경우, 목록의 세 번째 선입니다.

- 다음 이미지에 표시된 화살표 스타일을 사용하세요.

- 여러 화살표가 있는 경우 가능하면 평행하게 만드세요.

[
  
](/19.1/development/documentation/styleguide/img/callouts_v18_3.png)

#### 이미지 요구사항

- 넓거나 높은 스크린샷은 크기를 조정하세요.

너비는 1000픽셀 이하여야 합니다.

- 높이는 500픽셀 이하여야 합니다.

- 스크린샷이 크기 조정 및 압축 후에도 선명한지 확인하세요.

- JPEG 대신 PNG 이미지를 사용하세요.

- 모든 이미지는 반드시 100 KB 이하로 [압축](/19.1/development/documentation/styleguide/#compress-images)해야 합니다.
대부분의 경우 이미지 품질을 낮추지 않고도 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/`라는 별도 디렉터리에 이미지를 배치하세요.

외부에서 호스팅되는 이미지에 링크하지 마세요. 복사본을 다운로드하여 docs 디렉터리 내의 적절한 `img` 디렉터리에 저장하세요.

- [https://ezgif.com/optimize](https://ezgif.com/optimize) 또는 유사한 도구로 GIF를 압축하세요.

문서를 설명하기 위해 [동영상](/19.1/development/documentation/styleguide/#videos)을 링크하고 삽입하는 방법도 참조하세요.

#### 이미지 압축

문서에 추가하는 새 이미지를 압축하세요.
이는 파일 크기를 줄이고 페이지 로딩 성능을 향상시키는 데 도움이 됩니다.

크로스 플랫폼 오픈 소스 도구인 [`pngquant`](https://pngquant.org/)를 사용할 수 있습니다.
공식 웹사이트를 방문하여 OS에 맞는 지침에 따라 설치하세요.

이미지를 자동 또는 수동으로 압축할 수 있습니다:

- macOS에서 자동 압축은
[스크린샷을 80% 작게 만드는 간단한 방법](https://about.gitlab.com/blog/simple-trick-for-smaller-screenshots/)을 참조하세요.

- 수동 압축은 [`pngquant` 스크립트](https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/pngquant)를 사용하세요.

`pngquant` 스크립트를 사용하려면 `https://gitlab.com/gitlab-org/gitlab` 로컬 복사본의 루트 디렉터리에서
필요에 따라 다음 명령어를 실행하세요:

- 
모든 문서 PNG 이미지가 압축되었는지 확인하려면:

  

bin/pngquant lint

- 
모든 문서 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

##### 이미지 파일을 PNG 형식으로 변환

압축 스크립트가 제자리에서 압축하지 않고 `.compressed` 파일을 생성하는 경우,
해당 파일은 PNG 확장자를 가지고 있지만 실제로는 다른 이미지 형식(예: JPEG)일 가능성이 높습니다.

`png_quantizator` gem은 PNG가 아닌 파일에서 충돌이 발생하여 스크립트가 완료되지 않습니다.

사전 요구 사항:

- 
GraphicsMagick을 설치하세요:

  

macOS:#

brew install graphicsmagick

이미지 파일을 PNG 형식으로 변환하려면:

- 
파일 형식을 확인하세요:

  

file doc/user/img/problematic_file.png

`file` 명령은 확장자가 아닌 파일 내용(매직 바이트/헤더)을 검사합니다. 잘못 명명된 JPEG 파일은 다음과 같이 표시됩니다:

  

doc/user/img/problematic_file.png: JPEG image data, JFIF standard 1.01...

- 
GraphicsMagick을 사용하여 파일을 PNG 형식으로 변환하세요:

  

gm convert problematic_file.png corrected_file.png

- 
압축 스크립트를 다시 실행하세요.

원본이 JPEG 파일이었다면, 변환된 PNG 파일이 더 크게 보일 수 있습니다.
PNG는 무손실 압축을 사용하는 반면 JPEG는 손실 압축을 사용하기 때문입니다.

##### 이미지 삭제

영어 문서에서 이미지 참조를 제거할 때 이미지 파일을 삭제하지 마세요.
현지화된 문서(예: 일본어 페이지)는 영어 문서와 동일한 이미지 파일을 사용합니다.
이미지가 영어 문서에서 더 이상 참조되지 않더라도, 번역된 페이지에서 여전히 사용 중일 수 있습니다.

문서 사이트 빌드 프로세스는 이미지 경로를 확인합니다. 아직 사용 중인 이미지를 삭제하면,
머지 리퀘스트 파이프라인의 `hugo_build` job이 실패합니다.

어디에도 사용되지 않는 이미지는 [월간 유지보수](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks)의 일환으로 정리됩니다.

#### 애니메이션 이미지

애니메이션 이미지(예: 애니메이션 GIF)는 사용하지 마세요. 사용자에게 산만하고
불편함을 줄 수 있습니다.

사용자 인터페이스에서 복잡한 상호작용을 설명하면서 독자가 이해할 수 있도록
시각적 표현을 포함하고 싶다면 다음과 같이 할 수 있습니다:

- 정적 이미지(스크린샷)를 사용하고, 필요한 경우 화면의 특정 영역을 강조하는 설명선을 추가하세요.

- 상호작용에 대한 짧은 동영상을 만들어 링크로 연결하세요.

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

문서에 이미지를 포함하기 위한 Markdown 코드는 다음과 같습니다:
`![Image description, used for alt tag](img/document_image_title_vX_Y.png)`

#### 대체 텍스트

대체 텍스트(alt text)는 접근성 있는 경험을 제공합니다.
스크린 리더는 대체 텍스트를 사용하여 이미지를 설명하며, 이미지 다운로드에 실패할 경우
대체 텍스트가 표시됩니다.

대체 텍스트는 이미지의 콘텐츠가 아닌 이미지의 맥락을 설명해야 합니다. 페이지나 섹션의
주제와 관련된 맥락을 추가하세요. 이미지를 볼 수 없는 상태에서 누군가가 페이지를 읽고
상호작용하도록 돕는다면 이미지에 대해 어떻게 설명할지 생각해보세요.

권장 예시:

`![A runner sending a request to the Docker API.](img/document_image_title_vX_Y.png)`

비권장 예시:

`![Runner and Docker architecture](img/document_image_title_vX_Y.png)`

대체 텍스트를 작성할 때:

- 155자 이하의 짧고 설명적인 대체 텍스트를 작성하세요.
스크린 리더는 일반적으로 이 글자 수 이후에는 읽기를 중단합니다.

- 이미지에 워크플로 다이어그램과 같은 복잡한 정보가 포함된 경우, 짧은 대체 텍스트로
이미지를 식별하고 본문에 자세한 정보를 포함하세요.

- 문장이든 아니든 문자열 끝에 마침표를 사용하세요.

- 문장 대소문자를 사용하고 모두 대문자는 피하세요.
일부 스크린 리더는 대문자를 개별 글자로 읽습니다.

- **Image of** 또는 **Graphic of**와 같은 표현을 사용하지 마세요.

- 키워드 나열을 사용하지 마세요.
본문에 키워드를 포함하여 맥락을 보완하세요.

- 이미지는 대체 텍스트가 아닌 주제 본문에서 소개하세요.

- 주제에서 이미 사용한 텍스트를 반복하지 않도록 노력하세요.

- 굵게, 이탤릭체, 백틱과 같은 인라인 스타일을 사용하지 마세요.
스크린 리더는 `**text**`를 `star star text star star`로 읽습니다.

- 이미지가 페이지에 고유한 정보를 추가하지 않는 경우(예: 이미지가 장식용이거나 본문 텍스트나 캡션에 이미 충분히 설명된 경우), 태그를 완전히 생략하는 대신 빈 대체 텍스트 태그(`alt=""`)를 사용하세요. 빈 alt 태그는 보조 기술에 텍스트를 의도적으로 생략했음을 알려주는 반면, 누락된 alt 태그는 의미가 모호합니다.

#### 자동 스크린샷 생성기

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

- [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md)를 설정하세요.

- 클론된 GitLab 리포지터리가 있는 하위 디렉터리(일반적으로 `gdk/gitlab`)로 이동하세요.

- GDK 데이터베이스가 완전히 마이그레이션되었는지 확인하세요: `bin/rake db:migrate RAILS_ENV=development`.

- `pngquant`를 설치하세요. 자세한 내용은 도구 웹사이트를 참조하세요: [`pngquant`](https://pngquant.org/)

- `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 # Helper that enables the screenshots taking mechanism

before do page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page end

- 
각 `it` 블록에 스크린샷이 저장되는 경로를 추가합니다:

  

it '<path/to/images/directory>'

`visit <path>`를 사용하여 페이지 스크린샷을 찍을 수 있습니다.
빈 스크린샷을 방지하려면 `expect`를 사용하여 콘텐츠가 로드될 때까지 기다립니다.

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

- 
스크린샷 생성기 파일에 다음을 추가합니다:

  

screenshot_area = find('') # Find the element scroll_to screenshot_area # Scroll to the element expect(screenshot_area).to have_content '' # Wait for the content you want to capture set_crop_data(screenshot_area, ) # Capture the element with added padding

`spec/docs_screenshots/container_registry_docs.rb`를 참고하여 직접 스크립트를 작성하세요.

### 다이어그램

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

다이어그램을 생성하려면 다음 중 하나를 사용합니다:

- [Mermaid](https://mermaid.js.org/#/) (권장). 문서에서는 Mermaid 버전 11을 지원합니다.

- [Draw.io](https://draw.io).

Mermaid는 권장하는 다이어그램 도구이지만, 모든 상황에 적합한 것은 아닙니다. 예를 들어,
복잡한 다이어그램 요구 사항은 이해하기 어려운 레이아웃을 초래할 수 있습니다.

GUI 다이어그램 도구는 작성자가 Mermaid’s의 복잡성과 레이아웃 문제를 극복하는 데 도움을 줄 수 있습니다. Draw.io는
편집기를 사용할 때 다이어그램과 그 정의가 모두 SVG 파일에 저장되어 편집이 가능하므로
선호하는 GUI 도구입니다. Draw.io는 GitLab 위키와도 통합되어 있습니다.

  
| 기능 | Mermaid | Draw.io |
| --- | --- | --- |
| 편집기 필요 여부 | 텍스트 편집기 | Draw.io 편집기 |
| WYSIWYG 편집 | dash-circle  No | check-circle-filled  Yes |
| grep으로 텍스트 콘텐츠 검색 가능 여부 | check-circle-filled  Yes | dash-circle  No |
| 외관 제어 주체 | 웹사이트의 CSS | 다이어그램 작성자 |
| 파일 형식 | SVG | SVG |
| VS Code 통합 (확장 사용 시) | check-circle-filled  Yes (미리 보기 및 로컬 편집) | check-circle-filled  Yes (미리 보기 및 로컬 편집) |
| 동적 생성 여부 | check-circle-filled  Yes | dash-circle  No |

#### 다이어그램 가이드라인

접근 가능하고 유지 관리가 용이한 다이어그램을 만들려면 다음 가이드라인을 따르세요:

- 
다이어그램을 간결하고 집중되게 유지하세요. 필수 요소와 정보만 포함합니다.

- 
요소를 구분하기 위해 도형만 사용하세요. 다이어그램은 라이트 모드와 다크 모드 모두와 호환되어야 하므로
색상으로 요소를 구분하지 마세요.

권장 도형은 다음과 같습니다:

프로세스나 단계에는 직사각형.

- 결정 지점에는 마름모.

- 요소 간 직접적인 관계에는 실선.

- 요소 간 간접적인 관계에는 점선.

- 프로세스의 흐름이나 방향에는 화살표.

- 
동일한 요소를 나타내는 도형은 같은 모양과 크기여야 합니다.

- 
다이어그램 요소에 명확한 라벨과 간략한 설명을 추가하세요.

- 
텍스트가 있는 요소의 경우, 텍스트와 도형’s의 윤곽선 사이에 적절한 여백이 있는지 확인하세요. 필요한 경우, 해당 도형과 다이어그램 내 **모든** 유사한 도형의 크기를 늘리세요.

- 
다이어그램에 제목과 간략한 설명을 포함하세요.

- 
텍스트에는 GitLab Sans 폰트를 사용하거나, 대체 옵션으로 Google Inter 폰트를 사용하세요.

- 
복잡한 프로세스의 경우, 하나의 큰 다이어그램 대신 여러 개의 단순한 다이어그램을 만드는 것을 고려하세요.

- 
다이어그램이 다양한 기기와 화면 크기에서 잘 표시되는지 확인하세요.

- 
링크를 포함하지 마세요. [`click` 액션](https://mermaid.js.org/syntax/classDiagram.html#interaction)으로 다이어그램에 삽입된 링크는 링크 검사 도구로 테스트할 수 없습니다.

- 
프로세스가 변경될 때 정확성을 유지하기 위해 문서 또는 코드와 함께 다이어그램도 업데이트하세요.

#### Mermaid로 다이어그램 만들기

[Mermaid 구문](https://mermaid.js.org/intro/syntax-reference.html)을 사용하여 다이어그램을 만드는 방법은
[Mermaid 사용자 가이드](https://mermaid.js.org/intro/getting-started.html)와
Mermaid 사이트의 예제를 참고하세요.

GitLab 문서용 Mermaid 다이어그램을 만들려면:

- 
[Mermaid Live Editor](https://mermaid.live/)에서 다이어그램을 만드세요.

- 
**Code** 창의 콘텐츠를 복사하여 `mermaid` 코드 블록으로 감싸 Markdown 파일에 붙여넣습니다. 자세한 내용은

자세한 내용은 [Mermaid용 GitLab Flavored Markdown](/19.1/user/markdown/#mermaid)을 참조하세요.

- 
다이어그램 유형(예: `flowchart` 또는 `sequenceDiagram`)을 선언한 다음 줄에,
접근성을 위해 다음 줄을 추가하세요:

  

accTitle: your diagram title here accDescr: describe what your diagram does in a single sentence, with no line breaks.

제목과 설명이 [대체 텍스트 지침](/19.1/development/documentation/styleguide/#alternative-text)을 따르는지 확인하세요.

예를 들어, 다음 플로우차트에는 접근성 정보가 포함되어 있습니다:

  

flowchart TD
    accTitle: Example diagram title
    accDescr: A description of your diagram
A[Start here] --&gt;|action| B[next step]</code></pre></details></div>


#### Draw.io로 다이어그램 만들기

[Draw.io](https://draw.io) 웹 애플리케이션 또는 (비공식)
VS Code [Draw.io Integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio)
확장 프로그램을 사용하여 다이어그램을 만드세요. 두 도구 모두 동일한 다이어그램 편집 환경을 제공하지만, 웹
애플리케이션에서는 편집 가능한 예제 다이어그램을 제공합니다.

Draw.io를 사용하여 만든 다이어그램은 일반
[다이어그램 지침](/19.1/development/documentation/styleguide/#diagram-guidelines) 및 Draw.io 전용 지침을 준수해야 합니다.

##### Draw.io 지침

Draw.io에서 다이어그램을 만들 때, Mermaid로 만드는 다이어그램과 시각적으로 일관성이 있어야 합니다. 다음 규칙은 일반
[다이어그램 지침](/19.1/development/documentation/styleguide/#diagram-guidelines)에 추가되는 내용입니다.

글꼴:

- 모든 텍스트에 Inter 글꼴을 사용하세요. 이 글꼴은 기본 글꼴에 포함되어 있지 않습니다.
Inter 글꼴을 커스텀 글꼴로 추가하려면:

글꼴 드롭다운 목록에서 **Custom**을 선택하세요.

- **Google fonts**를 선택하고, **Font name** 텍스트 상자에 `Inter`를 입력하세요.

도형:

- 요소에는 사각형 도형을 사용하세요.

- 플로우차트에는 **Flowchart** 도형 컬렉션의 도형을 사용하세요.

##### 웹 애플리케이션 사용

Draw.io 웹 애플리케이션을 사용하여 다이어그램을 만들려면:

- [Draw.io](https://draw.io) 웹 애플리케이션에서 다이어그램을 만드세요.

- 다이어그램을 저장하세요:

Draw.io 웹 애플리케이션에서 **File** > **Export as** > **SVG**를 선택하세요.

- **Include a copy of my diagram: All pages** 체크박스를 선택한 다음 **Export**를 선택하세요.
Draw.io에서 편집할 수 있음을 나타내기 위해 파일 확장자로 `drawio.svg`를 사용하세요.

- [SVG를 이미지로 문서에 추가하세요](/19.1/development/documentation/styleguide/#add-the-image-link-to-content).
이러한 SVG는 다른 비-SVG 이미지와 동일한 Markdown을 사용합니다.

##### VS Code 확장 프로그램 사용

VS Code용 Draw.io Integration 확장 프로그램을 사용하여 다이어그램을 만들려면:

- 
다이어그램이 포함될 디렉터리에 `drawio.svg` 접미사를 가진 빈 파일을 만드세요.

- 
VS Code에서 파일을 열고 다이어그램을 만드세요.

- 
파일을 저장하세요.

다이어그램의 정의는 SVG 파일에 Draw.io 호환 형식으로 저장됩니다.

- 
[SVG를 이미지로 문서에 추가하세요](/19.1/development/documentation/styleguide/#add-the-image-link-to-content).
이러한 SVG는 다른 비-SVG 이미지와 동일한 Markdown을 사용합니다.

## Emoji

Markdown emoji 형식(예: `:smile:`)은 어떤 목적으로도 사용하지 마세요.
대신 [GitLab SVG 아이콘](/19.1/development/documentation/styleguide/#gitlab-svg-icons)을 사용하세요.

## GitLab SVG icons

[GitLab SVG 라이브러리](https://design.gitlab.com/svgs/)의 아이콘을
문서에 직접 사용할 수 있습니다. 예를 들어, `[tanuki]`는 다음과 같이 렌더링됩니다: tanuki .

대부분의 경우, 텍스트 내에서 아이콘 사용을 지양하세요.
단, 호버 텍스트가 UI 요소를 설명하는 유일한
방법인 경우에는 아이콘을 사용하세요. 예를 들어, **Delete** 또는 **Edit** 버튼은
호버 텍스트만 있는 경우가 많습니다.

아이콘을 사용할 때는 호버 텍스트로 시작하고, 그 뒤에 괄호 안에 SVG 참조를 붙이세요.

- 지양: `Select ✏️ **Edit**.` 렌더링 결과: Select  pencil  **Edit**.

- 대신 사용: `Select **Edit** (✏️).` 렌더링 결과: Select **Edit** ( pencil ).

아이콘을 설명하는 단어를 사용하지 마세요:

- 지양: `Select **Erase job log** (the trash icon).`

- 대신 사용: `Select **Erase job log** ([remove]).` 렌더링 결과: Select **Erase job log** ( remove ).

버튼에 호버 텍스트가 없는 경우 아이콘을 설명하세요.
접근성 개선을 위해 버튼에 호버 텍스트를 추가하는
[UX 버그 이슈](https://gitlab.com/gitlab-org/gitlab/-/issues/new?description_template=Bug)를
생성하여 후속 조치를 취하세요.

- 피하기: `Select ⋮.`

- 대신 사용: `Select the vertical ellipsis (⋮).` 이렇게 렌더링됩니다: 세로 줄임표( ellipsis_v )를 선택하세요.

## 동영상

GitLab YouTube 동영상 튜토리얼을 문서에 추가하는 것을 적극 권장합니다.
단, 동영상이 오래된 경우는 예외입니다. 동영상은 문서를 대체하는 것이 아니라
문서를 보완하거나 설명하는 역할을 해야 합니다. 기능과 주요 사용 사례에 필수적인 내용이
동영상에 있지만 문서에 충분히 다루어지지 않은 경우 다음을 수행해야 합니다:

- 해당 내용을 문서 텍스트에 추가합니다.

- 동영상을 검토하고 페이지를 업데이트하는 이슈를 생성합니다.

제품 리포지터리에 동영상을 업로드하지 마세요. 대신 [링크를 추가하거나](/19.1/development/documentation/styleguide/#link-to-video)
[임베드](/19.1/development/documentation/styleguide/#embed-videos)하세요.

### 동영상 링크 추가

동영상에 링크를 추가할 때는 독자가 페이지를 읽기 전에 동영상을 쉽게 찾을 수 있도록
YouTube 아이콘을 포함하세요. 링크 텍스트에 대해서는 [일반 가이드라인](/19.1/development/documentation/styleguide/#text-for-links)을 따르세요.
오래된 동영상을 식별하는 데 도움이 되도록 링크 뒤에 동영상의 게시 날짜를 포함하세요.

  


For an overview, see merge requests.


GitLab 사용자에게 유용한 최신 동영상이라면 어떤 것이든 링크할 수 있습니다.

### 동영상 임베드

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

[GitLab 공식 YouTube 채널](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)의 동영상만 임베드할 수 있습니다.
다른 출처의 동영상은 대신 [링크로 연결](/19.1/development/documentation/styleguide/#link-to-video)하세요.

대부분의 경우 [동영상 링크 추가](/19.1/development/documentation/styleguide/#link-to-video)를 사용하세요.
임베드된 동영상은 페이지에서 많은 공간을 차지하고 독자의 주의를 분산시킬 수 있습니다.

동영상을 임베드하려면:

- 이 절차의 코드를 복사하여 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` 필드 내용을 교체하여 붙여넣으세요.

- 오래된 동영상을 식별하는 데 도움이 되도록 링크 아래에 동영상의 게시 날짜를 포함하세요.

  

leave a blank line here

  See the video: Video title.


  


leave a blank line here
```
GitLab 문서 사이트에서는 다음과 같이 렌더링됩니다:
동영상 보기: GitLab이란 무엇인가.
이 형식을 사용하면:


figure 태그는 시맨틱 SEO에 필수이며, video-container
클래스는 동영상이 반응형으로 동작하고 다양한 모바일 기기에서 표시되도록 하는 데 필요합니다.


<div class="video-fallback">은 /help에 필요한 폴백으로,
GitLab Markdown 프로세서가 iframe을 지원하지 않기 때문입니다. 문서 사이트에서는 숨겨져 있지만
/help에서는 표시됩니다.


www.youtube-nocookie.com 도메인은 YouTube 임베드 플레이어의
개인정보 보호 강화 모드를
활성화합니다. 이 모드를 통해 쿠키 설정이 제한된 사용자도 임베드된 동영상을 볼 수 있습니다.


클릭스루 데모 링크 추가#
클릭스루 데모 링크 추가는 동영상과 유사한 가이드라인을 따라야 합니다.
For a click-through demo, see [Demo Title](https://link-to-demo).
<!-- Demo published on YYYY-MM-DD -->

알림 박스#
알림 박스를 사용하여 정보에 주의를 집중시키세요. 드물게 사용하고, 알림 박스가 바로 다른 알림 박스 다음에 오지 않도록 하세요.
알림 박스는 Markdown 알림을 사용하여 생성됩니다:
<div class="admonition note"><div class="admonition-title">Note</div>

The text inside the alert box goes here.

</div>```

유효한 알림 유형은 `flag`, `note`, `warning`, `disclaimer`입니다. 알림 유형은 대소문자를 구분하지 않습니다.

### Flag

이 알림 유형은 기능의 가용성을 설명할 때 사용합니다. `flag` 알림 형식 지정 방법에 대한 자세한 내용은 [기능 플래그 뒤에 배포된 기능 문서화](/19.1/development/documentation/feature_flags/)를 참조하세요.

### Note

노트는 꼭 필요한 경우에만 사용하세요. 노트가 너무 많으면 주제를 파악하기 어려워집니다.

노트를 추가하는 대신 다음 방법을 고려하세요:

- 문장을 단락의 일부로 다시 작성한다.

- 정보를 별도의 단락으로 배치한다.

- 새 주제 제목 아래에 내용을 배치한다.

노트를 반드시 사용해야 한다면 다음 형식을 사용하세요:

  

Note
This is something to note.
```
GitLab 문서 사이트에서 다음과 같이 렌더링됩니다:
This is something to note.

Warning#
경고는 더 이상 사용되지 않는 기능을 나타내거나, 데이터 손실 가능성이 있는 절차에 대한 경고를 제공할 때 사용합니다.
<div class="admonition warning"><div class="admonition-title">Warning</div>

This is something to be warned about.

</div>```

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

    
    This is something to be warned about.

  
### Disclaimer

아직 제공되지 않은 기능에 대해 **반드시** 작성해야 하는 경우, 해당 내용 근처에 미래 지향적 진술에 관한 disclaimer를 추가하세요.

Disclaimer 알림은 [템플릿](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/themes/gitlab-docs/layouts/shortcodes/alert.html)을 통해 생성되며, 다른 텍스트를 포함해서는 안 됩니다.

다음과 같이 disclaimer를 추가하세요:

  

Disclaimer
이 페이지에는 개발 중인 제품, 기능에 대한 정보가 포함되어 있습니다. 이 정보는 참고 목적으로만 제공되며, 구매 또는 계획 시 이 정보에 의존하지 마십시오.


GitLab 문서 사이트에서 disclaimer 텍스트와 함께 다음과 같이 렌더링됩니다:

    
    This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
  페이지의 모든 콘텐츠가 아직 제공되지 않은 경우, 미래 지향적 진술에 관한 disclaimer를 페이지 상단에 한 번만 사용하세요.

주제의 콘텐츠가 아직 준비되지 않은 경우, 해당 주제에 disclaimer를 사용하세요.

자세한 내용은 [향후 버전에서 기능 약속하기](/19.1/development/documentation/styleguide/#promising-features-in-future-versions)를 참조하세요.

## Blockquotes

제품 문서에서는 [블록 인용문](/19.1/user/markdown/#blockquotes) 사용을 피하세요.
블록 인용문은 텍스트를 파악하기 어렵게 만들 수 있습니다. 블록 인용문 대신 다음을 고려하세요:

- [코드 블록](/19.1/development/documentation/styleguide/#code-blocks).

- [알림 박스](/19.1/development/documentation/styleguide/#alert-boxes).

- 특별한 스타일링 없이 사용.

[GitLab Flavored Markdown(GLFM)](/19.1/user/markdown/) 페이지는 일반 텍스트와 렌더링된 예시를 구별하기 위해 블록 인용문을 사용하는 드문 사례입니다. 그러나 대부분의 경우에는 사용을 피해야 합니다.

## Tabs

문서 사이트에서는 텍스트를 탭으로 표시하도록 형식을 지정할 수 있습니다.

    
    탭 안에 버전 히스토리 불릿, 주제 제목, HTML, 또는 탭을 넣지 마세요. 단락, 목록,
알림 박스, 코드 블록만 사용하세요. 다른 스타일은 올바르게 렌더링되지 않을 수 있습니다. 확실하지 않을 때는 단순하게 유지하세요.

  탭 세트를 생성하려면 다음 예시를 참고하세요:

  

Tab oneTab two

Here's some content in tab one.


Here's some other content in tab two.



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

  Tab one
  
    
    
    
    Here&rsquo;s some content in tab one.

  Tab two
  
    
    
    
    Here&rsquo;s some other content in tab two.

탭 제목은 간결하고 일관성 있게 작성하세요. 병렬 구조를 유지하고, 각 제목의 첫 글자는 대문자로 시작해야 합니다.
예를 들면:

- `Linux package (Omnibus)`, `Helm chart (Kubernetes)` (설정 편집을 문서화할 때는
[설정 편집 가이드](/19.1/development/documentation/styleguide/#how-to-document-different-installation-methods)를 따르세요)

- `15.1 and earlier`, `15.2 and later`

탭에 대한 깨진 링크 자동 테스트가 구현될 때까지, 단일 탭으로 직접 링크하지 마세요.
자세한 내용은 [이슈 225](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/issues/225)를 참조하세요.

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

## 접을 수 있는 패널

접을 수 있는 패널은 기본적으로 닫혀 있으며 제목이 필요합니다. 렌더링된 문서에서
패널 안의 콘텐츠를 보려면 패널을 펼쳐야 합니다.

  

Collapsible panel example
This content appears inside the collapsible panel.


접을 수 있는 패널은 [가용성 세부 정보](/19.1/development/documentation/styleguide/availability_details/) 섹션의 GitLab Duo 페이지에서 지원되는 LLM, 편집기, 셀프 호스팅 모델 가용성 정보에 대해서만 사용하세요.

다른 콘텐츠에는 접을 수 있는 패널을 사용하지 마세요.

## 카드

카드는 하위 페이지 링크가 있는 랜딩 페이지를 만드는 데 사용합니다.

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

  


The first page
Another page
One more page

```
또한 카드는 선택적 설명과 함께 외부 URL을 지원합니다.
다음 구문을 사용하세요:
<ul class="card-grid">
<li><a href="https://example.com "Optional Description"">External page title</a></li>
</ul>

카드는 GitLab 문서 사이트(https://docs.gitlab.com)에서만 렌더링됩니다.
GitLab 제품 도움말에서는 카드 세트가 순서 없는 링크 목록으로 표시됩니다.
카드 설명은 Markdown 페이지 헤더의 description 메타데이터에서 가져옵니다.
카드를 페이지의 유일한 콘텐츠로 사용하는 최상위 페이지에서 카드를 사용하세요.
유지 관리 버전#
유지 관리 버전 숏코드를 사용하여 유지 관리 정책에 명시된
현재 유지 관리 중인 GitLab 버전의 순서 없는 목록을 만드세요:


유지 관리 버전은 GitLab 문서 사이트(https://docs.gitlab.com)의 사전 릴리즈 버전에서만 렌더링됩니다. 그 외 모든 경우와
/help에서는 문서 사이트 링크가 대신 표시됩니다.
용어집 툴팁#
용어집 툴팁 숏코드를 사용하여 마우스를 올렸을 때 툴팁으로 표시되는 짧은 정의를 제공하세요.
예를 들면:
To do this thing, use .

사용자가
​에 마우스를 올리면 툴팁이 표시됩니다.
툴팁에 용어집 페이지가 설정된 경우, 사용자가 앵커 텍스트를 선택하면 관련 용어집 페이지가 열립니다.
사용 지침#
용어집 툴팁은 정의가 단일하고 간결한 문장인 경우에 사용하고, 60자를 초과하지 않도록 하세요. 더 긴 정의는 용어집 페이지를 사용하세요.
한 페이지에 툴팁을 5~10개 이상 사용하지 마세요. 툴팁이 많을수록 독자의 읽기 속도가 느려집니다. 정의를 과도하게 제공하지 않도록 주의하세요.
다음과 같은 경우에 용어 설명 툴팁을 사용하세요:


페이지에서 GitLab 전용 용어가 처음 등장할 때.


artifact나 analyzer처럼 독자가 모를 수 있는 용어.


다음과 같은 경우에는 용어 설명 툴팁을 사용하지 마세요:


repository, branch, commit처럼 일반적인 용어.


같은 용어가 등장할 때마다 매번.


약어를 대체하는 용도로. 첫 등장 시 약어를 풀어 쓸 수 있고 업계 표준인 경우에는 용어 설명 툴팁을 사용하지 마세요.


용어집 항목 생성#
docs-gitlab-com 리포지터리의
glossary.yaml 파일에
용어집 정의를 추가하세요. 각 정의는 짧게 작성하고 링크를 포함하지 않아야 합니다.
용어집 항목은 terms 블록 안에 다음 필드로 정의됩니다:
term_id
용어집 항목의 고유 ID입니다. 용어집 섹션에 링크를 연결하려면, term_id가 해당 항목의 용어집 페이지 앵커와 일치해야 합니다.
display_name
문서에 표시되는 텍스트입니다. display_name 필드는 대소문자를 구분하지 않습니다. 예를 들어, 단축 코드의 text 파라미터 값이 "attack surface"이면 glossary.yaml 파일의 "Attack Surface" 항목과 매칭됩니다.
glossary
선택 사항입니다. 해당 항목의 용어집 정의로 연결되는 링크입니다. 포함된 경우, glossary_url 끝에 term_id가 추가됩니다. 예: /user/application_security/terminology#attack-surface.
short_description
사용자가 툴팁 위에 마우스를 올렸을 때 표시되는 텍스트입니다.
glossary.yaml 파일의 용어집 항목 정의 예시:
terms:
  - term_id: attack-surface
    display_name: Attack Surface
    glossary: *security_glossary
    short_description: The different places in an application that are vulnerable to attack

용어집은 glossary.yaml 파일 상단에 정의됩니다.
첫 번째 줄은 두 개의 고유 ID로 구성됩니다:


용어집의 짧은 이름.


용어집의 더 긴 식별자. 이 용어집에 링크되는 용어집 항목의 glossary 필드는 이 값과 일치해야 합니다.


glossary_url
해당 항목이 정의된 용어집 페이지의 루트 URL입니다.
glossary.yaml 파일의 용어집 정의 예시:
# Glossary files
security: &security_glossary
  glossary_url: "/user/application_security/terminology"

이 두 예시를 결합하면 다음과 같이 동작합니다:


"Attack Surface"라는 구문이 문서에서 링크로 표시됩니다.


사용자가 링크 위에 마우스를 올리면 short_description 필드의 내용이 툴팁으로 표시됩니다.


사용자가 링크를 선택하면 용어집 페이지가 attack-surface 앵커 위치에서 열립니다.


표절#
인용 출처를 밝힌 제한적인 인용이 아닌 한, 다른 출처의 내용을 복사하여 붙여넣지 마세요. 일반적으로 관련 정보를 자신만의 표현으로 다시 작성하거나 출처에 링크를 거는 것이 더 좋습니다.
향후 버전의 기능 약속#
향후 릴리스에서 기능을 제공하겠다고 약속하지 마세요. 예를 들어, "이 기능에 대한 지원이 계획되어 있습니다."와 같은 표현은 피하세요.
향후 기능 작업을 보장할 수 없으며, 이러한 약속은 법적 문제를 일으킬 수 있습니다. 대신 이슈가 존재한다고 언급하세요.
예를 들어:


개선에 대한 지원이 [issue <issue_number>](https://link-to-issue)에서 제안되었습니다.


이 작업은 수행할 수 없지만, [issue 12345](https://link-to-issue)에서 이 동작을 변경하도록 제안하고 있습니다.


기능을 제거할 계획이라고 언급하는 것은 가능합니다.
향후 기능을 반드시 문서화해야 하는 경우, 면책 조항을 사용하세요.
제품 및 기능#
GitLab 제품 문서에서 제품과 기능을 설명할 때 이 섹션의 정보를 참조하세요.
이름에 줄 바꿈 사용 금지#
기능 또는 제품 이름에 공백이 포함된 경우, 줄 바꿈으로 이름을 나누지 마세요.
이름이 변경될 때 줄 바꿈이 포함된 텍스트를 검색하거나 grep하기가 더 복잡해집니다.
제품 가용성 세부 정보#
제품 가용성 세부 정보는 기능에 대한 정보를 제공하며 토픽 제목 아래에 표시됩니다.
제품 가용성 세부 정보에서 자세히 알아보세요.
특정 섹션#
특정 섹션에는 특정 스타일을 적용해야 합니다. 특정
섹션의 스타일은 이 섹션에서 설명합니다.
도움말 및 피드백 섹션#
이 섹션은 각 문서의 끝에 표시되며, 프론트매터에
키를 추가하여 생략할 수 있습니다:
---
feedback: false
---

기본값은 해당 섹션을 유지하는 것입니다. 문서에서 이를 생략하려면
기술 작성자와 먼저 협의해야 합니다.
GitLab 재시작#
GitLab의 재시작 또는 재구성이 필요한 경우, 중복을 피하기 위해
필요에 따라 ‘reconfigure’를 ‘restart’로 바꿔서 다음과 같은 텍스트와 함께
doc/administration/restart_gitlab.md로 링크하세요:
Save the file and [reconfigure GitLab](../../../administration/restart_gitlab.md)
for the changes to take effect.

문서가 doc/ 디렉터리 외부에 있는 경우, 상대 링크 대신 전체 경로를 사용하세요:
https://docs.gitlab.com/administration/restart_gitlab.
다양한 설치 방법 문서화 방법#
GitLab은 다섯 가지 공식 설치 방법을 지원합니다. 문장이나 제목의 일부로
단어를 참조할 때는 다음 표현을 사용하세요:


Linux package


Helm chart


GitLab Operator


Docker


Self-compiled


탭을 사용할 때
설명을 위한 괄호를 추가하는 것도 괜찮습니다:


Linux package (Omnibus)


Helm chart (Kubernetes)


GitLab Operator (Kubernetes)


Docker


Self-compiled (source)


탭을 사용하여 GitLab Self-Managed 구성 절차 설명#
구성 절차에는 사용자가 구성 파일을 편집하거나, GitLab을 재구성하거나,
GitLab을 재시작해야 하는 경우가 있습니다. 이 경우:


탭을 사용하여 다양한 설치 방법을 구분하세요.


이전 목록에서 설명한 대로 설치 방법 이름을 정확히 사용하세요.


아래에 설명된 순서대로 사용하세요.


코드 블록을 해당 목록 항목에 맞게 들여쓰기 하세요.


각 코드 블록에 적절한 구문 강조 표시를 사용하세요(ruby, shell, 또는 yaml).


YAML 파일의 경우, 항상 상위 설정을 포함하세요.


GitLab을 재구성하거나 재시작하는 마지막 단계는 매번 동일하므로
그대로 사용할 수 있습니다.


구성 편집을 설명할 때는 필요에 따라 편집하여 다음 스니펫을 사용하세요:
<div class="tabs-container" data-tabs><div class="tabs-nav"><button class="tab-button active" data-tab-index="0">Linux package (Omnibus)</button><button class="tab-button" data-tab-index="1">Helm chart (Kubernetes)</button><button class="tab-button" data-tab-index="2">Docker</button><button class="tab-button" data-tab-index="3">Self-compiled (source)</button></div><div class="tab-panel active" data-tab-index="0">

1. Edit `/etc/gitlab/gitlab.rb`:

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



Save the file and reconfigure GitLab:
sudo gitlab-ctl reconfigure