글로벌 탐색

도입(Introduced): GitLab 11.6에서.
업데이트(Updated): GitLab 12.1에서.
프로젝트별 탐색은 GitLab 12.2에 추가되었습니다.
통합된 글로벌 탐색은 GitLab 13.11에 추가되었습니다.

글로벌 탐색은 문서에서 가장 왼쪽에 있는 패널입니다. “글로벌 탐색”을 사용하여 콘텐츠를 찾을 수 있습니다.

연구에 따르면, 사람들은 GitLab 제품 문서를 찾기 위해 구글을 사용합니다. 결과 페이지에 접속했을 때, 그들이 읽고 있는 내용과 관련된 인근 주제를 찾을 수 있기를 희망합니다. 글로벌 탐색은 이 정보를 제공합니다.

최상위 수준에서, 우리의 글로벌 탐색은 워크플로 기반입니다. 탐색은 사용자가 GitLab을 사용하는 방법에 대한 정신적 모델을 구축하는 데 도움이 되어야 합니다. 더 높은 워크플로 기반 주제 아래의 수준은 기능의 이름입니다.
예를 들어:

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

일부 구석진 섹션은 알파벳 순으로 정렬됩니다만, 주로 탐색은 워크플로 기반으로 되어야 합니다.

내비게이션 항목을 추가하지 않았을 때:

페이지가 열렸을 때 내비게이션이 닫히고, 독자는 현재 위치를 잃습니다.
페이지가 다른 페이지와 함께 그룹에서 보이지 않습니다.

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

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

내비게이션 항목은 페이지 제목과 일치해야 합니다. 그러나, 제목이 너무 길 경우, 구문을 줄일 때 Merge Request과 같이:

명사, 예를 들어 Merge Request.
능동적 동사, 예를 들어 GitLab 설치 또는 러너로 시작하기.

페이지의 용도를 명확히 나타내는 구문을 사용하세요. 예를 들어, 시작하기는 러너로 시작하기만큼 유용하지 않습니다.

내비게이션 항목 추가

기술 작가 중 한 명의 동의 없이는 글로벌 내비게이션에 항목을 추가하지 마십시오.

글로벌 내비게이션에 주제를 추가하려면:

navigation.yaml 파일에 항목을 추가하세요.
검토 및 Merge을 위해 기술 작가에게 MR(Merge Request)를 할당하세요.

추가할 위치

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

GitLab 사용자. 이것은 기능 설정부터 소유자까지 모든 권한 수준의 사용자를 위한 GitLab의 일상적인 사용에 대한 문서입니다.
GitLab 관리자. 이것은 GitLab을 호스팅하는 기본 인프라에 액세스를 요구하는 Self-managed 인스턴스를 위한 문서입니다.
기타 문서. 이것은 GitLab의 일상적인 사용 이외의 고객 및 기여자를 위한 문서 및 기여자에 대한 문서를 포함합니다. 다른 그룹에 맞지 않는 문서는 여기에 속합니다.

이러한 그룹을 염두에 두고, 새로운 항목을 추가해야 할 일반적인 규칙은 다음과 같습니다.

사용자 문서는:
- 그룹 수준의 기능은 그룹에 속합니다.
- 프로젝트 수준의 기능은 프로젝트에 속합니다.
- 그룹 또는 프로젝트 수준 밖의 기능(가끔 “인스턴스 수준”이라고 함)은 최상위 수준에 배치될 수 있지만, 해당 최상위 공간을 압도하지 않도록 주의해야 합니다. 가능하다면 이러한 기능은 어떤 방식으로든 그룹화될 수 있습니다.
- 위의 조건을 만족하지 않는 대부분의 그 외 잡다한 사용자 문서는 사용자 아래에 속합니다.
관리 문서는 관리자 아래에 속합니다.
그 외의 문서는 최상위 수준에 속합니다만, 해당 최상위 내비게이션을 몹시 길게 만들면 그 목적을 저해하기 때문에 주의해야 합니다.

이러한 원칙에 따라 모든 문서 및 내비게이션 항목을 만들도록 진행 중입니다.

추가할 내용

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

독자가 볼 수 있는 내비게이션 항목 텍스트는:
- 가능한 짧아야 합니다.
- 맥락적이어야 합니다. 부모 항목의 텍스트를 반복할 필요는 거의 없습니다.
- 만약 널리 사용되지 않는다면 전문 용어나 기술 용어를 피해야 합니다. 예를 들어, 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: 텍스트
    section_url: '링크'

섹션은 독립적일 수도 있고 내부에 카테고리를 포함할 수 있습니다.

카테고리

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

하나의 독립적인 카테고리 예제가 있는 섹션:

- section_title: 섹션 제목
  section_url: '섹션-링크'
  section_categories:
    - category_title: 카테고리 제목
      category_url: '카테고리-링크'

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

- section_title: 섹션 제목
  section_url: '섹션-링크'
  section_categories:
    - category_title: 카테고리 1 제목
      category_url: '카테고리-1-링크'
    
    - category_title: 카테고리 2 제목
      category_url: '카테고리-2-링크'

명확한 이해를 위해, 항상 카테고리 간에 빈 줄을 추가하십시오.

문서

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

각 수준에서 하나의 문서 링크가있는 예제:

- category_title: 카테고리 제목
  category_url: '카테고리-링크'
  docs:
    - doc_title: 문서 제목
      doc_url: '문서-링크'
      docs:
      - doc_title: 문서 제목
        doc_url: '문서-링크'
        docs:
        - doc_title: 문서 제목
          doc_url: '문서-링크'

카테고리는 필요한만큼 많은 문서를 지원하지만, 명확성을 위해 한 카테고리에 너무 많은 항목을 넣지 않도록 하십시오. 또한 세 단계 이상의 문서를 사용하지 마십시오. 지원되지 않습니다.

여러 문서가있는 예제:

- category_title: 카테고리 제목
  category_url: '카테고리-링크'
  docs:
    - doc_title: 문서 1 제목
      doc_url: '문서-1-링크'
    - doc_title: 문서 2 제목
      doc_url: '문서-2-링크'

외부 URL의 문서를 추가해야하는 경우, 문서 링크 아래에 external_url 속성을 추가하십시오:

- doc_title: 문서 2 제목
  doc_url: '문서-2-링크'
  external_url: true

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

예시:

- category_title: 오퍼레이션
  category_url: 'ee/user/project/integrations/prometheus_library/'
  # 오퍼레이션의 링크가 있을 때까지, 첫 번째 문서 링크가
  # 카테고리 링크에서 반복됩니다.
  docs:
    - doc_title: 지표
      doc_url: 'ee/user/project/integrations/prometheus_library/'

구문

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

제목

기능 이름의 첫 글자만 대문자로 사용하십시오.
특수 문자가 없는 한 제목을 래핑 할 필요는 없습니다. 예를 들어, GitLab CI/CD에서 /이 있기 때문에 다음과 같이 제목을 래핑해야합니다. 관습적으로 제목을 이중 따옴표로 감싸십시오: category_title: "GitLab CI/CD".

URL

URL은 상대적이거나 외부적 일 수 있으며 다음을 적용합니다:

데이터 파일의 모든 링크는 .html로 끝나야하며 (예외 .md가 아님), .md 아닙니다.
index.html 파일의 경우 clean (canonical) URL을 사용합니다: path/to/. 예를 들어, https://docs.gitlab.com/ee/install/index.html은 ee/install/로 변환됩니다.
상대적인 링크를 슬래시 /로 시작하지 마십시오.
관습적으로 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로 설정됩니다. 링크의 글꼴 크기, 패딩, 색상 등을 조절하려면 이러한 클래스를 사용하세요. 이렇게 함으로써 각 링크의 규칙이 스타일시트의 다른 규칙과 충돌하지 않도록 보장합니다.