글로벌 내비게이션

글로벌 내비게이션(global nav)은 문서의 가장 왼쪽 면입니다. 글로벌 내비게이션을 사용하여 콘텐츠를 탐색할 수 있습니다.

연구에 따르면 사람들은 GitLab 제품 문서를 검색하기 위해 Google을 사용합니다. 그들이 결과에 도달하면, 우리가 원하는 것은 그들이 읽고 있는 콘텐츠와 관련된 인근 주제를 찾는 것입니다. 글로벌 내비게이션은 이 정보를 제공합니다.

가장 높은 수준에서 우리의 글로벌 내비게이션은 워크플로 기반입니다. 내비게이션은 사용자가 GitLab을 사용하는 방법에 대한 정신 모델을 구축하는 데 도움이 되어야 합니다.

각 상위 워크플로 기반 주제 아래의 수준은 기능의 이름입니다. 예를 들어:

Use GitLab (workflow) > Build your application (workflow) > Get started (feature) > CI/CD (feature) > Pipelines (feature)

일부 오래된 내비게이션 섹션이 알파벳 순이긴 하지만, 내비게이션은 주로 워크플로 기반이어야 합니다.

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

  • 페이지가 열리면 내비게이션이 닫히고 독자는 자신의 위치를 잃게 됩니다.
  • 페이지가 다른 페이지와 그룹으로 보이지 않습니다.

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

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

내비게이션 항목은 페이지 제목과 일치해야 합니다. 그러나 제목이 너무 길면,

구를 줄일 때는 다음 중 하나를 사용하세요:

  • Merge requests와 같은 명사.
  • Install GitLab 또는 Get started with runners와 같은 능동 동사.

페이지의 용도를 명확히 나타내는 구를 사용하세요. 예를 들어, Get started는 Get started with runners만큼 유용하지 않습니다.

내비게이션 항목 추가하기

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

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

  1. navigation.yaml 파일에 항목을 추가하세요.
  2. 검토 및 병합을 위해 MR을 기술 작가에게 할당하세요.

어디에 추가할지

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

  • GitLab 사용자. 이는 Reporter에서 Owner까지 다양한 권한을 가진 사용자를 위한 GitLab의 일상적인 사용을 위한 문서입니다.
  • GitLab 관리자. 이는 GitLab 호스팅을 위한 기본 인프라에 대한 액세스가 필요한 자가 관리 인스턴스에 대한 문서입니다.
  • 기타 문서. 이는 GitLab을 일상적으로 사용하는 고객 이외의 문서와 기여자를 위한 문서를 포함합니다. 다른 그룹에 적합하지 않은 문서는 여기에 포함됩니다.

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

  • 사용자 문서는 Use GitLab에 속해야 합니다.
  • 관리 문서는 Administer 아래에 있어야 합니다.
  • 기타 문서는 최상위에 위치해야 하지만, 목적을 무력화하는 불필요하게 긴 최상위 내비게이션을 생성하지 않도록 주의해야 합니다.

모든 문서와 내비게이션 항목이 이러한 원칙을 준수하도록 하는 작업은 점진적으로 진행되고 있습니다.

무엇을 추가할지

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

  • 독자가 보는 내비게이션 항목 텍스트는:
    • 가능한 짧아야 합니다.
    • 맥락적이어야 합니다. 부모 항목의 텍스트를 반복할 필요는 드뭅니다.
    • 전문 용어나 용어는 피해야 하며, 유행할 경우에만 사용해야 합니다. 예를 들어, CI는 Continuous Integration의 수용 가능한 대체 용어입니다.
  • 내비게이션 링크는 data file에 문서화된 규칙을 따라야 합니다.

추가할 필요가 없는 페이지

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

  • 법적 고지사항.
  • architecture/blueprints 디렉토리의 페이지.
  • user/application_security/dast/checks/ 디렉토리의 페이지.

다음 페이지는 아마도 글로벌 내비게이션에 있어야 하지만, 기술 작가들이 적극적으로 추가 작업을 하지 않는 페이지입니다:

  • /development 디렉토리의 페이지.
  • doc/administration/troubleshooting 디렉토리에 있는 지원팀이 작성한 페이지.

때때로 deprecated(사용 중단된) 기능의 페이지는 기능이 언제 deprecated되었는지에 따라 글로벌 내비게이션에 없을 수 있습니다.

그 외의 모든 페이지는 글로벌 내비게이션에 있어야 합니다.

기술 작성 팀은 내비게이션에 없는 페이지를 확인하기 위해 리포트를 실행합니다.

이 팀은 매달 이 목록을 검토합니다.

내비게이션 구조

글로벌 내비게이션은 5개 수준으로 구성됩니다:

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

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

GitLab 사용 섹션

기능 문서 외에도, GitLab 사용 섹션의 각 카테고리는 다음을 포함해야 합니다:

이는 사용자가 문서를 탐색하는 방법을 익힐 수 있는 반복 가능한 패턴을 보장합니다.

GitLab 사용 섹션의 구조는 다음과 같습니다:

  • GitLab 사용
    • 최상위 페이지
      • 시작하기 페이지
      • 기능
      • 기능

구성

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

데이터 파일은 문서 링크로 레이아웃에 데이터를 공급합니다. 레이아웃은 데이터를 적절하게 스타일 적용하여 내비게이션의 컨테이너에 조직합니다.

데이터 파일

데이터 파일은 해당 프로젝트의 내비게이션 구조를 설명합니다.

이는 https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml에 저장되며 세 가지 주요 구성 요소로 구성됩니다:

  • 섹션
  • 카테고리
  • 문서

섹션

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

sections:
  - section_title: Text
    section_url: 'link'

섹션은 독립적으로 존재할 수 있거나 카테고리를 포함할 수 있습니다.

카테고리

섹션 내의 각 카테고리는 내비게이션의 두 번째 수준을 구성합니다.

카테고리 제목과 링크를 포함합니다. 내비게이션에서 독립적으로 존재할 수 있거나 세 번째 수준의 하위 항목을 포함할 수 있습니다.

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

- section_title: 섹션 제목
  section_url: 'section-link'
  section_categories:
    - category_title: 카테고리 제목
      category_url: 'category-link'

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

- section_title: 섹션 제목
  section_url: 'section-link'
  section_categories:
    - category_title: 카테고리 1 제목
      category_url: 'category-1-link'

    - category_title: 카테고리 2 제목
      category_url: 'category-2-link'

명확성을 위해, 항상 카테고리 사이에 빈 줄을 추가하세요.

문서

각 문서는 내비게이션 링크의 세 번째, 네 번째 및 다섯 번째 수준을 나타냅니다.

항상 카테고리 내에 추가되어야 합니다.

각 수준에서 세 개의 문서 링크가 있는 예:

- category_title: 카테고리 제목
  category_url: 'category-link'
  docs:
    - doc_title: 문서 제목
      doc_url: 'doc-link'
      docs:
      - doc_title: 문서 제목
        doc_url: 'doc-link'
        docs:
        - doc_title: 문서 제목
          doc_url: 'doc-link'

카테고리는 필요에 따라 많은 문서를 지원하지만, 명확성을 위해 카테고리를 과도하게 채우지 않도록 하세요. 또한, 3개 이상의 문서 수준을 사용하지 마세요. 지원되지 않습니다.

여러 문서가 있는 예:

- category_title: 카테고리 제목
  category_url: 'category-link'
  docs:
    - doc_title: 문서 1 제목
      doc_url: 'doc-1-link'
    - doc_title: 문서 2 제목
      doc_url: 'doc-2-link'

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

- doc_title: 문서 2 제목
  doc_url: 'doc-2-link'
  external_url: true

모든 내비게이션 링크는 선택 가능합니다. 상위 수준 링크에 자체 링크가 없는 경우,

그것은 자신의 첫 번째 하위 항목 링크로 연결되어야 하며, GitLab에서의 내비게이션을 모방해야 합니다.

이는 중복 링크나 두 개의 .active 링크가 동시에 있는 것을 피해야 합니다.

예시:

- category_title: Operations
  category_url: 'ee/user/project/integrations/prometheus_library/'
  # 우리가 작업에 대한 링크를 갖기 전까지,
  # 첫 번째 문서 링크가 카테고리 링크에서 반복됩니다
  docs:
    - doc_title: Metrics
      doc_url: 'ee/user/project/integrations/prometheus_library/'

문법

모든 구성요소(섹션, 카테고리 및 문서)에 대해, 들여쓰기를 존중하고 다음 문법 규칙을 따르세요.

제목
  • 문장형 대문자를 사용하여 기능 이름을 대문자로 시작합니다.
  • 제목에 특별한 문자가 포함되지 않는 한, 제목을 감쌀 필요가 없습니다. 예를 들어, GitLab CI/CD는 /가 포함되어 있으므로, 따옴표로 감싸야 합니다. 관례상 제목은 두 개의 따옴표로 감싸세요: category_title: "GitLab CI/CD".
URL

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

  • 데이터 파일 내의 모든 링크는 .html로 끝나야 하며( index.html 파일은 예외), .md는 사용할 수 없습니다.
  • index.html 파일의 경우, 깔끔한(정규화된) URL을 사용하세요: path/to/. 예를 들어, https://docs.gitlab.com/ee/install/index.html은 ee/install/로 변환됩니다.
  • 상대 링크는 항상 슬래시(/)로 시작하지 않아야 합니다.
  • 관례상, 항상 URL은 단일 인용부호 'url'로 감싸야 합니다.
  • 링크를 추가할 때, 해당 링크가 속한 프로젝트에 따라 프로젝트 접두사를 항상 사용하세요. 전체 URL에서 https://docs.gitlab.com/를 제거하여 글로벌 탐색 링크를 찾습니다.

  • 외부 URL에 링크가 연결된 경우, 예를 들어 GitLab Design System와 같이, 속성 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에 의해 고유한 스타일이 설정됩니다.

링크의 글꼴 크기, 패딩, 색상 등을 조정하려면 이러한 클래스를 사용하세요.

이렇게 하면 각 링크에 대한 규칙이 스타일시트 내의 다른 규칙과 충돌하지 않도록 보장할 수 있습니다.