サイドバー

MDN のページにはすべてサイドバーが設置されています。そのほとんどは、 YAML ファイルでデータ構造を定義し、マクロ呼び出しを使用してページにサイドバーを挿入する標準システムで作成されています。

このガイドでは、サイドバーがどのように動作するのかを学び、必要に応じて既存のサイドバーを編集したり、新しいサイドバーを作成したりする方法を習得します。また、標準システムを使用していないものについても詳しく説明します。

メモ: サイドバーを編集している場合は、書式化とリダイレクトの同期に yarn tool コマンドを使用することができます。 詳しくは Yari の CLI ツールのドキュメントを参照してください。

サイドバーの働き

それぞれのサイドバーには、対応する YAML ファイルが MDN の content リポジトリーの files/sidebars ディレクトリーの中にあります。このファイルでは、サイドバーリンクの階層構造、それぞれのリンクが指し示すべき URL、およびオプションのカスタム見出し/リンクテキストを定義しています。必要に応じて、これらのテキストをさまざまな言語にローカライズすることができます。

例として、現在見ているページを例にとると、サイドバーの構造は mdnsidebar.yaml ファイルで定義されています。

サイドバーは、対応するマクロ呼び出し {{MDNSidebar}} を文書のソース内のフロントマターのすぐ下に記載することで、現在のページ（および同じ文書ツリー内のページにも）に表示されます。

md
---
title: サイドバー
slug: MDN/Writing_guidelines/Page_structures/Sidebars
l10n:
  sourceCommit: 269fa421f0a79b18f6000a26baebe30c74571b1f
---

{{MDNSidebar}}

フロントマターとは、ダッシュで区切られた間のコンテンツを指します。ソースに {{MDNSidebar}} マクロ呼び出しを記載すると、システムは同じ名前の YAML ファイルを files/sidebars ディレクトリー内で探します。ファイルが見つかると、サイドバーのレンダリングと、 1 つまたは複数の順序付きリスト（<ol>要素）としてページ上に配置する処理が自動的に行われます。

このページに戻る前に、サイドバーの周りをナビゲート操作してみてください。 通常、ページをナビゲートすると、現在いる節のリンクリストが展開され、他にも展開される一方で、他にもが折りたたまれ、現在いるページが強調表示されることに気づくでしょう。

標準のサイドバーの例

他にもよく見かける標準的なサイドバーには、次のものがあります。

{{CSSRef}}

すべての CSS ページに存在します。

{{GlossarySidebar}}

すべてのglossaryページに存在します。

{{LearnSidebar}}

ウェブ開発の学習の中にあるすべてのページに存在します。

{{HTMLSidebar}}

HTML のドキュメントのためのサイドバーを生成します。

{{HTTPSidebar}}

HTTP ドキュメント のためのサイドバーを生成します。

{{PWASidebar}}

プログレッシブウェブアプリ (PWA) のドキュメントのためのサイドバーを生成します。

メモ: 使用する適切なマクロはページの種類に依存します。各ページ種類のテンプレートには、そのページ種類に適したマクロが記載されています。

サイドバーの YAML の構文の解説

この節では、 MDN のサイドバーに含めることができるさまざまな機能と、それぞれの生成に使用できる YAML 構文について説明します。この文書化を進める中で、既存のサイドバーの YAML に対して機能を相互参照してください。

新しいサイドバーの作成

それぞれの YAML サイドバーのデータ定義の始めに sidebar キーを使用します。このキーの値は、サイドバーデータを定義するリストです。

yaml
sidebar:
  # サイドバー定義の始まり

基本的な単一のリンク

サイドバーに基本的な単一のリンクを作成するには、 YAML リストアイテムに相対 URL が含めて記述してください。

yaml
sidebar:
  - /MDN/Changelog

この URL は MDN の URL 構造における docs ディレクトリーに対する相対パスであるため、例えば /MDN/Changelog は https://developer.mozilla.org/ja/docs/MDN/Changelog へのリンクを生成します。システムは自動的にリンク先のページの文書タイトルをリンクテキストとして使用します。

独自のリンクテキストを使用したい場合は、リストアイテム内に 2 つのキーを記述する必要があります。 1 つは、独自のリンクテキストを持つ title、もう 1 つは、相対 URL を持つ link です。次の例では、 MDN Web Docs の変更履歴へのリンクを前回と同様に作成しますが、リンクテキストは独自の "Our changelog" になります。

yaml
sidebar:
  - title: Our changelog
    link: /MDN/Changelog

セクションタイトル

セクションタイトルは、通常のサイドバーアイテムよりも大きなフォントサイズで表示されるサイドバーアイテムです。これは一般的に、ドキュメントのセクションのランディングページにリンクするサイドバー上部のタイトルとして、または具体的な大型サイドバーのセクション区切りとして使用されています（ ウェブ開発の学習の章を参照）。

セクションタイトルは、リストアイテムに type キーと section の値を設定することで定義します。例を示します。

yaml
sidebar:
  - type: section
    link: /MDN

セクションタイトルには、独自のリンクテキストを指定することができます。

yaml
sidebar:
  - type: section
    title: Yay MDN!
    link: /MDN

または、リンクを含まないテキストリストアイテムのみを表示するには、 link キーを省略できます。

yaml
sidebar:
  - type: section
    title: Yay MDN!

展開/折りたたみができるリンクのリストを作成

展開/折りたたみができるリンクのリストを作成するには、まず通常通りリストアイテムを作成し、 children キーを記述します。このキーの値は、親アイテムの下に子アイテムとして表示したいリンクを含むリストです。それぞれの子リストアイテムは、親アイテムと同じ構文を使用します。子リストアイテムには、独自の children を含めることができるため、複数の階層レベルを作成することができます。例えば、次のような例があります。

yaml
sidebar:
  - title: community_guidelines
    details: closed
    children:
      - /MDN/Community
      - title: contributing_to_mdn_web_docs
        details: closed
        children:
          - /MDN/Community
          - /MDN/Community/Getting_started
          - /MDN/Community/Our_repositories
          - /MDN/Community/Translated_content
          - /MDN/Community/Security_vulnerability_response
      - /MDN/Community/Open_source_etiquette
      - /MDN/Community/Communication_channels
      - /MDN/Community/Discussions
      - /MDN/Community/Learn_forum
      - /MDN/Community/Issues
      - /MDN/Community/Pull_requests
      - /MDN/Community/Roles_teams

なお、details キーにも注意してください。これは、ページが最初に読み込まれた際に、リストアイテムの子リストが閉じられた状態で表示されるか、開かれた状態で表示されるかを制御します。利用可能な値は次の通りです。

  • closed: 現在のページがいずれかの子ページにリンクされていない限り、子ページは閉じられて表示されます。リンクされている場合は、開いた状態になります。
  • open: 子は常に開いて表示されます。

リストアイテムに children および details が指定されている場合、そのアイテムは、<details>/<summary> 要素構造でレンダリングされ、その中に子リストが含まれます。この子リストは、展開/折りたたみボタンをクリックするか、サマリーにフォーカスして Enter/Return キーを押すことで展開/折りたたみすることができます。

サブページのリストの自動的なレンダリング

特定のページのサブページへのリンクを含むリストを作成したい場合は、リストアイテムを指定して、タイプキーの値を listSubPages、パスキーの値をリンクを作成したいサブページへのパスとして指定することで、これを作成できます。例えば、 Glossary サイドバーの定義全体（glossarysidebar.yaml を参照）は次のようになります。

yaml
sidebar:
  - type: section
    link: /Glossary
    title: Glossary
  - type: listSubPages
    path: /Glossary

これによって、用語集のランディングページに戻るリンクが含まれたセクションタイトルを伴うサイドバーと、用語集の子ページすべてへのリンクが掲載されている最上位のリストが表示されます。

これを行としてレンダリングし、サブページが展開されたり折りたたまれたりする子リストとして現れるようにしたい場合は、親アイテムに表示するテキストを指定する title キーと、<details>/<summary> 構造の開閉状態を指定する details キーを追加で記載する必要があります。

yaml
sidebar:
  - type: listSubPages
    path: /Glossary
    title: Glossary
    details: closed

リストのサブページのグループ化

listSubPagesGrouped の type 値もあります。 これによって、同じ部分文字列に続いてハイフン（例えば item-）で終わるタイトルを持つすべてのサブページが、その部分文字列にハイフンとアスタリスク（例えば item-*）を追加したリストアイテムの下のサブリストに記載されます。

例えば、この記事を書いている時点では、 MDN 用語集には CORS 関連のページが 3 つ含まれています。

  • CORS
  • CORS-safelisted request header
  • CORS-safelisted response header

用語集サイドバーの定義をこれに更新するとしたら、このようにします。

yaml
sidebar:
  - type: listSubPagesGrouped
    path: /Glossary
    title: Glossary
    details: closed

これらのページへのリンクは、次のような子リスト構造にグループ化されます。

  • CORS-*
    • CORS
    • CORS-safelisted request header
    • CORS-safelisted response header

もっと現実的な例は、 CSS のサイドバー定義（cssref.yaml を参照）にあり、 listSubPagesGrouped を使用して、一括指定および個別指定プロパティの関連リンクをグループ化することができます。プロパティのサイドバーメニューを生成するリストアイテムは次のようになります。

yaml
- type: listSubPagesGrouped
  path: /Web/CSS
  title: Properties
  tags:
    - css-property
    - css-shorthand-property
  details: closed

このリストアイテムの定義には tags も含まれており、これは次の節で取り上げるテーマです。

リストのサブページの絞り込み

同じディレクトリー内に複数の異なる種類のページ（ページのフロンマター内に指定された page-type キーで指定）がある場合、 listSubPages および listSubPagesGrouped によって生成されたリストアイテムをページ種類別にフィルターすることができます。これを行うには、リストアイテム内に tags キーを含めることができます。このキーの値が、生成されたリストアイテムに含める単一のページ種類またはページ種類のリストを示します。 CSS サイドバーには、例えば次のようなものが含まれています。

yaml
- type: listSubPages
  path: /Web/CSS
  title: Modules
  tags: css-module
  details: closed
- type: listSubPagesGrouped
  path: /Web/CSS
  title: Properties
  tags:
    - css-property
    - css-shorthand-property
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Selectors
  tags: css-selector
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Combinators
  tags: css-combinator
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Pseudo-classes
  tags: css-pseudo-class
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Pseudo-elements
  tags: css-pseudo-element
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: At-rules
  tags: css-at-rule
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Functions
  tags: css-function
  details: closed
- type: listSubPages
  path: /Web/CSS
  title: Types
  tags: css-type
  details: closed

テキスト文字列のローカライズ

上で説明したように、リンクテキストやセクションタイトルを埋め込むためのカスタムテキストを title キーに指定することができます。そのテキストを複数の言語にローカライズしたい場合は、title キーにプレースホルダーを含め、 YAML ファイルの末尾にある l10n 辞書内に、そのプレースホルダーをそれぞれの言語でどのように定義するかを記載することができます。

どのようなものか、例を見てみましょう。 HTML サイドバー（htmlsidebar.yaml を参照）では、すべての <input> 型のリファレンスページへのリンクのリストを生成するリストアイテムを定義します。親リストアイテムのテキストは、 title キーに Input_types のプレースホルダーとして定義されます。

yaml
- type: listSubPages
  path: /Web/HTML/Element/input
  title: Input_types
  details: closed
  code: true

ファイルの一番下では、l10n 辞書を定義しています。 l10n 内の各キーは、さまざまなロケールを表します。 en-US、fr、ja などです。 これらの各キーの値は、サブ辞書であり、そのキーはリストアイテム定義で定義されているプレースホルダーです。 各キーの値は、それぞれのロケールにおけるそのプレースホルダーの値です。

例を示します。

yaml
l10n:
  en-US:
    Input_types: <code>&lt;input&gt;</code> types
  fr:
    Input_types: Types <code>&lt;input&gt;</code>
  ja:
    Input_types: <code>&lt;input&gt;</code> 型
  ko:
    Input_types: <code>&lt;input&gt;</code> types
  pt-BR:
    Input_types: Tipos de <code>&lt;input&gt;</code>
  ru:
    Input_types: Типы <code>&lt;input&gt;</code>
  zh-CN:
    Input_types: <code>&lt;input&gt;</code> 类型

簡潔にするため、各ロケールには Input_types の値のみ含まれます。

サイドバーがレンダリングされる際、システムは、アクセスしているサイトのどのバージョンのロケールであっても、 Input_types テキストを定義した値に置き換えます。例えば、次の例と比較してください。

MDNのロケールにアクセスし、特定のプレースホルダに対して値が定義されていない場合、既定では en-US バージョンが使用されます。 en-US バージョンが定義されていない場合、リテラルプレースホルダテキストが表示されます（上記の場合、 Input_types となります）。

標準外のサイドバー

MDN で使用されているサイドバーの中には、上記で説明されている標準システムを使用していないものもあります。これらは複雑な完全に自動化されたマクロであり、変更する必要が頻繁にあるわけではありません。

{{APIRef("<API>")}}

API リファレンスページに表示される API サイドバー。それぞれのインターフェイスに対して、マクロはインターフェイスで定義されたメンバー（プロパティ、メソッド、イベントなど）へのリンクを自動生成します。単一の引数は、 GroupData.json ファイルで定義された関連する API グループの名前です。サイドバーの下部に表示される関連ページを編集するには、その API の GroupData 項目を編集します。

{{DefaultAPISidebar("<API>")}}

API ランディングページに表示される API サイドバー。単一の引数は、 GroupData.json ファイルで定義された関連する API グループの名前です。具体的な API のサイドバーにリンクされたガイド、インターフェイスなどを編集するには、その API の GroupData 項目を編集します。

{{JSRef("<JS_topic>")}}

JavaScript リファレンスページのサイドバー。単一の引数は、リンクを作成したいディレクトリーです。

これらのうちの 1 つが更新されるべきであるとお考えの場合は、通常の方法で私たちにご連絡ください。

関連情報