グローバルナビゲーション

グローバルナビゲーションはドキュメントの一番左のペインです。グローバルナビゲーション “を使ってコンテンツをブラウズすることができます。

調査によると、人々はGitLab製品のドキュメントを検索するのにGoogleを使っています。彼らが検索結果にたどり着いたとき、読んでいるコンテンツに関連するトピックを近くに見つけてほしいのです。グローバルナビはこの情報を提供します。

最も高いレベルで、私たちのグローバルナビはワークフローベースです。ナビゲーションは、ユーザーがGitLabの使い方のメンタルモデルを構築するのを助ける必要があります。ワークフローベースの各トピックの下にあるレベルは、機能の名前です。例えば

GitLabを使う（ワークフロー）> アプリケーションをビルドする（ワークフロー）> CI/CD（機能）> パイプライン（機能）

ナビの古いセクションにはアルファベット順のものもありますが、ナビは主にワークフローに基づいたものであるべきです。

ナビゲーションの項目に適切な言葉を選びましょう

左ナビに項目を追加する前に、使用する品詞を選択してください。

ナブの項目はページのタイトルと一致させる必要があります。ただし、タイトルが長すぎる場合は、フレーズを短くするときに、どちらかを使用します：

  • マージリクエストのような名詞。
  • GitLabのインストールや Runnerを始めるのような能動動詞。

何のためのページなのかを明確に示すフレーズを使いましょう。例えば、Get startedはGet started with runnerほど役に立ちません。

ナビゲーション項目を追加

グローバルナビゲーションにトピックを追加するには、navigation.yaml を編集し、項目を追加します。

ナビゲーションの項目がない場合

  • ページを開くとナビゲーションが閉じてしまい、読者は自分の居場所を失います。
  • ページが他のページと一緒のグループに表示されません。

追加する必要のないページ

これらのページをグローバルナビゲーションから除外します：

  • 法的通知
  • architecture/blueprints ディレクトリのページ。
  • user/application_security/dast/checks/ ディレクトリのページ。

以下のページはおそらくグローバルナビにあるべきですが、テクニカルライターが積極的に追加することはありません：

  • /development ディレクトリのページ。
  • doc/administration/troubleshooting ディレクトリにある、サポートチームによって作成されたページ。

非推奨になった機能のページがグローバルナビゲーションにないことがあります。

他のすべてのページはグローバルナビにあるべきです。

テクニカルライティングチームはどのページがナビにないかを決定するためにレポートを作成します。チームは毎月このリストをレビューします。

追加するページ

ドキュメントページは以下のグループに属すると言えます：

  • GitLabユーザー。レポーターからオーナーまで、どの権限レベルのユーザーでもGitLabを日常的に使うためのドキュメントです。
  • GitLab管理者。これは、GitLabをホスティングしている基礎的なインフラストラクチャにアクセスする必要がある、セルフマネージドインスタンスのためのドキュメントになりがちです。
  • その他の文書。GitLabの日常的な利用以外の顧客のためのドキュメントや、貢献者のためのドキュメントが含まれます。他のグループに当てはまらない文書はここに属します。

これらのグループを念頭に置いて、新しい項目を追加する場所に関する一般的なルールを以下に示します。

  • のユーザー文書：
    • グループレベルの機能は、グループの下にあります。
    • プロジェクトレベルのフィーチャーはProjectsに属します。
    • グループレベルやプロジェクトレベル以外のフィーチャー（「インスタンスレベル」と呼ばれることもあります）をトップレベルに配置することもできますが、トップレベルのスペースを圧迫しないように注意する必要があります。可能であれば、そのようなフィーチャーは何らかの方法でグループ化することができます。
    • 上記以外では、ほとんどの雑多なユーザードキュメントはUserに属します。
  • 管理に関する文書はAdministrator に属します。
  • その他の文書はトップレベルに属しますが、非常に長いトップレベルのナビゲーションを作らないように注意しなければなりません。

すべてのドキュメントとナビゲーションの項目をこれらの原則に従うようにすることは、徐々に展開されています。

追加する項目

ナビゲーション要素を追加する場所を決めたら、次のステップは何を追加するかを決めることです。必要なものの仕組みは以下に記しますが、原則的には

  • ナビゲーション項目のテキスト（読者が目にするもの）は、以下のようにすべきです：
    • できるだけ短く。
    • 文脈に合わせましょう。親アイテムのテキストを繰り返す必要はめったにありません。
    • 専門用語や術語は、どこにでもあるものでない限り避けましょう。例えば、CIは Continuous Integrationの代わりに使えます。
  • ナビゲーション・リンクは、データ・ファイルに記載されているルールに従ってください。

どのように動作するか

グローバルナビには5つのレベルがあります：

  • セクション
    • カテゴリ
      • ドック
        • ドック
          • ドック

この構造は navigation.yml ファイルで見ることができます。

テクニカルライターの同意なしにグローバルナビに項目を追加しないでください。

構成

グローバルナビは2つのファイルから構成されています：

データファイルはドキュメントへのリンクをレイアウトに供給します。レイアウトは適切にスタイル設定されたコンテナ内のナビゲーションの間でデータを整理します。

データファイル

データファイルには、該当プロジェクトのナビゲーションの構造が記述されています。https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml に保存され、3つの主要コンポーネントで構成されています：

  • セクション
  • カテゴリー
  • ドキュメント

セクション

各セクションは上位のナビ項目を表します。タイトルとURLでComposerされます：

sections:
  - section_title: Text
    section_url: 'link'

セクションは単独でも、中にカテゴリーを含むこともできます。

カテゴリー

セクション内の各カテゴリはナビゲーションの第2レベルを構成します。カテゴリのタイトルとリンクが含まれます。カテゴリは単独でナビゲーションの中に存在することも、第3レベルのサブアイテムを含むこともできます。

1つの独立したカテゴリーを持つセクションの例：

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

独立したカテゴリーが2つあるセクションの例：

- 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'

わかりやすくするため、カテゴリーとカテゴリーの間には必ず空白行を入れます。

ドキュメント

それぞれのdocはナビリンクの第3、4、5レベルを表します。これらは常にカテゴリー内に追加されなければなりません。

各レベルに1つずつ、3つのdocリンクがある例：

- 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'

カテゴリは必要なだけのドキュメントをサポートしますが、わかりやすくするために、カテゴリを増やしすぎないようにしてください。また、3つ以上のレベルのdocを使わないでください。

複数のドキュメントの例

- 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にドキュメントを追加する必要がある場合は、docリンクの下に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/'
  # until we have a link to operations, the first doc link is
  # repeated in the category link
  docs:
    - doc_title: Metrics
      doc_url: 'ee/user/project/integrations/prometheus_library/'

構文

すべてのコンポーネント (セクション、カテゴリ、docs) では、インデントと以下の構文規則を尊重してください。

タイトル
  • 大文字と小文字を区別してください。
  • 特別な文字が含まれていない限り、タイトルをラップする必要はありません。例えば、GitLab CI/CD には、/ があるので、引用符で囲む必要があります。慣例として、タイトルは二重引用符で囲みます：category_title: "GitLab CI/CD".
URL

URLには相対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 のような内部 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.htmlee/api/avatar.html
https://docs.gitlab.com/ee/install/index.htmlee/install/
https://docs.gitlab.com/omnibus/settings/database.htmlomnibus/settings/database.html
https://docs.gitlab.com/charts/installation/deployment.htmlcharts/installation/deployment.html
https://docs.gitlab.com/runner/install/docker.htmlrunner/install/docker.html

レイアウトファイル（ロジック）

レイアウトは データファイルから供給され、グローバルナビを構築し、デフォルトレイアウトによってレンダリングされます。

グローバルナビには、4つのアップストリームプロジェクトすべてのリンクが含まれています。グローバルナビのURLは、変更するドキュメントファイルによってプレフィックスが異なります。

リポジトリリンクプレフィックス最終URL
https://gitlab.com/gitlab-org/gitlab/-/tree/master/docee/https://docs.gitlab.com/ee/
https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docomnibus/https://docs.gitlab.com/omnibus/
https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docsrunner/https://docs.gitlab.com/runner/
https://gitlab.com/charts/gitlab/tree/master/doccharts/https://docs.gitlab.com/charts/

CSSクラス

ナビのスタイルは一般的なstylesheet.scssで設定されています。そのスタイルを変更するには、チーム内でより良い開発ができるように、それらをグループ化しておいてください。

URL コンポーネントは、CSS クラス.level-0,.level-1,.level-2によって独自のスタイルが設定されています。リンクのフォントサイズ、パディング、色などを調整するには、これらのクラスを使用します。こうすることで、各リンクのルールがスタイルシートの他のルールと衝突しないことが保証されます。