글로벌 내비게이션

글로벌 내비게이션은 문서에서 가장 왼쪽에 있는 창입니다. “글로벌 내비게이션”을 사용하여 콘텐츠를 탐색할 수 있습니다.

연구에 따르면, 사람들은 GitLab 제품 문서를 검색하기 위해 Google을 사용합니다. 그들이 결과물에 접속했을 때, 우리는 그들이 읽고 있는 내용과 관련된 근처 주제를 찾을 수 있도록 하고 싶습니다. 글로벌 내비게이션은 이러한 정보를 제공합니다.

가장 높은 수준에서 우리의 글로벌 내비게이션은 워크플로우 기반입니다. 내비게이션은 사용자들이 GitLab을 사용하는 방법에 대한 주요 한정 모델을 구축하는 데 도움이 되어야 합니다. 더 높은 워크플로우 기반 주제 각각 아래의 수준은 기능의 이름입니다. 예를 들어:

GitLab 사용하기 (워크플로우) > 애플리케이션 빌드하기 (워크플로우) > CI/CD (기능) > 파이프라인 (기능)

내비게이션에 있는 일부 오래된 섹션들은 알파벳순으로 되어 있지만, 내비게이션은 주로 워크플로우 기반으로 되어야 합니다.

내비게이션 항목이 없는 경우:

페이지가 열릴 때 내비게이션이 닫히고, 독자는 자신의 위치를 잃게 됩니다.
페이지가 다른 페이지와 함께 그룹에 나타나지 않습니다.

내비게이션 항목에 적절한 단어 선택하기

왼쪽 내비게이션에 항목을 추가하기 전에, 사용할 품사를 선택하세요.

내비게이션 항목은 페이지 제목과 일치해야 합니다. 그러나, 제목이 너무 길 경우, 구문을 줄일 때 다음 중 하나를 사용하세요:

Merge Request(Merge requests)와 같이 명사를 사용합니다.
GitLab 설치(Install GitLab) 또는 러너로 시작하기(Get started with runners)와 같이 능동적인 동사를 사용합니다.

페이지가 어떤 용도인지 명확히 나타내는 구문을 사용하세요. 예를 들어, 시작하기(Get started)는 러너로 시작하기(Get started with runners)만큼 도움이 되지 않습니다.

내비게이션 항목 추가하기

기술 작가 중 한 명의 승인 없이 글로벌 내비게이션에 항목을 추가하지 마세요.

글로벌 내비게이션에 주제를 추가하려면 다음을 수행하세요:

navigation.yaml 파일에 항목을 추가합니다.
기술 작가에게 검토 및 Merge을 위임합니다.

추가할 위치

문서 페이지는 다음 그룹에 속한다고 말할 수 있습니다:

GitLab 사용자. 이는 보고자부터 소유자까지 모든 권한 수준의 사용자를 위한 GitLab의 일상적인 사용에 대한 문서입니다.
GitLab 관리자. 이는 GitLab을 호스팅하는 기반이 되는 기반이 필요한 Self-Managed형 인스턴스에 대한 문서입니다.
기타 문서. 이는 GitLab의 일상적인 사용 이외의 고객 및 기여자를 위한 문서를 포함하며, 다른 그룹에 맞지 않는 문서가 여기에 속합니다.

이러한 그룹들을 염두에 두고, 새 항목이 어디에 추가되어야 하는지에 대한 일반 규칙은 다음과 같습니다.

사용자 문서:
- 그룹 수준 기능은 그룹(Groups) 아래에 속합니다.
- 프로젝트 수준 기능은 프로젝트(Projects) 아래에 속합니다.
- 그룹 또는 프로젝트 수준 이외의 기능(가끔 “인스턴스 수준”이라고도 함)은 최상위 수준에 배치될 수 있지만, 최상위 공간이 지나치게 많아지지 않도록 주의가 필요합니다. 가능하다면 이러한 기능은 어떠한 방식으로든 그룹화될 수 있어야 합니다.
- 위의 경우 외에도 대부분의 기타 잡다한 사용자 문서는 사용자(User) 아래에 속합니다.
관리 문서는 관리자(Administrator) 아래에 속합니다.
기타 문서는 최상위 수준에 속합니다. 그러나, 최상위 내비게이션이 지나치게 길어지는 것을 피해야 합니다.

모든 문서와 내비게이션 항목이 이러한 원칙을 준수하도록 하는 것이 점진적으로 이루어지고 있습니다.

추가할 항목

내비게이션 요소를 추가할 위치를 결정한 후, 다음 단계는 무엇을 추가해야 하는지 결정하는 것입니다. 무엇이 필요한지에 대한 내용은 아래에 문서화되어 있지만, 원칙적으로:

독자가 볼 수 있는 내비게이션 항목 텍스트는 다음과 같아야 합니다:
- 가능한 한 짧아야 합니다.
- 문맥상 확인할 수 있어야 합니다. 부모 항목의 텍스트를 반복할 필요는 드뭅니다.
- 널리 사용되는 용어나 전문 용어를 피하세요. 예를 들어, CI는 Continuous Integration 대체어로 사용할 수 있습니다.
내비게이션 링크는 데이터 파일에 기술된 규칙을 따라야 합니다.

추가할 필요가 없는 페이지

다음 페이지들은 글로벌 내비게이션에서 제외하세요:

법적 고지.
architecture/blueprints 디렉터리에 있는 페이지들.
user/application_security/dast/checks/ 디렉터리에 있는 페이지들.

다음 페이지들은 아마 글로벌 내비게이션에 포함되어야 하지만, 기술 작가들은 능동적으로 이들을 추가하지는 않습니다:

/development 디렉터리에 있는 페이지들.
지원 팀이 작성한 페이지는 doc/administration/troubleshooting 디렉터리에 있습니다.

가끔 폐기된 기능에 대한 페이지는 글로벌 내비게이션에 포함되지 않을 수 있습니다. 이는 해당 기능이 얼마나 오래 전에 폐기되었느냐에 따라 다릅니다.

다른 모든 페이지는 글로벌 내비게이션에 포함되어야 합니다.

기술 작가 팀은 내비게이션에 없는 페이지를 확인하기 위해 보고서를 실행합니다. 팀은 매월이 디렉터리을 검토합니다.

내비게이션 구조

글로벌 내비게이션은 다섯 단계로 구성됩니다:

섹션
- 카테고리
  - 문서
    - 문서
      - 문서

이 구조는 navigation.yml 파일에서 확인할 수 있습니다.

구성

글로벌 내비게이션은 두 파일에서 구성됩니다:

데이터
레이아웃

데이터 파일은 레이아웃에 문서에 대한 링크를 제공합니다. 레이아웃은 데이터를 네비게이션 내에서 적절하게 구성합니다. 스타일에 따라서도 데이터가 구성됩니다.

데이터 파일

데이터 파일은 해당 프로젝트의 내비게이션 구조를 설명합니다. 이 파일은 https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml에 저장되어 있으며, 다음 세 가지 주요 컴포넌트로 구성됩니다:

섹션
카테고리
문서

섹션

각 섹션은 더 높은 수준의 내비게이션 항목을 나타냅니다. 제목과 URL로 구성됩니다:

sections:
  - section_title: Text
    section_url: 'link'

섹션은 독립적으로 또는 내부에 카테고리를 포함할 수 있습니다.

카테고리

섹션 내의 각 카테고리는 내비게이션의 두 번째 수준으로 구성됩니다. 카테고리 제목과 링크를 포함합니다. 내비게이션 내에서 독립적으로 서 있을 수도 있고, 세 단계 이내의 하위 항목을 포함할 수도 있습니다.

독립된 카테고리가 있는 섹션의 예:

- section_title: Section title
  section_url: 'section-link'
  section_categories:
    - category_title: Category title
      category_url: 'category-link'

독립된 카테고리가 두 개 있는 섹션의 예:

- section_title: Section title
  section_url: 'section-link'
  section_categories:
    - category_title: Category 1 title
      category_url: 'category-1-link'
    
    - category_title: Category 2 title
      category_url: 'category-2-link'

분명성을 위해 카테고리 간에 항상 빈 줄을 추가하세요.

문서

각 문서는 내비게이션의 세 번째, 네 번째, 다섯 번째 수준의 링크를 나타냅니다. 항상 카테고리 내부에 추가해야 합니다.

세 단계의 각 수준에서 문서 링크가 하나씩 있는 예:

- category_title: Category title
  category_url: 'category-link'
  docs:
    - doc_title: Document title
      doc_url: 'doc-link'
      docs:
      - doc_title: Document title
        doc_url: 'doc-link'
        docs:
        - doc_title: Document title
          doc_url: 'doc-link'

한 카테고리는 필요한 만큼의 문서를 지원하지만, 명확성을 위해 카테고리를 지나치게 많이 채우지 않도록 하세요. 또한, 세 단계를 넘는 문서는 사용할 수 없습니다.

여러 문서가 있는 예:

- category_title: Category title
  category_url: 'category-link'
  docs:
    - doc_title: Document 1 title
      doc_url: 'doc-1-link'
    - doc_title: Document 2 title
      doc_url: 'doc-2-link'

외부 URL에 있는 문서를 추가해야 할 경우, 문서 링크 아래에 external_url 속성을 추가하세요:

- doc_title: Document 2 title
  doc_url: 'doc-2-link'
  external_url: true

모든 내비게이션 링크는 선택 가능해야 합니다. 더 높은 수준의 링크가 자체 링크가 없는 경우, 그것은 첫 번째 하위 항목 링크로 이동하여 GitLab 내비게이션을 흉내 내지 않아야 합니다. 이것은 중복된 링크나 동시에 두 개 이상의 .active 링크를 가지지 않도록 피해야 합니다.

예시:

- category_title: Operations
  category_url: 'ee/user/project/integrations/prometheus_library/'
  # operations에 대한 링크가 없을 때, 첫 번째 doc 링크가
  # 카테고리 링크에 반복됩니다.
  docs:
    - doc_title: Metrics
      doc_url: 'ee/user/project/integrations/prometheus_library/'

구문

모든 컴포넌트(섹션, 카테고리 및 문서)에 대해 들여쓰기를 준수하고 다음 구문 규칙을 따릅니다.

제목

기능 이름을 대문자로 사용하는 문장 케이스를 사용합니다.
제목을 래핑할 필요가 없으며, 특수 문자가 있지 않은 경우입니다. 예를 들어 GitLab CI/CD의 경우 /이 있으므로 이를 따옴표로 래핑해야 합니다. 관례상 제목은 이중 인용부호로 래핑합니다: category_title: "GitLab CI/CD".

URL

URL은 상대적이거나 외부일 수 있으며 다음이 적용됩니다.

데이터 파일의 모든 링크는 .md가 아닌 .html로 끝나야 합니다. (예외: index.html 파일)
index.html 파일의 경우 클린 (카노니컬) URL을 사용합니다: path/to/. 예를 들어, https://docs.gitlab.com/ee/install/index.html은 ee/install/로 변환됩니다.
상대적 링크를 슬래시 /로 시작하지 않습니다.
관례상 URL을 항상 작은 따옴표로 래핑합니다 'url'.
링크를 추가하는 프로젝트 접두어를 항상 사용합니다. 전역 내비게이션 링크를 찾으려면 전체 URL에서 https://docs.gitlab.com/을 제거합니다.
GitLab Design System과 같이 외부 URL에 링크되는 경우 다음과 같이 속성 external_url: true를 추가합니다.
```
- category_title: GitLab Design System
  category_url: 'https://design.gitlab.com'
  external_url: true
```

상대적 URL의 예:

전체 URL	글로벌 내비게이션 URL
`https://docs.gitlab.com/ee/api/avatar.html`	`ee/api/avatar.html`
`https://docs.gitlab.com/ee/install/index.html`	`ee/install/`
`https://docs.gitlab.com/omnibus/settings/database.html`	`omnibus/settings/database.html`
`https://docs.gitlab.com/charts/installation/deployment.html`	`charts/installation/deployment.html`
`https://docs.gitlab.com/runner/install/docker.html`	`runner/install/docker.html`

레이아웃 파일 (로직)

레이아웃은 데이터 파일에서 공급받아 전역 내비게이션을 작성하며 기본 레이아웃에 의해 렌더링됩니다.

글로벌 내비게이션에는 네 개의 상위 프로젝트에서 나온 링크가 포함되어 있습니다. 전역 내비게이션 URL은 변경하는 문서 파일에 따라 다른 접두사가 있습니다.

리포지터리	링크 접두어	최종 URL
https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc	`ee/`	`https://docs.gitlab.com/ee/`
https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc	`omnibus/`	`https://docs.gitlab.com/omnibus/`
https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs	`runner/`	`https://docs.gitlab.com/runner/`
https://gitlab.com/charts/gitlab/tree/master/doc	`charts/`	`https://docs.gitlab.com/charts/`

CSS 클래스

내비게이션은 일반 stylesheet.scss에서 스타일이 지정됩니다. 스타일을 변경하려면 팀 내에서 더 나은 개발을 위해 그룹화된 상태로 유지합니다.

URL 컴포넌트는 각각의 고유한 스타일을 갖도록 CSS 클래스 .level-0, .level-1, 및 .level-2로 설정됩니다. 링크의 글꼴 크기, 패딩, 색상 등을 조정하려면 이러한 클래스를 사용합니다. 이렇게 함으로써 각 링크의 규칙이 스타일시트의 다른 규칙과 충돌하지 않도록 보장합니다.