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

グローバル・ナビゲーション(3つのペインで構成されたドキュメントの一番左のペイン)には、以下の機能があります:

  • 製品の特徴をハイレベルにグループ化したビュー。
  • メニュー構造をブラウズして新しい機能を発見する機能。
  • 読者が製品分野に集中できるようにする方法。
  • ランディングページを絞り込むことができるため、ドキュメントに含まれるすべてのページを表示する必要がありません。

新しいアイテムの追加

すべての新しいページには、新しいナビゲーション項目が必要です。 ナビゲーションがないと、ページは「孤児」になります。 つまり:

  • ページを開くとナビゲーションが閉じてしまい、読者は居場所を失います。
  • そのページは他のページとグループに属していません。

つまり、新しいページを作るという決断は、新しいナビゲーション項目を作るという決断であり、その逆もまた然りです。

追加する場所

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

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

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

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

追加するもの

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

  • ナビゲーション項目のテキスト(読者が目にするもの)であるべきです:
    • できるだけ短く。
    • 親アイテムのテキストを繰り返す必要はめったにありません。
    • 専門用語や術語は、どこにでもあるようなものでない限り避けてください。 たとえば、CIは Continuous Integrationの代用として認められます。
  • ナビゲーションリンクは、データファイルに記載されているルールに従う必要があります。
  • EEバッジは以下の条件を満たすことが必要です:
    • EE専用ページにリンクする場合はPagesが必要です。
    • CEとEEのみのコンテンツが混在するページへのリンクの場合は不要です。
    • すべてのサブ項目が EE-only の場合は必須。 この場合、サブ項目に EE バッジは付きません。
    • 小項目に CE と EE のみの項目が混在する場合は不要。 この場合、各項目には適切なバッジが付きます。

どのように動作するか

グローバルナビには3つのコンポーネントがあります:

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

利用可能なセクションは以下の表の通りです:

セクション 説明
ユーザー GitLabのユーザーUIのドキュメント。
管理者 GitLabの管理エリアのドキュメントです。
貢献者 GitLab開発者のためのドキュメント。

ナビで利用可能なリンクの大部分はUIに従って追加されました。 UIナビの項目によってはドキュメントが適用されないものもあり、完全な一致ではありません。 また、新しいユーザーがドキュメントを発見するのを助けるためのリンクもあります。管理の下のドキュメントはわかりやすくするためにアルファベット順に並んでいます。

今後予定されている改善点については、グローバル・ナビ・エピックをご覧ください。

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

構成

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

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

データファイル

データファイルには、該当プロジェクトのナビゲーションの構造が記述されています。 すべてのデータファイルはhttps://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/ に保存され、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'

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

CEにカテゴリURLが存在しない場合(EEのみの文書である場合)、カテゴリリンクの下に属性ee_only: true 。 例:

- category_title: Category title
  category_url: 'category-link'
  ee_only: true

GitLabデザインシステムなど、カテゴリーが外部URLにリンクしている場合は、カテゴリータイトルの下にexternal_url: true 。 例:

- category_title: GitLab Design System
  category_url: 'https://design.gitlab.com'
  external_url: true

資料

それぞれのdocはナビリンクの第3レベルを表し、必ずカテゴリー内に追加する必要があります。

ドキュメントリンクの例

- category_title: Category title
  category_url: 'category-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'

ドキュメントがEEにしか存在しない場合は、docリンクの下に属性ee-only: true。 例:

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

外部URLにドキュメントを追加する必要がある場合は、docリンクの下に属性external_url

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

すべてのナビリンクはクリック可能です。 上位リンクがそれ自身のリンクを持っていない場合、GitLabのナビゲーションを真似て、その最初のサブ項目リンクにリンクしなければなりません。これは、リンクが重複したり、同時に2つの.active リンクを持つことがないように避けなければなりません。

使用例:

- category_title: Operations
  category_url: '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: 'user/project/integrations/prometheus_library/'

構文

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

タイトル
  • 大文字と小文字を区別してください。
  • 特別な文字が含まれていない限り、タイトルをラップする必要はありません。 例えば、GitLab CI/CDでは、/ が存在するため、引用符で囲む必要があります。慣例として、タイトルはダブルクォーテーションで囲みます:category_title: "GitLab CI/CD".
URL
  • 慣例として、URLは常にシングルクォートで囲みます'url'.
  • CEとEEのホームに対しては、常に相対パスを使用します。 例を示します:
    • https://docs.gitlab.com/ee/README.htmlの場合、相対URLはREADME.htmlです。
    • https://docs.gitlab.com/ee/user/project/cycle_analytics.htmlの場合、相対URLはuser/project/cycle_analytics.htmlです。
  • README.html ファイルの場合は、完全なパスpath/to/README.htmlを追加します。
  • index.html ファイルについては、クリーンな(正規の) URL を使用してください:path/to/
  • EE-only docsの場合は、同じ相対パスを使用しますが、上記で説明したように、doc_url またはcategory_urlの下にee_only: true という属性を追加します。これにより、ナビ上に「情報」アイコンが表示され、その機能がEE-onlyであることをユーザーに認識させることができます。
重要!データファイル上に存在するすべてのリンクは、.mdではなく、.htmlで終わる必要があります。相対リンクの先頭をフォワードスラッシュ/で始めてはいけません。

例:

- category_title: Issues
  category_url: 'user/project/issues/'
  # note that the above URL does not start with a slash and
  # does not include index.html at the end

  docs:
    - doc_title: Service Desk
      doc_url: 'user/project/service_desk.html'
      ee_only: true
      # note that the URL above ends in html and, as the
      # document is EE-only, the attribute ee_only is set to true.

レイアウトファイル(ロジック)

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

ナビに組み込むロジックには、主に3つの考慮点があります:

  • パス:docs.gitlab.com/以下の第一レベルディレクトリ :
    • https://docs.gitlab.com/ce/
    • https://docs.gitlab.com/ee/
    • https://docs.gitlab.com/omnibus/
    • https://docs.gitlab.com/runner/
    • https://docs.gitlab.com/debug/
    • https://docs.gitlab.com/*
  • EE-only: ドキュメントは/ee/でのみ利用可能で、/ce/では利用できません:
    • https://docs.gitlab.com/ee/user/group/epics/
    • https://docs.gitlab.com/ee/user/project/security_dashboard.html
  • デフォルトURL: CEとEEのドキュメントの間では、デフォルトはeeです。したがって、内部的にceにリンクしている/ce/ の場合を除き、すべてのドキュメントは/ee/ にリンクする必要があります。

パス

データファイルで相対パスを使用するために、ルートの最初の子ディレクトリから変数dir、他のページへのすべてのナビリンクを構築するパスを定義しました:

<% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %>

例えば、https://docs.gitlab.com/ce/user/index.htmlの場合、dir ==cehttps://docs.gitlab.com/omnibus/README.htmlの場合、dir ==omnibus

デフォルトURL

GitLabドキュメントのデフォルトで正規のURLはhttps://docs.gitlab.com/ee/です。したがって、/ce/ ドキュメント自体にリンクする場合を除き、docsサイト内のすべてのリンクは/ee/ にリンクする必要があります。

したがって、ユーザーが/ee//omnibus//runner/、またはその他の最上位のディレクトリを見ている場合、navは/ee/ docsを指すべきです。

一方、ユーザーが/ce/ ドキュメントを見ているのであれば、CEナビのリンクはすべてファイルへの /ce/内部/ce/ リンクであるべき /ce/です。

<% if dir != 'ce' %>
  <a href="/ee/<%= sec[:section_url] %>">...</a>
  <% else %>
    <a href="/<%= dir %>/<%= sec[:section_url] %>">...</a>
  <% end %>
  ...
<% end %>

これにより、他の最上位ディレクトリ(/omnibus/,/runner/, など)にもナビを表示することができ、それらを/ee/にリンクさせることができます。

すべてのセクション(sec[:section_url])、カテゴリー(cat[:category_url])、docs(doc[:doc_url])のURLにも同じロジックが適用されます。

ee-only 諸注意

GitLab EEのみに存在する機能のドキュメントは、ee-only によってデータファイルにタグ付けされ、ee-only その機能がCEでは利用できないことを示すアイコンがナビリンクに表示されます。

ee-only 属性はcategories (<% if cat[:ee_only] %>) とdocs (<% if doc[:ee_only] %>) で使用できますが、sectionsでは使用できません。

CSSクラス

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

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