• 내비게이션 항목에 적합한 단어 선택
• 내비게이션 항목 추가
  • 추가할 위치
  • 추가해야 할 내용
  • 추가할 필요가 없는 페이지
• 내비게이션 구조
• 구성
  • 데이터 파일
    • 섹션
    • 카테고리
    • 문서
    • 구문
      • 제목
      • URL
  • 레이아웃 파일 (로직)
  • CSS 클래스

글로벌 내비게이션

• 도입됨 GitLab 11.6.
• 업데이트됨 GitLab 12.1.
• 프로젝트별 내비게이션이 GitLab 12.2에 추가되었습니다.
• 통합 글로벌 내비게이션이 GitLab 13.11에 추가되었습니다.

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

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

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

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

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

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

• 페이지가 열리면 내비게이션이 닫히고, 독자가 자리를 잃습니다.
• 페이지가 다른 페이지와 그룹에 표시되지 않습니다.

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

왼쪽 내비게이션에 항목을 추가하기 전에 사용할 단어를 선택합니다.

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

• 병합 요청(Merge requests)와 같이 명사를 사용합니다.
• GitLab 설치 또는 러너(runnerts)로 시작하기와 같이 능동적인 동사를 사용합니다.

페이지가 어떤 용도인지 명확히 나타내는 구문을 사용합니다. 예를 들어, 시작하기는 러너(runnerts)로 시작하기만큼 유용하지 않습니다.

내비게이션 항목 추가

글로벌 내비게이션에 항목을 추가하기 전에 기술 작성자(Technical writers)의 승인 없이 추가하지 마십시오.

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

1. navigation.yaml 파일에 항목을 추가합니다.
2. MR(Merge Request)을 기술 작성자에게 할당하여 검토 및 병합합니다.

추가할 위치

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

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

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

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

이러한 원칙에 따라 모든 문서와 내비게이션 항목을 적용하는 것이 점진적으로 진행 중입니다.

추가해야 할 내용

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

• 독자가 볼 수 있는 내비게이션 항목 텍스트는:
  • 최대한 짧아야 합니다.
  • 문맥적이어야 합니다. 상위 항목에서 텍스트를 반복할 필요가 거의 없습니다.
  • 널리 사용되는 용어를 제외하고는 중용어나 전문 용어를 피해야 합니다. 예를 들어, CI는 Continuous Integration의 대체어로 허용됩니다.
• 내비게이션 링크는 데이터 파일에 문서화된 규칙을 따라야 합니다.

추가할 필요가 없는 페이지

다음과 같은 페이지는 전역 내비게이션에서 제외합니다:

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

다음 페이지는 아마도 전역 내비게이션에 있어야 하지만, 기술 작성팀은 적극적으로 이러한 페이지를 추가하지는 않습니다.

• /development 디렉터리의 페이지.
• 지원팀이 작성한 페이지로 doc/administration/troubleshooting 디렉터리에 속합니다.

때로는 사용되지 않는 기능에 대한 페이지가 글로벌 내비게이션에 없을 수 있으며, 이는 해당 기능이 얼마나 오래되었는지에 따라 다릅니다.

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

기술 문서 팀은 글로벌 내비게이션에 없는 페이지를 확인하는 보고서를 실행합니다. 팀은 매월 이 목록을 검토합니다.

내비게이션 구조

글로벌 내비게이션에는 다섯 가지 수준이 있습니다:

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

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

구성

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

• 데이터
• 레이아웃

데이터 파일은 레이아웃에 문서 링크를 제공합니다. 레이아웃은 데이터를 내비게이션에 적절히 구성하여 컨테이너에 배치합니다(스타일이 적용됨).

데이터 파일

데이터 파일은 해당 프로젝트의 내비게이션 구조를 설명합니다. 다음 주소에 저장되며, 세 가지 주요 구성 요소로 구성됩니다:

• 섹션
• 카테고리
• 문서

섹션

각 섹션은 상위 수준 내비 항목을 나타냅니다. 제목과 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에 링크가 없는 경우, 첫 번째 문서 링크가 카테고리 링크에서 반복됨
  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은 변경하는 문서 파일에 따라 다른 접두사를 가지고 있습니다.

CSS 클래스

내비게이션은 일반 stylesheet.scss에서 스타일이 지정됩니다. 스타일을 변경할 때에는 팀 내에서의 개발을 위해 스타일을 그룹화하여 유지하세요.

URL 구성 요소는 고유한 스타일을 가진 CSS 클래스 .level-0, .level-1 및 .level-2에 의해 설정됩니다. 링크의 글꼴 크기, 여백, 색상 등을 조정하려면 이러한 클래스를 사용하세요. 이렇게 함으로써 각 링크의 규칙이 스타일시트의 다른 규칙과 충돌하지 않도록 보장합니다.