이 문서는 문법, 서식 등 GitLab 문서의 표준을 정의합니다. 특정 단어에 대한 지침은 단어 목록을 참고합니다.

GitLab 보이스#

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

이 지침을 바탕으로 GitLab 문서의 보이스는 간결하고, 직접적이며, 정확하고자 합니다. 검색하고 훑어보기 쉬운 정보를 제공하는 것이 목표입니다.

문서의 보이스는 대화하듯 자연스러우면서도 짧아야 하고, 친근하면서도 간결해야 합니다.

문서는 단일 진실 공급원(SSoT)입니다#

GitLab 문서는 구현, 사용, 문제 해결과 관련된 모든 제품 정보의 SSoT입니다. 문서는 계속 발전합니다. 새로운 제품과 기능이 추가될 때마다, 그리고 명확성, 정확성, 완결성을 높이기 위해 갱신됩니다.

이 정책은 다음과 같은 효과가 있습니다.

• 정보 사일로를 방지하고 GitLab 제품에 대한 정보를 더 쉽게 찾을 수 있게 합니다.
• 문서의 여러 위치에 콘텐츠를 중복해서 둘 수 없다는 뜻은 아닙니다.

주제 유형#

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

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

• 콘텐츠를 찾기 어렵습니다. GitLab 문서는 방대하며 유용한 정보를 많이 담고 있습니다. 주제 유형은 반복되는 패턴을 만들어 콘텐츠를 훑어보고 파악하기 쉽게 합니다.
• 콘텐츠가 기여자의 관점에서 작성되는 경우가 많습니다. GitLab 문서는 다양한 기여자가 작성합니다. 주제 유형(특히 작업)은 기능이 어떻게 구현되었는지를 기록하는 대신, 다른 사람을 돕는 데 맞춘 형식으로 정보를 정리하도록 돕습니다.

문서 우선 방법론#

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

• 질문의 답이 문서에 있다면 정보를 다시 풀어 쓰지 말고 문서 링크를 공유합니다.
• GitLab 문서에 없는 정보를 발견하면 머지 리퀘스트(MR)를 만들어 문서에 그 정보를 추가합니다. 그런 다음 MR을 공유해 정보를 전달합니다.

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

현지화를 위한 글쓰기#

GitLab은 글로벌 독자를 위해 글을 쓰는 데 도움이 되는 지침을 따릅니다.

GitLab 보이스는 번역을 염두에 두고 명확하고 직접적으로 쓰도록 요구합니다. 스타일 가이드, 단어 목록, Vale 규칙은 문서의 일관성을 보장합니다.

문서를 다른 언어로 번역할 때는 각 단어의 의미가 분명해야 합니다. 기계 번역, GitLab Duo Chat, 기타 AI 도구의 사용이 늘어나면서 일관성은 더욱 중요해졌습니다.

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

피해야 할 표현은 다음과 같습니다.

• there is 및 there are처럼 주어를 숨기는 표현.
• it처럼 모호한 대명사.
• -ing로 끝나는 단어.
• since와 because처럼 서로 혼동될 수 있는 단어.
• 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으로 작성합니다.

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

Markdown 서식은 markdownlint와 Vale로 테스트합니다.

Markdown 안의 HTML#

하드코딩한 HTML도 유효하지만 다음과 같은 이유로 권장하지 않습니다.

• 사용자 지정 마크업은 향후 사이트 전체 변경이나 디자인 시스템 업데이트를 깨뜨릴 수 있습니다.
• 사용자 지정 마크업에는 사이트 전체의 일관성을 보장하는 테스트 커버리지가 없습니다.
• 사용자 지정 마크업은 반응형이 아니거나 접근성이 떨어질 수 있습니다.
• 사용자 지정 마크업은 Pajamas 지침을 따르지 않을 수 있습니다.
• Markdown 안의 HTML과 CSS는 /help에서 렌더링되지 않습니다.
• HTML을 직접 작성하면 오류가 발생하기 쉽습니다. 잘못된 HTML로 페이지 레이아웃이나 다른 구성 요소가 깨질 수 있습니다.

다음 경우에는 HTML을 허용합니다.

• Markdown에 동등한 기능이 없는 경우.
• 테크니컬 라이터가 콘텐츠를 검토하고 승인한 경우.
• 사용자 지정 요소가 시급하게 필요하고 Technical Writing 엔지니어의 구현을 기다릴 수 없는 경우.

HTML <a> 태그로 만드는 링크는 href 속성에 절대 URL을 사용해야 합니다. 일반 링크와 달리 Markdown 파일로 향하는 상대 링크를 사용하지 않습니다. Hugo는 Markdown 형식의 링크만 처리하고 바꿀 수 있기 때문입니다.

Docs 사이트에 유용할 새 요소에 대한 아이디어나 요청이 있다면 기능 요청을 제출합니다.

Markdown의 제목 수준#

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

• 하위 섹션마다 제목 수준을 하나씩 높입니다. 즉, 주제 제목 앞의 # 문자 수를 하나씩 늘립니다.
• H5(#####)보다 깊은 제목 수준은 피합니다. 제목 수준이 다섯 개를 넘게 필요하다면 주제를 새 페이지로 옮깁니다. H4보다 깊은 제목 수준은 오른쪽 사이드바 탐색에 표시되지 않습니다.
• 수준을 건너뛰지 않습니다. 예: ## > ####.
• 주제 제목의 앞뒤에 빈 줄을 하나씩 둡니다.
• 주제 제목에 코드를 사용하는 경우 코드를 백틱으로 감쌉니다.
• 주제 제목에 굵은 글씨를 사용하지 않습니다.

제목이 목차(TOC)에 나타나지 않게 하려면 제목 텍스트 뒤에 `` 속성을 추가합니다.

## My heading 

제목은 페이지에 그대로 렌더링되지만 TOC에서는 제외됩니다.

Markdown의 설명 목록#

용어를 정의하거나 옵션을 구분하려면 설명 목록을 사용합니다. UI 요소 목록에는 설명 목록 대신 일반 목록을 사용합니다.

설명 목록을 다른 스타일과 섞어 쓰지 않습니다.

Term 1
: Definition of Term 1

Term 2
: Definition of Term 2 is much longer, but we can use
  multiple lines.

이 목록은 다음과 같이 렌더링됩니다.

Term 1 : Definition of Term 1

Term 2 : Definition of Term 2 is much longer, but we can use multiple lines.

쇼트코드#

쇼트코드는 Markdown 콘텐츠에 포함해 페이지에 가용성 정보나 탭 같은 비표준 요소를 표시하는 템플릿 코드 조각입니다.

GitLab 문서는 다음 쇼트코드를 사용합니다.

• 가용성 정보
• 접을 수 있는 패널
• 버전 히스토리
• 아이콘
• 탭
• 카드
• 유지 관리 버전
• 가이드
• 기능 표
  • Yes
  • No
• 용어집 툴팁

언어#

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 같은 단어를 사용하지 않습니다.
• "This feature will save you time and money."와 같은 마케팅 문구를 사용하지 않습니다.

대신 사실과 달성 가능한 목표에 초점을 맞추고 구체적으로 씁니다. 예를 들면 다음과 같습니다.

• The build time can decrease when you use this feature.
• Use this feature to save time when you create a project. The API creates the file and you do not have to manually intervene.

자기 지시적 글쓰기#

문서 자체에 대해 쓰는 것을 피합니다. 예를 들어 다음과 같이 쓰지 않습니다.

• 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에서 테스트합니다.

대소문자#

GitLab은 회사 차원에서 소문자를 선호합니다.

주제 제목#

주제 제목에는 문장형 대소문자를 사용합니다. 예를 들면 다음과 같습니다.

• # Use variables to configure pipelines
• ## Use the To-Do List

UI 텍스트#

버튼 레이블, 페이지, 탭, 메뉴 항목 같은 특정 사용자 인터페이스 텍스트를 언급할 때는 사용자 인터페이스에 표시되는 것과 같은 대소문자를 사용합니다.

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

사용자 인터페이스 텍스트에 스타일 오류가 있다고 생각되면 이슈나 MR을 만들어 사용자 인터페이스 텍스트 변경을 제안합니다.

기능 이름#

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

다만 드물게 기능 이름을 제목형 대소문자로 쓰는 경우가 있습니다. 예외는 다음과 같습니다.

• 모든 문서에 일관되게 적용할 수 있도록 markdownlint에 고유 명칭으로 추가된 경우.
• 단어 목록에 추가된 경우.

용어가 단어 목록에 없다면 GitLab 테크니컬 라이터에게 조언을 구합니다. 기능 이름을 정하고 GitLab 표준을 충족하는지 확인하는 데 도움이 필요하면 핸드북을 참고합니다.

Features 페이지나 features.yml의 용어나 문구의 대소문자를 기본적으로 따라 하지 않습니다.

기타 용어#

다음 이름은 대문자로 씁니다.

• GitLab 제품 티어. 예를 들어 GitLab Free, GitLab Ultimate.
• 서드 파티 조직, 소프트웨어, 제품. 예를 들어 Prometheus, Kubernetes, Git, The Linux Foundation.
• 방법 또는 방법론. 예를 들어 Continuous Integration, Continuous Deployment, Scrum, Agile.

해당 대상의 공식 출처에 나열된 대소문자 스타일을 따릅니다. 그 스타일은 비표준일 수 있습니다. 예: GitLab, npm.

가짜 사용자 정보#

문서에 실제 사용자 이름이나 이메일 주소를 포함하지 않습니다.

텍스트의 경우 다음을 따릅니다.

• Sidney Jones, Zhang Wei, Alex Garcia처럼 흔한 성을 가진 다양하거나 성별이 드러나지 않는 이름을 사용합니다.
• 가짜 이메일 주소는 example.com으로 끝나게 합니다.

스크린샷의 경우 다음을 따릅니다.

• 스크린샷을 찍기 전에 페이지를 임시로 수정합니다.

  1. 변경하려는 텍스트를 마우스 오른쪽 버튼으로 클릭합니다.
  2. Inspect를 선택합니다.
  3. Elements 대화 상자에서 HTML을 편집해 실제 사용자 정보가 포함된 텍스트를 예시 데이터로 바꿉니다.
  4. 대화 상자를 닫습니다. 웹 페이지의 모든 사용자 데이터가 입력한 예시 데이터로 바뀌어 있어야 합니다.
  5. 스크린샷을 찍습니다.

• 또는 테스트 환경에 예시 계정을 만들고 그곳에서 스크린샷을 찍습니다.

• 환경을 재현할 수 없다면 macOS의 미리 보기 같은 이미지 편집 도구로 사용자 데이터를 흐리게 처리합니다.

가짜 URL#

문서에 샘플 URL을 포함할 때는 다음을 사용합니다.

• 도메인 이름이 일반적인 경우 example.com.
• GitLab Self-Managed만 가리키는 경우 gitlab.example.com. GitLab.com에는 gitlab.com을 사용합니다.

가짜 토큰#

문서에 실제 토큰을 사용하지 않습니다.

예시에는 다음 가짜 토큰을 사용합니다.

축약형#

축약형은 특히 튜토리얼, 안내 문서, 사용자 인터페이스에서 친근하고 격식 없는 어조를 만들 수 있어 권장합니다.

하지만 일부 축약형은 피해야 합니다.

소유격#

조직이나 제품 이름 같은 고유 명사에는 소유격('s)을 사용하지 않습니다.

예를 들어 Docker's CLI 대신 the Docker CLI를 사용합니다.

자세한 내용은 Google 문서 스타일 가이드를 참고합니다.

전치사#

필요하면 문장 끝에 전치사를 사용합니다. 문장 끝에 남은 전치사도 괜찮습니다. 예를 들면 다음과 같습니다.

• 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 스타일 가이드를 참고합니다.

UI의 숫자에 대해서는 Pajamas를 참고합니다.

날짜와 시간#

날짜는 month day, year 형식을 사용하고 시간은 AM과 PM을 사용합니다. 예를 들면 다음과 같습니다.

January 3, 2026 at 10:30 AM

자세한 내용은 Microsoft 스타일 가이드를 참고합니다.

UI의 날짜와 시간에 대해서는 Pajamas를 참고합니다.

텍스트#

• Markdown으로 작성합니다.

• 새 문단에는 빈 줄을 삽입합니다.

• 서로 다른 마크업 사이(예: 모든 문단, 제목, 목록 뒤)에 빈 줄을 삽입합니다. 예시는 다음과 같습니다.

  ## Heading
  
  Paragraph.
  
  - List item 1
  - List item 2
  

줄 길이#

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

• 긴 줄은 약 100자에서 나누되 링크는 나누지 않습니다.
• 논리적인 단어 묶음 사이에서 줄을 나누지 않도록 하고, 같은 줄에 함께 둡니다.
• 새 문장은 새 줄에서 시작합니다.

예를 들면 다음과 같습니다.

• 다음과 같이 씁니다.

  This long line talks about how to manage a GitLab Self-Managed instance
  deployed to Google Cloud for Education.
  

• 다음과 같이 쓰지 않습니다.

  This long line talks about how to manage a GitLab
  Self-Managed instance deployed to Google Cloud for
  Education.
  

주석#

Markdown에 주석을 삽입하려면 게시될 때 렌더링되지 않는 표준 HTML 주석을 사용합니다. 예시는 다음과 같습니다.

<!-- This is a comment that is not rendered -->

페이지를 유지 관리하는 작성자가 알아야 할 세부 사항을 메모할 때 HTML 주석을 사용합니다. 예: This table is autogenerated, edit 'path/to/file.rb' and run 'script.sh' to update the table.

문서를 숨기려고 HTML 주석을 사용하지 않습니다. 자세한 내용은 숨기지 말고 삭제하기를 참고합니다.

문장부호#

문장부호는 다음 지침을 따릅니다.

UI의 문장부호에 대해서는 Pajamas를 참고합니다.

• 완전한 문장은 마침표로 끝냅니다.
• 세 개 이상의 항목을 나열할 때는 마지막 and 또는 or 앞에 연속 쉼표(옥스퍼드 쉼표)를 사용합니다. (OxfordComma.yml에서 테스트합니다.)

콘텐츠의 간격을 조정할 때는 다음을 따릅니다.

• 문장 사이에는 공백을 하나만 사용합니다. (공백을 두 개 이상 사용하는지는 SentenceSpacing.yml에서 테스트합니다.)
• 줄 바꿈 없는 공백을 사용하지 않습니다. 대신 표준 공백을 사용합니다. (lint-doc.sh에서 테스트합니다.)
• 들여쓰기에 탭을 사용하지 않습니다. 대신 공백을 사용합니다. Tab 키를 눌렀을 때 탭 대신 공백이 입력되도록 코드 편집기를 설정하는 것을 고려합니다.

다음 문장부호는 사용하지 않습니다.

• ;(세미콜론): 대신 두 문장으로 나눕니다.
• –(엔 대시) 또는 —(엠 대시): 대신 문장을 나누거나 쉼표를 사용합니다.
• “ ” ‘ ’: 큰따옴표 또는 작은따옴표의 타이포그래퍼 스타일("곡선") 따옴표입니다. 대신 곧은 따옴표를 사용합니다. (NonStandardQuotes.yml에서 테스트합니다.)

말줄임표#

말줄임표는 사용하지 않도록 합니다. 예를 들어 코드 블록이나 CLI 응답처럼 꼭 써야 한다면 공백 없이 마침표 세 개(...)를 사용합니다.

… HTML 엔티티나 … HTML 코드는 코드 블록 렌더링에 문제를 일으키므로 사용하지 않습니다.

UI 텍스트를 문서화할 때는 말줄임표를 포함하지 않습니다. 예를 들어 다음과 같이 씁니다.

• Search or go to

다음과 같이 쓰지 않습니다.

• Search or go to...

자세한 내용은 Microsoft 스타일 가이드를 참고합니다.

자리 표시자 텍스트#

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

이런 경우 <와 >를 사용해 독자가 텍스트를 자신의 값으로 바꿔야 하는 위치를 표시합니다.

예를 들면 다음과 같습니다.

cp <your_source_directory> <your_destination_directory>

자리 표시자가 코드 블록 안에 있지 않다면 <와 >를 사용하고 자리 표시자를 백틱 하나로 감쌉니다. 예를 들면 다음과 같습니다.

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

따옴표#

따옴표에 대한 Microsoft 지침을 따릅니다.

사용자 입력에는 따옴표를 피하고 대신 백틱을 사용합니다.

텍스트 서식#

텍스트 서식은 다음과 같이 사용합니다.

• UI 요소와 페이지에는 굵게.
• 입력, 출력, 코드 등에는 인라인 코드 스타일.
• 명령줄 예시와 여러 줄 입력, 출력, 코드 등에는 코드 블록.
• 키보드 명령에는 <kbd>.

굵게#

굵은 글씨는 다음에 사용합니다.

• 눈에 보이는 레이블이 있는 UI 요소. 레이블의 텍스트와 대소문자를 그대로 따릅니다.
• 탐색 경로.

키워드나 강조에는 굵은 글씨를 사용하지 않습니다.

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

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

예를 들면 다음과 같습니다.

• Select Cancel.
• On the Issues page...
• On the Pipelines tab...

텍스트를 굵게 하려면 별표 두 개(**)로 감쌉니다. 예를 들면 다음과 같습니다.

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>. 꺾쇠 괄호를 포함합니다.

예를 들면 다음과 같습니다.

• In the Name text box, enter test.
• Use the rules: CI/CD keyword to control when to add jobs to a pipeline.
• Send a DELETE request to delete the runner. Send a POST request to create one.
• The job log displays Job succeeded when complete.

코드 블록#

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

코드 블록은 다음에 사용합니다.

• CLI 및 cURL 명령.
• 인라인 코드로 쓰기에는 너무 큰 여러 줄 입력, 출력, 코드 샘플.

코드 블록을 추가하려면 텍스트의 위와 아래에 백틱 세 개(```)를 추가하고, 올바른 구문 강조를 위해 맨 위에 구문 이름을 지정합니다. 예를 들면 다음과 같습니다.

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

코드 블록을 사용할 때는 다음을 따릅니다.

• 코드 블록의 위와 아래에 빈 줄을 추가합니다.
• 지원되는 구문 이름 중 하나를 사용합니다. 더 나은 옵션이 없다면 plaintext를 사용합니다.
• 코드 블록에 이미 백틱 세 개를 사용하는 다른(중첩된) 코드 블록이 있으면 백틱 네 개(````)를 사용합니다. 위 예시는 코드 블록 형식을 보여 주기 위해 내부적으로 백틱 네 개를 사용합니다.

코드 블록에서 빠진 정보를 나타내려면 주석이나 말줄임표를 사용합니다. 예를 들면 다음과 같습니다.

• # Removed for readability
• // ...

키보드 명령#

키 입력에 대해 쓸 때는 다음을 따릅니다.

• HTML <kbd> 태그를 사용합니다.
• 키 조합에서 <kbd> 태그 사이에 공백을 사용하지 않습니다.
• Alt를 제외하고 키의 전체 이름을 풀어 씁니다(Vale 규칙: SubstitutionWarning.yml).
• 동작 키라면 키 이름의 첫 글자를 대문자로 씁니다. 예를 들어 Shift, Command, Delete가 있습니다.
• 키가 문자라면 대문자를 사용합니다.
• 화살표에는 ↑, ↓, ←, →를 사용합니다.

예를 들면 다음과 같습니다.

To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.

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

To stop the command, press Control+C.

기울임꼴과 강조#

제품 문서에서는 강조를 위한 기울임꼴을 사용하지 않습니다. 대신 강조가 필요하지 않을 만큼 명확하게 콘텐츠를 작성합니다. GitLab과 https://docs.gitlab.com은 산세리프 글꼴을 사용하는데, 기울임꼴 텍스트는 산세리프를 사용하는 페이지에서 눈에 띄지 않습니다.

목록#

정보를 더 훑어보기 쉬운 형식으로 제시하려면 목록을 사용합니다.

• 목록의 모든 항목을 병렬 구조로 만듭니다. 예를 들어 일부 항목은 명사로, 다른 항목은 동사로 시작하지 않습니다.

• 모든 항목을 대문자로 시작합니다.

• 모든 항목에 같은 문장부호를 사용합니다.

• 항목이 완전한 문장이 아니면 마침표를 사용하지 않습니다.

• 완전한 문장마다, 또는 도입 문구와 결합했을 때 목록 항목이 완전한 문장이 되는 경우에는 마침표를 사용합니다. 세미콜론이나 쉼표는 사용하지 않습니다.

• 도입 문구 뒤에 콜론(:)을 추가합니다. 예를 들면 다음과 같습니다.

  The basket contains these fruits:
  
  - Bananas
  - Apples
  

• 목록에서 키워드나 개념을 정의하는 데 굵은 서식을 사용하지 않습니다. 굵은 글씨는 UI 요소 레이블에만 사용합니다. 예를 들면 다음과 같습니다.

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

  키워드와 개념에는 대체 서식으로 참조 주제나 설명 목록을 고려합니다.

• 목록 항목으로 도입 문구를 완성하는 방식은 피합니다. 이 형식은 문장 구조가 다른 언어로 현지화하기 어려울 수 있습니다. 예를 들어 다음과 같이 씁니다.

  You can get the license key in the following ways:
  
  - Copy the license key from the email.
  - Download the file.
  

  다음과 같이 쓰지 않습니다.

  You can get the license key by:
  
  - Copying it from the email.
  - Downloading the file.
  

순서 있는 목록과 순서 없는 목록 선택#

일련의 단계에는 순서 있는 목록을 사용합니다. 예를 들면 다음과 같습니다.

Follow these steps to do something.

1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.

단계를 순서대로 완료할 필요가 없으면 순서 없는 목록을 사용합니다. 예를 들면 다음과 같습니다.

These things are imported:

- Thing 1
- Thing 2
- Thing 3

목록 마크업#

• 순서 없는 목록에는 별표(*) 대신 대시(-)를 사용합니다.
• 순서 있는 목록의 모든 항목은 1.로 시작합니다. 렌더링되면 목록 항목은 순차적으로 번호가 매겨집니다.
• 목록의 앞뒤에 빈 줄을 둡니다.
• 중첩된 하위 항목을 나타내려면 줄을 공백(탭 아님)으로 시작합니다.

목록 항목 안에 중첩#

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

• 코드 블록
• 인용 블록
• 알림 상자
• 삽화
• 탭

중첩된 항목은 항상 목록 항목의 첫 글자와 정렬해야 합니다. 순서 없는 목록(- 사용)에서는 들여쓰기 한 단계마다 공백 두 개를 사용합니다.

- Unordered list item 1

  A line nested that uses 2 spaces to align with the `U` above.

- Unordered list item 2

  > A quote block that will nest
  > inside list item 2.

- Unordered list item 3

  ```plaintext
  a code block that nests inside list item 3
  ```

- Unordered list item 4

  ![An image nested under list item 4.](image.png)

순서 있는 목록에서는 들여쓰기 한 단계마다 공백 세 개를 사용합니다.

1. Ordered list item 1

   A line nested that uses 3 spaces to align with the `O` above.

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

1. Ordered list item one.
1. Ordered list item two.
   - Nested unordered list item one.
   - Nested unordered list item two.
1. Ordered list item three.

- Unordered list item one.
- Unordered list item two.
  1. Nested ordered list item one.
  1. Nested ordered list item two.
- Unordered list item three.

가이드#

guide 쇼트코드를 사용해 스타일이 적용된 순서 있는 단계 목록을 만듭니다. 가이드 안에 알림 같은 다른 쇼트코드를 중첩할 수 있습니다. 다만 렌더링된 스타일 때문에 콘텐츠를 훑어보기 어려울 수 있으므로 드물게 사용합니다.

가이드 안에 가이드를 사용하지 않습니다.

가이드를 만들려면 다음 예시를 따릅니다.

1. Guide item with text.

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

   This is an item with an alert.

   > [!note]
   > This is a note.

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

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

가이드는 튜토리얼에만 사용합니다. 대부분의 작업에는 순서 있는 목록을 사용합니다.

표#

표는 복잡한 정보를 알기 쉽게 설명하는 데 사용해야 합니다. 많은 경우 각 항목에 설명이 하나씩만 있는 항목 목록은 순서 없는 목록으로 충분히 설명할 수 있습니다. 하지만 데이터가 행렬로 설명하는 것이 가장 좋다면 표가 최선의 선택입니다.

작성 지침#

표를 접근하기 쉽고 훑어보기 쉽게 유지하려면 빈 셀을 피합니다. 기능 표에서는 쇼트코드를 사용해 기능 제공 여부를 나타냅니다. 그 외에 셀에 의미 있는 값이 없다면 None을 사용합니다.

표를 더 쉽게 유지 관리하려면 다음을 따릅니다.

• 표에 Description 칼럼이 있으면 가능한 한 가장 오른쪽 칼럼으로 둡니다.

• 칼럼 너비를 일관되게 맞추도록 공백을 추가합니다. 예를 들면 다음과 같습니다.

  | Parameter | Default      | Requirements |
  |-----------|--------------|--------------|
  | `param1`  | `true`       | A and B.     |
  | `param2`  | `gitlab.com` | None         |
  

• 표가 매우 넓다면 가장 오른쪽 칼럼에는 추가 공백을 생략합니다. 예를 들면 다음과 같습니다.

  | Setting   | Default | Description |
  |-----------|---------|-------------|
  | Setting 1 | `1000`  | A short description. |
  | Setting 2 | `2000`  | A long description that would make the table too wide and add too much whitespace if every cell in this column was aligned. |
  | Setting 3 | `0`     | Another short description. |
  

• 표의 헤더(첫 번째) 행과 구분(두 번째) 행은 길이가 같아야 합니다. |-|-|-|나 |--|--|처럼 줄인 구분 행은 사용하지 않습니다.

• 큰 표가 자동 서식으로 잘 정리되지 않는다면 자동 서식을 건너뛸 수 있지만 다음을 따릅니다.

  • 처음 두 행의 길이를 같게 만듭니다.
  • | 문자와 셀 내용 사이에 공백을 넣습니다. 예를 들어 |Cell1|Cell2|가 아니라 | Cell 1 | Cell 2 |를 사용합니다.

큰 표를 위한 옵션#

Hugo 클래스 속성을 사용해 표를 압축하거나 확장할 수 있게 만들 수 있습니다. 표에 린트 오류가 생기지 않도록 모든 규칙을 활성화한 상태로 로컬에서 표를 테스트합니다.

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

압축된 표#

압축된 표는 필요에 따라 세로와 가로로 스크롤할 수 있으며 높이가 제한됩니다. 기본적으로 페이지에 맞지 않는 넓은 표는 압축됩니다. 긴 표는 압축되지 않습니다. 원한다면 condensed 클래스 속성을 추가해 표가 페이지에서 차지하는 공간을 줄일 수 있습니다.

| Parameter | Default      | Requirements |
|-----------|--------------|--------------|
| `param1`  | `true`       | A and B.     |
| `param2`  | `gitlab.com` | None         |

또는

| Parameter | Default      | Requirements |
|-----------|--------------|--------------|
| `param1`  | `true`       | A and B.     |
| `param2`  | `gitlab.com` | None         |
{class="condensed"}

확장 가능한 표#

확장 가능한 표에는 Expand table 버튼이 있으며, 이 버튼을 선택하면 표가 대화 상자에서 열립니다. 확장 가능한 표를 만들려면 expandable 클래스 속성을 사용합니다.

표를 압축하면서 확장 가능하게도 만들려면 두 속성을 모두 사용합니다. 예를 들면 다음과 같습니다.

{.condensed .expandable}

또는

{class="condensed expandable"}

표 서식을 위한 편집기 확장#

모든 Markdown 파일에서 표 서식을 일관되게 유지하려면 VS Code의 Markdown Table Formatter로 표를 서식화하는 것을 고려합니다. 이 확장이 위 지침을 따르도록 구성하려면 Follow header row length 설정을 켭니다. 설정을 켜려면 다음을 따릅니다.

• UI에서 켜는 방법은 다음과 같습니다.

  1. VS Code 메뉴에서 Code > Settings > Settings로 이동합니다.
  2. Limit Last Column Length를 검색합니다.
  3. Limit Last Column Length 드롭다운 목록에서 Follow header row length를 선택합니다.

• VS Code settings.json에서 켜려면 다음 줄을 새로 추가합니다.

  {
    "markdown-table-formatter.limitLastColumnLength": "Follow header row length"
  }
  

이 확장으로 표를 서식화하려면 표 전체를 선택하고 선택 영역을 마우스 오른쪽 버튼으로 클릭한 다음 Format Selection With를 선택합니다. VS Code 명령 팔레트에서 Markdown Table Formatter를 선택합니다.

Sublime Text를 사용한다면 Markdown Table Formatter 플러그인을 사용해 볼 수 있지만, 이 플러그인에는 Follow header row length 설정이 없습니다.

기존 표 업데이트#

기존 표에 행을 추가하거나 편집하면 일부 행의 정렬이 맞지 않을 수 있습니다. 몇 개의 행만 변경한다면 표 전체를 다시 정렬하지 않습니다. 너비에 맞추려고 칼럼을 다시 정렬하면 표 전체가 수정된 것으로 표시되어 diff를 읽기 어려워지기 때문입니다.

Markdown 표는 시간이 지나면서 자연스럽게 정렬이 어긋나지만 docs.gitlab.com에서는 여전히 올바르게 렌더링됩니다. 테크니컬 라이팅 팀은 다음에 페이지를 리팩터링할 때 셀을 다시 정렬할 수 있습니다.

표 헤더#

표 헤더에는 문장형 대소문자를 사용합니다. 예를 들어 Keyword value 또는 Project name입니다.

기능 표#

기능 목록 표(예: Permissions 페이지의 권한별 사용 가능 기능)를 만들 때는 다음 쇼트코드를 사용합니다.

API 문서나 인라인 텍스트에는 이 쇼트코드를 사용하지 않습니다. API 문서는 API 주제 템플릿을 따릅니다.

각주#

표 자체에 콘텐츠를 포함할 수 없을 때만 표 아래에 각주를 사용합니다. 예를 들어 다음과 같은 경우에 각주를 사용합니다.

• 여러 표 셀에 같은 정보를 제공해야 하는 경우.
• 표의 레이아웃을 방해할 콘텐츠를 포함해야 하는 경우.

각주 형식#

표에서는 각주마다 HTML 위첨자 태그 <sup>를 사용합니다. 태그는 문장 끝에 둡니다. 문장과 태그 사이에 공백을 하나 둡니다.

예를 들면 다음과 같습니다.

| App name | Description |
|:---------|:------------|
| App A    | Description text. <sup>1</sup> |
| App B    | Description text. <sup>2</sup> |

각주를 추가할 때 표에 있는 기존 태그의 순서를 다시 정렬하지 않습니다.

표 아래의 각주에는 **Footnotes**: 다음에 순서 있는 목록을 사용합니다.

예를 들면 다음과 같습니다.

**Footnotes**:

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

표와 각주는 다음과 같이 렌더링됩니다.

Footnotes:

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

각주가 다섯 개 이상인 경우#

표 자체에 포함할 수 없는 각주가 다섯 개 이상이면 목록 항목에 연속된 번호를 사용합니다. 연속된 번호를 사용한다면 Markdown 규칙 029를 비활성화해야 합니다.

**Footnotes**:

<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix -->
<!-- markdownlint-disable MD029 -->

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.

<!-- markdownlint-enable MD029 -->

링크#

링크는 독자가 필요한 것을 찾도록 돕는 중요한 수단입니다.

하지만 대부분의 콘텐츠는 검색으로 찾으며, 한 페이지에 링크를 너무 많이 넣는 것은 피해야 합니다. 링크가 너무 많으면 가독성이 떨어질 수 있습니다.

• 같은 페이지에 링크를 중복하지 않습니다. 예를 들어 Page A에서 Page B로 여러 번 링크하지 않습니다.
• 제목에 링크를 사용하지 않습니다. 링크가 포함된 제목은 오류를 일으킵니다.
• 링크 안의 단어 사이에서 강제로 줄을 바꾸지 않습니다.
• 한 문단에 여러 링크를 두는 것을 피합니다.
• 하나의 작업에 여러 링크를 두는 것을 피합니다.
• 한 페이지에서 다른 페이지로 향하는 링크를 15개 넘게 사용하지 않도록 합니다.
• 작업의 흐름을 방해하는 링크를 줄이기 위해 관련 주제 사용을 고려합니다.
• 같은 페이지의 섹션으로 향하는 앵커 링크는 피합니다. 사용자가 오른쪽 탐색을 이용하게 합니다.

인라인 링크#

참조 링크 대신 인라인 링크를 사용합니다. 인라인 링크는 파악하고 편집하기 더 쉽습니다. (Vale 규칙: ReferenceLinks.yml)

• 올바른 예:

  For more information, see [merge requests](path/to/merge_requests.md)
  

• 잘못된 예:

  For more information, see [merge requests][1].
  
  [1]: path/to/merge_requests.md
  

같은 리포지터리 안의 링크#

같은 리포지터리에 있는 다른 문서(.md) 파일로 링크하려면 다음을 따릅니다.

• 상대 파일 경로가 있는 인라인 링크를 사용합니다. 예를 들어 [GitLab.com settings](../user/gitlab_com/_index.md)입니다.
• 링크가 매우 길더라도 링크 전체를 한 줄에 넣습니다. (Vale 규칙: MultiLineLinks.yml).

문서 파일 외부의 파일로 링크하려면, 예를 들어 개발 문서에서 특정 코드 파일로 링크하려면 다음을 따릅니다.

• 전체 URL을 사용합니다. 예: [`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/help/show.html.haml)
• 선택 사항입니다. 특정 ref가 있는 전체 URL을 사용합니다. 예: [`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/6d01aa9f1cfcbdfa88edf9d003bd073f1a6fff1d/app/views/help/show.html.haml)

다른 리포지터리의 링크#

다른 리포지터리에 있는 페이지로 링크하려면 전체 URL을 사용합니다. 예를 들어 GitLab 리포지터리의 페이지에서 Charts 리포지터리로 링크하려면 [GitLab Charts documentation](https://docs.gitlab.com/charts/) 같은 URL을 사용합니다.

앵커 링크#

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

주제 제목 텍스트를 바꾸면 앵커 링크도 바뀝니다. 깨진 링크를 방지하려면 다음을 따릅니다.

• 주제 제목에 단계 번호를 사용하지 않습니다.
• 가능하면 나중에 바뀔 수 있는 단어를 사용하지 않습니다.

링크와 제목 변경#

주제 제목을 바꾸면 앵커 링크가 바뀝니다. 다른 문서 페이지나 코드 파일이 이 앵커로 링크하고 있다면 파이프라인 job이 실패할 수 있습니다.

파이프라인 실패를 방지하려면 변경 사항을 푸시하기 전에 로컬에서 링크 검사를 실행하는 것을 고려합니다.

링크 텍스트#

링크 텍스트는 다음 지침을 따릅니다.

UI의 링크 텍스트 작성에 대해서는 Pajamas를 참고합니다.

표준 텍스트#

다음 패턴 중 하나를 따르는 텍스트를 사용합니다.

• 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)로 이어집니다.
• 유지 관리에 문제를 일으킵니다.

링크가 필요할 때도 있습니다. 문제 해결 단계를 명확히 하거나 콘텐츠 중복을 막는 데 도움이 될 수 있습니다. 더 정확하고 더 적극적으로 유지 관리되는 경우도 있습니다.

외부 링크를 추가할 때마다 고객에게 돌아가는 이점과 유지 관리의 어려움을 저울질합니다.

핸드북 링크#

핸드북으로 향하는 링크를 제한합니다. 라이선스 약관, 데이터 사용 및 접근 정책, 테스트 계약, 이용 약관처럼 피할 수 없는 링크도 있습니다.

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

다음으로 직접 링크하지 않습니다.

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

이러한 링크는 다음 경우에 실패합니다.

• 권한이 충분하지 않은 사용자.
• 자동화된 링크 검사기.

이러한 링크를 꼭 사용해야 한다면 다음을 따릅니다.

• 링크가 기밀 이슈나 내부 핸드북 페이지로 향한다면, 해당 이슈나 페이지가 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를 탐색하는 방법을 문서화할 때는 다음을 따릅니다.

• 항상 위치를 먼저 쓰고 동작을 씁니다.
  • From the Visibility dropdown list (location), select Public (action).
• 간결하고 구체적으로 씁니다. 예를 들면 다음과 같습니다.
  • 올바른 예: Select Save.
  • 잘못된 예: Select Save for the changes to take effect.
• 단계에 이유를 포함해야 한다면 이유로 단계를 시작합니다. 사용자가 더 빠르게 훑어볼 수 있습니다.
  • 올바른 예: To view the changes, in the merge request, select the link.
  • 잘못된 예: Select the link in the merge request to view the changes.

UI 요소 이름#

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

1. Top bar
2. Left sidebar: 사용자 인터페이스 왼쪽에 있는 탐색 사이드바입니다.
   • the **Explore** menu나 the **Your work** sidebar라는 표현을 사용하지 않습니다. 대신 the left sidebar를 사용합니다.
3. ... panel: 기본 컨텍스트에 따라 정해집니다. 예를 들어 컨텍스트가 머지 리퀘스트라면 merge request panel이라고 부릅니다.
4. Details panel: 기본 컨텍스트를 보조합니다. 선택한 이슈나 에픽에 한정됩니다.
5. GitLab Duo panel
6. GitLab Duo sidebar

right sidebar는 사용자 인터페이스 오른쪽에 있는 탐색 사이드바로, 열려 있는 이슈, 머지 리퀘스트, 에픽에 한정됩니다.

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

모든 UI 요소는 굵게 표시해야 합니다. 탐색 경로의 >는 굵게 표시하지 않습니다.

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

탐색 작업 단계 작성 방법#

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

프로젝트 설정을 여는 방법은 다음과 같습니다.

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

그룹 설정을 여는 방법은 다음과 같습니다.

1. In the top bar, select **Search or go to** and find your group.
1. In the left sidebar, select **Settings** > **CI/CD**.
1. 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.
1. In the left sidebar, select **Settings** > **CI/CD**.
1. Expand **General pipelines**.

프로젝트 또는 그룹 설정을 여는 방법은 다음과 같습니다.

1. In the top bar, select **Search or go to** and find your project or group.
1. In the left sidebar, select **Settings** > **CI/CD**.
1. 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**.
1. In the left sidebar, select **Settings** > **CI/CD**.

Your work 메뉴 항목을 여는 방법은 다음과 같습니다.

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

아바타를 선택하는 방법은 다음과 같습니다.

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

일부 드롭다운 목록에서 선택 내용을 저장하는 방법은 다음과 같습니다.

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

모든 프로젝트를 보는 방법은 다음과 같습니다.

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

모든 그룹을 보는 방법은 다음과 같습니다.

1. In the top bar, select **Search or go to**.
1. 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 키보드 단축키에 문서화되어 있습니다.

여러 필드를 한 번에 문서화#

UI 텍스트가 섹션의 필드를 충분히 설명한다면 모든 필드에 작업 단계를 넣지 않습니다. 대신 여러 필드를 하나의 작업 단계로 요약합니다.

Complete the fields라는 문구를 사용합니다.

예를 들면 다음과 같습니다.

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > Repository.
3. Expand Push rules.
4. Complete the fields.

여러 필드를 문서화하면서 필드 하나만 설명이 필요하다면 같은 단계에서 설명합니다.

1. Expand Push rules.
2. Complete the fields. Branch name must be a regular expression.

여러 필드를 설명하려면 순서 없는 목록 항목을 사용합니다.

1. Expand General pipelines.
2. Complete the fields.
   • Branch name must be a regular expression.
   • User must be a user with at least the Maintainer role.

삽화#

GitLab 문서는 두 가지 유형의 삽화를 사용합니다.

• 스크린샷: GitLab 사용자 인터페이스의 일부를 보여 주는 데 사용합니다.
• 다이어그램: 프로세스나 개체 간의 관계를 설명하는 데 사용합니다.

삽화는 독자가 개념, 복잡한 프로세스에서 자신의 위치, 또는 애플리케이션과 상호 작용하는 방법을 이해하는 데 도움이 될 수 있습니다. 다음과 같은 이유로 삽화는 최소한으로 사용합니다.

• 시간이 지나면 오래된 정보가 됩니다.
• 현지화하기 어렵고 비용이 많이 듭니다.
• 스크린 리더가 읽을 수 없습니다.

문서에 삽화를 꼭 사용해야 한다면 삽화는 다음 조건을 갖춰야 합니다.

• 텍스트를 보완하되 대체하지 않아야 합니다. 독자가 필요한 정보를 얻기 위해 삽화에만 의존해서는 안 됩니다.
• 앞선 텍스트에 도입 문장이 있어야 합니다. 예를 들어 The following diagram illustrates the product analytics flow:입니다.
• 접근할 수 있어야 합니다. 자세한 내용은 스크린샷과 다이어그램에 관한 지침을 참고합니다.
• 개인 식별 정보를 제외해야 합니다.

스크린샷#

관련 정보 중 일부를 텍스트로 전달할 수 없을 때 스크린샷으로 GitLab 사용자 인터페이스의 일부를 보여 줍니다.

스크린샷 캡처#

스크린샷을 찍을 때는 다음을 따릅니다.

• 스크린샷의 콘텐츠가 GitLab SAFE 프레임워크를 준수하는지 확인합니다. 확인하려면 SAFE 플로차트를 따릅니다.
• 가치를 제공하는지 확인합니다. lorem ipsum 텍스트를 사용하지 않습니다. 실제 시나리오에서 기능이 어떻게 사용될지 재현하고, 현실적인 텍스트를 사용합니다.
• 관련 UI만 캡처합니다. 불필요한 공백이나 요점을 설명하는 데 도움이 되지 않는 UI 영역은 포함하지 않습니다. GitLab의 사이드바는 바뀔 수 있으므로 꼭 필요한 경우가 아니면 스크린샷에 포함하지 않습니다.
• 작게 유지합니다. 화면 전체 너비를 보여 줄 필요가 없다면 보여 주지 않습니다. 브라우저 창 크기를 최대한 줄여 요소들을 가까이 두고 빈 공간을 줄입니다. 스크린샷의 크기를 가능한 한 작게 유지합니다.
• 이미지가 페이지에서 어떻게 렌더링되는지 검토합니다. 이미지를 로컬에서 미리 보거나 머지 리퀘스트의 리뷰 앱을 사용합니다. 이미지가 흐릿하거나 부담스럽지 않은지 확인합니다.
• 일관성을 유지합니다. 일관된 읽기 경험을 위해 문서 페이지에 이미 있는 다른 스크린샷과 맞춥니다. 탐색 테마가 기본 설정인 Neutral로, 구문 강조 테마도 기본 설정인 Light로 설정되어 있는지 확인합니다.

콜아웃 추가#

스크린샷에서 한 영역을 강조하려면 화살표를 사용합니다.

• 색상은 #EE2604를 사용합니다. macOS의 미리 보기 애플리케이션을 사용한다면 이 색이 기본 빨간색입니다.
• 선 굵기는 3pt를 사용합니다. macOS의 미리 보기 애플리케이션을 사용한다면 목록의 세 번째 선입니다.
• 다음 이미지에 나온 화살표 스타일을 사용합니다.
• 화살표가 여러 개라면 가능한 한 서로 평행하게 만듭니다.

이미지 요구 사항#

• 너비나 높이가 큰 스크린샷은 크기를 조정합니다.
  • 너비는 1000픽셀 이하여야 합니다.
  • 높이는 500픽셀 이하여야 합니다.
  • 크기를 조정하고 압축한 뒤에도 스크린샷이 여전히 선명한지 확인합니다.
• JPEG 대신 PNG 이미지를 사용합니다.
• 모든 이미지는 100KB 이하로 압축해야 합니다. 많은 경우 이미지 품질을 떨어뜨리지 않고도 25-50KB 이하로 줄일 수 있습니다.
• 이미지에 담긴 기능이나 개념을 설명하는 소문자 파일 이름으로 이미지를 저장합니다.
  • 이미지가 GitLab 인터페이스라면 image-name-vX_Y.png 형식에 따라 파일 이름 끝에 GitLab 버전을 붙입니다. 예를 들어 GitLab 19.2의 파이프라인 페이지에서 찍은 스크린샷이라면 pipelines-v19_2.png가 유효한 이름입니다.
  • 사용자 인터페이스의 일부를 포함하지 않는 삽화를 추가한다면 이미지가 추가된 릴리스에 해당하는 릴리스 번호를 붙입니다. 19.2 마일스톤에 추가된 MR이라면 삽화의 유효한 이름은 devops-diagram-v19_2.png입니다.
• 작업 중인 .md 문서가 있는 디렉터리와 같은 디렉터리에 img/라는 별도의 디렉터리를 만들어 이미지를 둡니다.
  • 외부에서 호스팅되는 이미지로 링크하지 않습니다. 사본을 내려받아 docs 디렉터리 안의 알맞은 img 디렉터리에 저장합니다.
• GIF는 https://ezgif.com/optimize 또는 유사한 도구로 압축합니다.

문서를 설명하기 위해 동영상을 링크하고 임베드하는 방법도 참고합니다.

이미지 압축#

문서에 추가하는 새 이미지는 압축합니다. 이렇게 하면 파일 크기를 줄이고 페이지 로딩 성능을 개선하는 데 도움이 됩니다.

크로스 플랫폼이며 오픈 소스인 pngquant를 사용할 수 있습니다. 공식 웹사이트를 방문해 사용하는 OS의 안내에 따라 설치합니다.

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

• macOS에서 자동으로 압축하려면 스크린샷을 80% 줄이는 간단한 요령을 참고합니다.
• 수동으로 압축하려면 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 형식으로 변환하려면 다음을 따릅니다.

1. 파일 형식을 확인합니다.

   file doc/user/img/problematic_file.png
   

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

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

2. GraphicsMagick을 사용해 파일을 PNG 형식으로 변환합니다.

   gm convert problematic_file.png corrected_file.png
   

3. 압축 스크립트를 다시 실행합니다.

원본이 JPEG 파일이었다면 PNG는 무손실 압축을 사용하고 JPEG는 손실 압축을 사용하므로 변환된 PNG 파일이 더 크게 나타날 수 있습니다.

이미지 삭제#

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

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

어디에서도 사용되지 않는 이미지는 월간 유지 관리의 일부로 정리됩니다.

애니메이션 이미지#

애니메이션 이미지(애니메이션 GIF 등)는 피합니다. 사용자에게 주의를 분산시키고 성가시게 할 수 있습니다.

사용자 인터페이스의 복잡한 상호 작용을 설명하면서 독자의 이해를 돕는 시각적 표현을 포함하고 싶다면 다음을 할 수 있습니다.

• 정적 이미지(스크린샷)를 사용하고, 필요하면 콜아웃을 추가해 화면의 한 영역을 강조합니다.
• 상호 작용을 담은 짧은 동영상을 만들어 링크합니다.

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

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

대체 텍스트#

대체 텍스트는 접근성 있는 경험을 제공합니다. 스크린 리더는 대체 텍스트로 이미지를 설명하며, 이미지를 내려받지 못하면 대체 텍스트가 표시됩니다.

대체 텍스트는 이미지의 내용이 아니라 이미지의 맥락을 설명해야 합니다. 페이지나 섹션의 주제와 관련된 맥락을 추가합니다. 누군가가 이미지를 볼 수 없는 상태에서 페이지를 읽고 상호 작용하도록 돕는다면 이미지에 대해 무엇이라고 말할지 생각해 봅니다.

올바른 예:

![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 태그가 없으면 의도가 모호합니다.

자동 스크린샷 생성기#

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

1. GitLab Development Kit(GDK)를 설정합니다.
2. 복제한 GitLab 리포지터리가 있는 하위 디렉터리(보통 gdk/gitlab)로 이동합니다.
3. GDK 데이터베이스가 완전히 마이그레이션되었는지 확인합니다: bin/rake db:migrate RAILS_ENV=development.
4. pngquant를 설치합니다. 자세한 내용은 도구 웹사이트를 참고합니다: pngquant
5. scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>을 실행합니다.
6. 스크립트의 it 매개변수로 정의한 gitlab/doc 위치를 기준으로 스크린샷의 위치를 확인합니다.
7. 새로 만든 스크린샷을 커밋합니다.

도구 확장#

스크린샷 생성기를 추가하려면 다음을 따릅니다.

1. spec/docs_screenshots 디렉터리에 확장자가 _docs.rb인 새 파일을 추가합니다.

2. 파일에 다음 정보를 추가합니다.

   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
   

3. 각 it 블록에 스크린샷을 저장할 경로를 추가합니다.

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

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

단일 요소 스크린샷

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

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

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

자체 스크립트를 만들 때 spec/docs_screenshots/container_registry_docs.rb를 가이드로 사용합니다.

다이어그램#

정보가 텍스트만으로 이해하기에 너무 복잡하다면 다이어그램으로 프로세스나 개체 간의 관계를 설명합니다.

다이어그램을 만들려면 다음 중 하나를 사용합니다.

• Mermaid(권장). 문서에서는 Mermaid 버전 11을 지원합니다.
• Draw.io.

Mermaid는 권장하는 다이어그램 도구이지만 모든 상황에 적합하지는 않습니다. 예를 들어 복잡한 다이어그램 요구 사항 때문에 이해하기 어려운 레이아웃이 만들어질 수 있습니다.

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

다이어그램 지침#

접근성 있고 유지 관리하기 쉬운 다이어그램을 만들려면 다음 지침을 따릅니다.

• 다이어그램을 단순하고 초점이 분명하게 유지합니다. 꼭 필요한 요소와 정보만 포함합니다.

• 요소를 구분할 때는 도형만 사용합니다. 다이어그램은 라이트 모드와 다크 모드에서 모두 호환되어야 하므로 색상으로 요소를 구분하지 않습니다.

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

  • 프로세스나 단계에는 직사각형.
  • 결정 지점에는 마름모.
  • 요소 간의 직접적인 관계에는 실선.
  • 요소 간의 간접적인 관계에는 점선.
  • 프로세스의 흐름이나 방향에는 화살표.

• 같은 요소를 나타내는 도형은 모양과 크기가 같아야 합니다.

• 다이어그램 요소에 명확한 레이블과 간단한 설명을 추가합니다.

• 텍스트가 있는 요소는 텍스트와 도형의 윤곽선 사이에 충분한 여백이 있는지 확인합니다. 필요하다면 도형과 다이어그램의 모든 유사한 도형의 크기를 키웁니다.

• 다이어그램에 제목과 간단한 설명을 포함합니다.

• 텍스트에는 GitLab Sans 글꼴을 사용하고, 대체 옵션으로 Google Inter 글꼴을 사용합니다.

• 복잡한 프로세스는 큰 다이어그램 하나 대신 단순한 다이어그램 여러 개를 만드는 것을 고려합니다.

• 다이어그램이 다양한 기기와 화면 크기에서 잘 표시되는지 검증합니다.

• 링크를 포함하지 않습니다. click 동작으로 다이어그램에 삽입한 링크는 GitLab의 링크 검사 도구로 테스트할 수 없습니다.

• 프로세스가 바뀌면 정확성을 유지하도록 문서나 코드와 함께 다이어그램을 업데이트합니다.

Mermaid로 다이어그램 만들기#

Mermaid 구문으로 다이어그램을 만드는 방법은 Mermaid 사용자 가이드와 Mermaid 사이트의 예시를 참고합니다.

Mermaid로 GitLab 문서용 다이어그램을 만들려면 다음을 따릅니다.

1. Mermaid Live Editor에서 다이어그램을 만듭니다.

2. Code 창의 내용을 복사해 mermaid 코드 블록으로 감싸 Markdown 파일에 붙여넣습니다. 자세한 내용은 Mermaid용 GitLab Flavored Markdown을 참고합니다.

3. 다이어그램 유형을 선언한 줄(flowchart나 sequenceDiagram 등)의 다음 줄에 접근성을 위해 다음 줄을 추가합니다.

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

   제목과 설명이 대체 텍스트 지침을 따르는지 확인합니다.

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

<div class="diagram-placeholder"><div class="diagram-placeholder-header">Mermaid 다이어그램 (5줄)</div><details><summary>소스 코드 보기</summary><pre><code>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 웹 애플리케이션이나 (비공식) VS Code Draw.io Integration 확장을 사용합니다. 두 도구 모두 같은 다이어그램 편집 경험을 제공하지만 웹 애플리케이션은 편집 가능한 예시 다이어그램을 제공합니다.

Draw.io로 만든 다이어그램은 일반 다이어그램 지침과 Draw.io 전용 지침을 준수해야 합니다.

Draw.io 지침#

Draw.io에서 다이어그램을 만들 때는 Mermaid로 만든 다이어그램과 시각적으로 일관되어야 합니다. 다음 규칙은 일반 다이어그램 지침에 추가되는 규칙입니다.

글꼴:

• 모든 텍스트에 Inter 글꼴을 사용합니다. 이 글꼴은 기본 글꼴에 포함되어 있지 않습니다. Inter 글꼴을 사용자 지정 글꼴로 추가하려면 다음을 따릅니다.
  1. 글꼴 드롭다운 목록에서 Custom을 선택합니다.
  2. Google fonts를 선택하고 Font name 텍스트 상자에 Inter를 입력합니다.

도형:

• 요소에는 직사각형 도형을 사용합니다.
• 플로차트에는 Flowchart 도형 컬렉션의 도형을 사용합니다.

웹 애플리케이션 사용#

Draw.io 웹 애플리케이션으로 다이어그램을 만들려면 다음을 따릅니다.

1. Draw.io 웹 애플리케이션에서 다이어그램을 만듭니다.
2. 다이어그램을 저장합니다.
   1. Draw.io 웹 애플리케이션에서 File > Export as > SVG를 선택합니다.
   2. Include a copy of my diagram: All pages 체크박스를 선택한 다음 Export를 선택합니다. Draw.io에서 편집할 수 있음을 나타내도록 파일 확장자 drawio.svg를 사용합니다.
3. SVG를 이미지로 문서에 추가합니다. 이러한 SVG는 SVG가 아닌 다른 이미지와 같은 Markdown을 사용합니다.

VS Code 확장 사용#

VS Code용 Draw.io Integration 확장으로 다이어그램을 만들려면 다음을 따릅니다.

1. 다이어그램을 담을 디렉터리에 접미사가 drawio.svg인 빈 파일을 만듭니다.

2. VS Code에서 파일을 열고 다이어그램을 만듭니다.

3. 파일을 저장합니다.

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

4. SVG를 이미지로 문서에 추가합니다. 이러한 SVG는 SVG가 아닌 다른 이미지와 같은 Markdown을 사용합니다.

이모지#

Markdown 이모지 형식(예: :smile:)은 어떤 목적으로도 사용하지 않습니다. 대신 GitLab SVG 아이콘을 사용합니다.

GitLab SVG 아이콘#

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

대부분의 경우 텍스트에서 아이콘은 피합니다. 다만 호버 텍스트가 UI 요소를 설명할 수 있는 유일한 방법이라면 아이콘을 사용합니다. 예를 들어 Delete나 Edit 버튼에는 호버 텍스트만 있는 경우가 많습니다.

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

• 피해야 할 표현: Select **Edit**. 렌더링 결과: Select ✏️ Edit.
• 대신 사용할 표현: Select **Edit** (). 렌더링 결과: Select Edit (✏️).

단어로 아이콘을 설명하지 않습니다.

• 피해야 할 표현: Select **Erase job log** (the trash icon).
• 대신 사용할 표현: Select **Erase job log** (). 렌더링 결과: Select Erase job log ([remove]).

버튼에 호버 텍스트가 없다면 아이콘을 설명합니다. 이어서 접근성을 개선하기 위해 버튼에 호버 텍스트를 추가하도록 UX 버그 이슈를 만듭니다.

• 피해야 할 표현: Select .
• 대신 사용할 표현: Select the vertical ellipsis (). 렌더링 결과: Select the vertical ellipsis (⋮).

동영상#

동영상이 오래되지 않았다면 GitLab YouTube 동영상 튜토리얼을 문서에 추가하는 것을 적극 권장합니다. 동영상은 문서를 대체해서는 안 되며 보완하거나 설명하는 역할을 해야 합니다. 동영상의 내용이 기능과 핵심 사용 사례에 필수적인데도 문서에서 충분히 다루지 않는다면 다음을 따릅니다.

• 이 세부 정보를 문서 텍스트에 추가합니다.
• 동영상을 검토하고 페이지를 업데이트하는 이슈를 만듭니다.

제품 리포지터리에 동영상을 업로드하지 않습니다. 대신 링크를 추가하거나 임베드합니다.

동영상 링크#

동영상으로 링크하려면 독자가 글을 읽기 전에 페이지에서 동영상을 훑어볼 수 있도록 YouTube 아이콘을 포함합니다. 링크 텍스트는 일반 지침을 따릅니다. 오래되었을 수 있는 동영상을 식별하는 데 도움이 되도록 링크 뒤에 동영상의 게시 날짜를 포함합니다.

<i class="fa-youtube-play" aria-hidden="true"></i>
For an overview, see [merge requests](https://link-to-video).
<!-- Video published on YYYY-MM-DD -->

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

동영상 임베드#

GitLab 문서 사이트는 임베드된 동영상을 지원합니다.

동영상은 GitLab 공식 YouTube 계정의 것만 임베드할 수 있습니다. 다른 출처의 동영상은 대신 링크합니다.

대부분의 경우 임베드된 동영상은 페이지에서 많은 공간을 차지하고 독자의 주의를 분산시킬 수 있으므로 동영상을 링크합니다.

동영상을 임베드하려면 다음을 따릅니다.

1. 이 절차의 코드를 복사해 Markdown 파일에 붙여넣습니다. 코드의 위와 아래에 빈 줄을 하나씩 둡니다. 코드를 편집하지 않습니다(공백을 제거하거나 추가하지 않습니다).
2. YouTube에서 표시하려는 동영상 URL로 이동합니다. 브라우저에서 일반 URL (https://www.youtube.com/watch?v=VIDEO-ID)을 복사하고 <div class="video-fallback"> 아래 줄의 동영상 제목과 링크를 바꿉니다.
3. YouTube에서 Share를 선택한 다음 Embed를 선택합니다.
4. <iframe> 소스(src) URL만 (https://www.youtube-nocookie.com/embed/VIDEO-ID) 복사하고, iframe 태그의 src 필드 내용을 바꿔 붙여넣습니다.
5. 오래되었을 수 있는 동영상을 식별하는 데 도움이 되도록 링크 아래에 동영상의 게시 날짜를 포함합니다.

leave a blank line here
<div class="video-fallback">
  See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
</div>

<figure class="video-container">
  <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>
<!-- Video published on YYYY-MM-DD -->
leave a blank line here

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

이 서식의 특징은 다음과 같습니다.

• figure 태그는 시맨틱 SEO에 필요하며 video-container 클래스는 동영상이 반응형으로 동작하고 다양한 모바일 기기에서 표시되도록 하는 데 필요합니다.
• <div class="video-fallback">은 GitLab Markdown 프로세서가 iframe을 지원하지 않기 때문에 /help에 필요한 폴백입니다. 문서 사이트에서는 숨겨지지만 /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` 알림의 서식을 지정하는 방법은
[기능 플래그 뒤에 배포된 기능 문서화](../feature_flags.md)를 참고합니다.

### 노트

노트는 드물게 사용합니다. 노트가 너무 많으면 주제를 훑어보기 어려워질 수 있습니다.

노트를 추가하는 대신 다음을 고려합니다.

- 문장을 문단의 일부가 되도록 다시 씁니다.
- 정보를 별도의 문단으로 만듭니다.
- 내용을 새 주제 제목 아래에 둡니다.

노트를 꼭 사용해야 한다면 다음 형식을 사용합니다.

```plaintext
<div class="admonition note"><div class="admonition-title">Note</div>

This is something to note.

</div>```

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

<div class="admonition note"><div class="admonition-title">Note</div>

This is something to note.

</div>

### 경고

지원 중단된 기능을 나타내거나 데이터 손실 가능성이 있는
절차에 대해 경고하려면 경고를 사용합니다.

```plaintext
<div class="admonition warning"><div class="admonition-title">Warning</div>

This is something to be warned about.

</div>```

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

<div class="admonition warning"><div class="admonition-title">Warning</div>

This is something to be warned about.

</div>

### 면책 조항

아직 제공하지 않은 기능에 대해 꼭 써야 한다면, 해당 콘텐츠 가까이에 미래 예측 진술에 대한 면책 조항을 추가합니다.

면책 조항 알림은 [템플릿](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/themes/gitlab-docs/layouts/shortcodes/alert.html)으로 채워지며
다른 텍스트를 포함하지 않아야 합니다.

다음과 같이 면책 조항을 추가합니다.

```plaintext

<div class="admonition warning"><div class="admonition-title">Disclaimer</div>

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

</div>

면책 조항 텍스트가 포함된 GitLab 문서 사이트에서는 다음과 같이 렌더링됩니다.

페이지의 모든 콘텐츠를 사용할 수 있는 것이 아니라면 페이지 맨 위에 미래 예측 진술에 대한 면책 조항을 한 번 사용합니다.

주제의 콘텐츠가 준비되지 않았다면 해당 주제에 면책 조항을 사용합니다.

자세한 내용은 향후 버전의 기능을 약속하는 표현을 참고합니다.

인용 블록#

제품 문서에서는 인용 블록을 사용하지 않도록 합니다. 인용 블록은 텍스트를 훑어보기 어렵게 만들 수 있습니다. 인용 블록 대신 다음을 사용하는 것을 고려합니다.

• 코드 블록.
• 알림 상자.
• 특별한 스타일을 전혀 적용하지 않은 텍스트.

GitLab Flavored Markdown(GLFM) 페이지는 일반 텍스트와 렌더링된 예시를 구분하기 위해 인용 블록을 사용하는 드문 경우입니다. 하지만 대부분의 경우 인용 블록은 피해야 합니다.

탭#

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

탭 세트를 만들려면 다음 예시를 따릅니다.

Here's some content in tab one.





Here's some other content in tab two.

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

탭 제목은 간결하고 일관되게 씁니다. 병렬 구조로 만들고 각 제목을 대문자로 시작합니다. 예를 들면 다음과 같습니다.

• Linux package (Omnibus), Helm chart (Kubernetes) (구성 편집을 문서화할 때는 구성 편집 가이드를 따릅니다)
• 15.1 and earlier, 15.2 and later

탭으로 향하는 깨진 링크에 대한 자동화된 테스트를 구현하기 전까지는 단일 탭으로 직접 링크하지 않습니다. 자세한 내용은 이슈 225를 참고합니다.

탭에 대한 자세한 내용은 Pajamas를 참고합니다.

접을 수 있는 패널#

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

This content appears inside the collapsible panel.

접을 수 있는 패널은 GitLab Duo 페이지의 가용성 정보 섹션에서 지원되는 LLM, 편집기, 자체 호스팅 모델 제공 여부에 관한 정보에만 사용합니다.

다른 콘텐츠에는 접을 수 있는 패널을 사용하지 않습니다.

카드#

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

카드 세트를 만들려면 다음 예시를 따릅니다.

- [The first page](first_page.md)
- [Another page](another/page.md)
- [One more page](one_more.md)

또한 카드는 선택적 설명이 있는 외부 URL도 지원합니다. 다음 구문을 사용합니다.

- [External page title](https://example.com "Optional Description")

카드는 GitLab 문서 사이트(https://docs.gitlab.com)에서만 렌더링됩니다. GitLab 제품 도움말에서는 카드 세트가 링크의 순서 없는 목록으로 표시됩니다.

카드 설명은 Markdown 페이지 헤더의 description 메타데이터에서 가져옵니다.

카드는 카드만 콘텐츠로 있는 최상위 페이지에서 사용합니다.

유지 관리 버전#

maintained versions 쇼트코드를 사용하면 유지 관리 정책에 지정된 현재 유지 관리 중인 GitLab 버전의 순서 없는 목록을 만듭니다.

유지 관리 버전은 GitLab 문서 사이트(https://docs.gitlab.com)의 프리릴리스 버전에서만 렌더링됩니다. 그 외의 모든 경우와 /help에서는 대신 문서 사이트로 향하는 링크가 표시됩니다.

용어집 툴팁#

용어집 툴팁 쇼트코드를 사용하면 마우스를 올렸을 때 툴팁으로 나타나는 짧은 정의를 제공할 수 있습니다. 예를 들면 다음과 같습니다.

To do this thing, use .

사용자가 에 마우스를 올리면 툴팁이 표시됩니다.

툴팁에 용어집 페이지가 구성되어 있고 사용자가 앵커 텍스트를 선택하면 관련 용어집 페이지가 열립니다.

사용 지침#

정의가 간결한 한 문장이라면 용어집 툴팁을 사용하고, 60자 이하로 쓰도록 합니다. 정의가 더 길다면 용어집 페이지를 사용합니다.

한 페이지에 툴팁을 다섯 개에서 열 개 넘게 사용하지 않습니다. 툴팁은 하나하나가 독자의 속도를 늦춥니다. 사용자에게 정의가 과도하게 쌓이지 않도록 주의합니다.

다음과 같은 경우에 용어집 툴팁을 사용합니다.

• 페이지에서 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

: 선택 사항입니다. 용어의 용어집 정의로 향하는 링크입니다. 포함하면 term_id가 glossary_url 끝에 덧붙습니다. 예를 들어 /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로 구성됩니다.

1. 용어집의 짧은 이름.
2. 용어집의 더 긴 식별자. 이 용어집으로 연결되는 용어집 용어는 glossary 필드가 이 값과 일치해야 합니다.

glossary_url

: 용어가 정의된 용어집 페이지의 루트 URL입니다.

glossary.yaml 파일의 용어집 정의 예시는 다음과 같습니다.

# Glossary files
security: &security_glossary
  glossary_url: "/user/application_security/terminology"

이 예시들을 결합하면 다음과 같은 결과가 나타납니다.

• "Attack Surface"라는 문구가 문서에 링크로 표시됩니다.
• 사용자가 링크에 마우스를 올리면 short_description 필드의 내용이 툴팁에 표시됩니다.
• 사용자가 링크를 선택하면 용어집 페이지가 앵커 attack-surface 위치에서 열립니다.

표절#

출처를 밝힌 제한적인 인용이 아니라면 다른 출처의 콘텐츠를 복사해 붙여넣지 않습니다. 일반적으로 관련 정보를 자신의 말로 바꿔 쓰거나 출처로 링크하는 것이 더 좋습니다.

AI 생성 콘텐츠#

AI 도구를 사용해 문서를 생성하거나 작성을 보조할 때는 검토를 요청하기 전에 결과물을 주의 깊게 확인합니다. AI는 설득력 있게 쓰도록 설계되었지만 AI 생성 콘텐츠에는 다음과 같은 문제가 자주 나타납니다.

반복 : 페이지나 링크된 주제에서 이미 말한 내용을 다시 서술하는 콘텐츠입니다. 각 섹션은 새로운 정보를 더해야 합니다. 방금 설명한 내용을 요약하지 않습니다. 첫 문단에서 제목이나 소개를 다시 서술하지 않습니다.

모호하거나 검증할 수 없는 주장 : 코드베이스나 기존 문서에 근거하지 않은 기능 작동 방식의 설명입니다. 기존 코드베이스, 링크된 문서, 페이지에 이미 있는 콘텐츠에 근거할 수 있는 정보만 포함합니다. 기능의 작동 방식을 추측하거나 추론하지 않습니다. 명령 구문, API 매개변수, UI 요소 이름을 지어내지 않습니다.

잘못된 범위 : 적합한 페이지가 이미 있는데도 개념이나 절차를 위한 새 페이지를 만든 경우입니다. 하나의 개념, 용어, 절차 단계를 위해 새 페이지를 만들지 않습니다.

향후 버전의 기능 약속#

향후 릴리스에서 기능을 제공하겠다고 약속하지 않습니다. 예를 들어 "Support for this feature is planned."와 같은 표현은 피합니다.

향후 기능 작업은 보장할 수 없으며, 이러한 약속은 법적 문제를 일으킬 수 있습니다. 대신 이슈가 있다고 말합니다. 예를 들면 다음과 같습니다.

• Support for improvements is proposed in [issue <issue_number>](https://link-to-issue).
• You cannot do this thing, but [issue 12345](https://link-to-issue) proposes to change this behavior.

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

향후 기능을 꼭 문서화해야 한다면 면책 조항을 사용합니다.

제품과 기능#

GitLab 제품 문서에서 제품과 기능을 설명할 때는 이 섹션의 정보를 참고합니다.

이름 안에서 줄 바꿈 피하기#

기능이나 제품 이름에 공백이 있더라도 줄 바꿈으로 이름을 나누지 않습니다. 이름이 바뀔 때 줄 바꿈이 있는 텍스트는 검색하거나 grep하기가 더 복잡해집니다.

제품 가용성 정보#

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

자세한 내용은 제품 가용성 정보를 참고합니다.

특정 섹션#

특정 섹션에는 일정한 스타일을 적용해야 합니다. 특정 섹션의 스타일은 이 섹션에서 설명합니다.

도움말 및 피드백 섹션#

이 섹션은 각 문서의 끝에 표시되며 프론트 매터에 키를 추가해 생략할 수 있습니다.

---
feedback: false
---

기본값은 이 섹션을 그대로 두는 것입니다. 문서에서 이 섹션을 생략하려면 그 전에 반드시 테크니컬 라이터와 확인해야 합니다.

GitLab 재시작#

GitLab의 재시작이나 재구성이 필요할 때는 다음과 같은 텍스트로 doc/administration/restart_gitlab.md로 링크해 중복을 피합니다. 필요에 따라 'reconfigure'를 'restart'로 바꿉니다.

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을 재구성하거나 재시작하는 마지막 단계는 매번 같으므로 그대로 사용할 수 있습니다.

구성 편집을 설명할 때는 이 스니펫을 필요에 따라 편집해 사용합니다.

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

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

1. Save the file and reconfigure GitLab:

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





1. Export the Helm values:

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

1. Edit `gitlab_values.yaml`:

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

1. Save the file and apply the new values:

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





1. Edit `docker-compose.yml`:

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

1. Save the file and restart GitLab:

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





1. Edit `/home/git/gitlab/config/gitlab.yml`:

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

1. Save the file and restart GitLab:

   ```shell
   # For systems running systemd
   sudo systemctl restart gitlab.target

   # For systems running SysV init
   sudo service gitlab restart
   ```

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