サイドバーのナビゲーション

サイドバーはユーザーがサイト内を移動するための主要な方法の1つであるため、サイドバーを整理することは良いドキュメントの鍵となります。Starlightでは、サイドバーのレイアウトとコンテンツをカスタマイズするためのオプション一式を提供しています。

デフォルトのサイドバー

Starlightはデフォルトで、ドキュメントのファイルシステム構造に基づいてサイドバーを自動的に生成します。その際、各ファイルのtitleプロパティをサイドバーのエントリとして使用します。

たとえば以下のファイル構造があるとします。

• ディレクトリsrc/

  • ディレクトリcontent/

    • ディレクトリdocs/

      • ディレクトリconstellations/

        • andromeda.md
        • orion.md
      • ディレクトリstars/

        • betelgeuse.md

すると以下のサイドバーが自動的に生成されます。

• 星座

  • アンドロメダ座
  • オリオン座
• 星

  • ベテルギウス

自動生成されるサイドバーについては、自動生成されるグループのセクションで詳しく説明します。

リンクとリンクグループを追加する

サイドバーのリンクと（折りたたみ可能なヘッダー内の）リンクグループを設定するには、astro.config.mjsでstarlight.sidebarプロパティを使用します。

リンクとグループを組み合わせることで、さまざまなサイドバーレイアウトを作成できます。

内部リンク

slugプロパティをもつオブジェクトを使用して、src/content/docs/内のページへのリンクを追加します。デフォルトでは、リンク先ページのタイトルがラベルとして使用されます。

たとえば、以下の設定があるとします。

starlight({
  sidebar: [
    { slug: 'constellations/andromeda' },
    { slug: 'constellations/orion' },
  ],
});

そして以下のファイル構造であるとします。

• ディレクトリsrc/

  • ディレクトリcontent/

    • ディレクトリdocs/

      • ディレクトリconstellations/

        • andromeda.md
        • orion.md

すると以下のサイドバーが生成されます。

• アンドロメダ座
• オリオン座

リンク先ページのフロントマターから推測される値をオーバーライドするには、label、translations、attrsプロパティを追加します。

ページのフロントマターからサイドバーの表示を制御する方法について、詳しくは「自動生成されるリンクのカスタマイズ」を参照してください。

内部リンクの省略記法

内部リンクは、ページのスラグを文字列として渡すだけの省略記法でも指定できます。

たとえば、以下の設定は上記のslugを使用した設定と同等です。

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});

その他のリンク

labelとlinkプロパティをもつオブジェクトを使用して、外部ページやドキュメント以外のページへのリンクを追加します。

starlight({
  sidebar: [
    // サイト内のドキュメント以外のページへのリンク。
    { label: '流星商店', link: '/shop/' },
    // NASAのウェブサイトへの外部リンク。
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 流星商店
• NASA

グループ

折りたたみ可能な見出しの下に関連するリンクをグループ化することで、サイドバーに構造を追加できます。グループには、リンクと他のサブグループを含められます。

labelとitemsプロパティをもつオブジェクトを使用して、グループを追加します。labelはグループの見出しとして使用されます。items配列にリンクまたはサブグループを追加します。

starlight({
  sidebar: [
    // 「星座」というラベルのリンクグループ。
    {
      label: '星座',
      items: [
        'constellations/carina',
        'constellations/centaurus',
        // 季節の星座の入れ子になったリンクグループ。
        {
          label: '季節の星座',
          items: [
            'constellations/andromeda',
            'constellations/orion',
            'constellations/ursa-minor',
          ],
        },
      ],
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星座

  • りゅうこつ座
  • ケンタウルス座
  • 季節の星座

    • アンドロメダ座
    • オリオン座
    • こぐま座

自動生成されるグループ

Starlightはドキュメントのディレクトリに基づいて、サイドバーのグループを自動的に生成できます。これはグループ内のサイドバー項目を手動で入力したくない場合に便利です。

デフォルトでは、ページはファイルのidに従ってアルファベット順に並べ替えられます。

labelとautogenerateプロパティをもつオブジェクトを使用して、自動生成されるグループを追加します。autogenerateの設定には、サイドバーのエントリに使用するdirectoryを指定する必要があります。たとえば、以下のように設定したとします。

starlight({
  sidebar: [
    {
      label: '星座',
      // constellationsディレクトリのリンクグループを自動生成します。
      autogenerate: { directory: 'constellations' },
    },
  ],
});

そして以下のファイル構造があるとします。

• ディレクトリsrc/

  • ディレクトリcontent/

    • ディレクトリdocs/

      • ディレクトリconstellations/

        • carina.md
        • centaurus.md
        • ディレクトリseasonal/

          • andromeda.md

すると以下のサイドバーが生成されます。

• 星座

  • りゅうこつ座
  • ケンタウルス座
  • seasonal

    • アンドロメダ座

自動生成されるリンクをフロントマターでカスタマイズする

個々のページでsidebarフロントマターフィールドを使用して、自動生成されるリンクをカスタマイズできます。

フロントマターのサイドバーオプションにより、カスタムラベルの設定、カスタム属性の使用、リンクへのバッジの追加、サイドバーのリンクの非表示、独自のソート順の定義が可能です。

---
title: 私のページ
sidebar:
  # このリンクのカスタムラベルを設定します
  label: カスタムサイドバーラベル
  # このリンクの順番をカスタマイズします（数字が小さいほど上に表示されます）
  order: 2
  # このリンクにバッジを追加します
  badge:
    text: 新規
    variant: tip
---

上記のフロントマターを設定したページと一緒に自動生成されるグループは、以下のサイドバーを生成します。

• ガイド

  • ページ
  • カスタムサイドバーラベル 新規
  • 別のページ

ノート

sidebarフロントマターの設定は、自動生成されるグループ内のリンクとslugプロパティで定義されたドキュメントリンクにのみ使用されます。linkプロパティで定義されたリンクには適用されません。

バッジ

リンク、グループ、自動生成されるグループには、ラベルの横にバッジを表示するためのbadgeプロパティも含められます。

starlight({
  sidebar: [
    {
      label: '星',
      items: [
        // 「超巨星」バッジ付きのリンク。
        {
          slug: 'stars/persei',
          badge: '超巨星',
        },
      ],
    },
    // 「要更新」バッジ付きの自動生成されるグループ。
    {
      label: '衛星',
      badge: '要更新',
      autogenerate: { directory: 'moons' },
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星

  • ペルセウス座 超巨星
• 衛星 要更新

  • イオ
  • エウロパ
  • ガニメデ

バッジのバリアントとカスタムスタイル

textとvariant、classプロパティをもつオブジェクトを使用して、バッジのスタイルをカスタマイズできます。

textは表示するコンテンツ、たとえば「新規」などを表わします。デフォルトでは、バッジにはサイトのアクセントカラーが使用されます。組み込みのバッジスタイルを使用するには、variantプロパティをnote、tip、danger、caution、successのいずれかに設定します。

また、classプロパティにCSSクラス名を設定することで、カスタムバッジスタイルを作成することも可能です。

starlight({
  sidebar: [
    {
      label: '星',
      items: [
        // 「準備中」バッジ付きのリンク。
        {
          slug: 'stars/sirius',
          badge: { text: '準備中', variant: 'caution' },
        },
      ],
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星

  • シリウス 準備中

詳しくは、バッジの使用とカスタマイズを参照してください。

カスタムHTML属性

リンク要素にカスタムのHTML属性を追加するには、attrsプロパティを使用します。

以下の例では、リンクが新しいタブで開かれるよう、attrsを使用してtarget="_blank"属性を追加しています。また、リンクのラベルにカスタムのstyle属性を適用して斜体にします。

starlight({
  sidebar: [
    {
      label: 'リソース',
      items: [
        // 新しいタブで開かれる、NASAのウェブサイトへの外部リンク。
        {
          label: 'NASA',
          link: 'https://www.nasa.gov/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• リソース

  • NASA

自動生成されるリンクのカスタムHTML属性

autogenerate設定でattrsプロパティを定義することで、自動生成されるグループ内のすべてのリンクのHTML属性をカスタマイズできます。個々のページではsidebar.attrsフロントマターフィールドを使用してカスタム属性を指定でき、これはautogenerate.attrs設定とマージされます。

たとえば、以下の設定があるとします。

starlight({
  sidebar: [
    {
      label: '星座',
      autogenerate: {
        // 'constellations'ディレクトリのリンクグループを自動生成します。
        directory: 'constellations',
        // このグループ内のすべてのリンクラベルを斜体にします。
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
});

そして以下のファイル構造があるとします。

• ディレクトリsrc/

  • ディレクトリcontent/

    • ディレクトリdocs/

      • ディレクトリconstellations/

        • carina.md
        • centaurus.md
        • ディレクトリseasonal/

          • andromeda.md

すると、自動生成されるすべてのリンクが斜体になった以下のサイドバーが生成されます。

• 星座

  • りゅうこつ座
  • ケンタウルス座
  • seasonal

    • アンドロメダ座

国際化

リンクやグループのラベルをサポート対象の言語向けに翻訳するには、リンクやグループのエントリにtranslationsプロパティを使用します。BCP-47の言語タグ、たとえば"en"、"ar"、"zh-CN"をキーとして、翻訳されたラベルを値として指定します。labelプロパティは、デフォルトのロケールと、翻訳がない言語に対して使用されます。

starlight({
  sidebar: [
    {
      label: '星座',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: 'アンドロメダ座',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromeda',
        },
        {
          label: 'さそり座',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpius',
        },
      ],
    },
  ],
});

ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。

• Constelação

  • Andrômeda
  • Escorpião

内部リンクの国際化

内部リンクは、デフォルトでコンテンツのフロントマターの翻訳されたページタイトルを自動的に使用します。

starlight({
  sidebar: [
    {
      label: '星座',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        { slug: 'constellations/andromeda' },
        { slug: 'constellations/scorpius' },
      ],
    },
  ],
});

ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。

• Constelações

  • Andrômeda
  • Escorpião

多言語サイトでは、slugの値にURLの言語部分は含まれません。たとえば、en/introとpt-br/introにページがある場合、サイドバーを設定する際のスラグはintroとなります。

バッジの国際化

バッジのtextプロパティは、文字列か、多言語サイトの場合はロケールごとの値をもつオブジェクトを指定できます。オブジェクト形式を使用する場合、キーはBCP-47タグ（en、ar、zh-CNなど）である必要があります。

starlight({
  sidebar: [
    {
      label: '星座',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          slug: 'constellations/andromeda',
          badge: {
            text: {
              ja: '新規',
              'pt-BR': 'Novo',
            },
          },
        },
      ],
    },
  ],
});

ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。

• Constelações

  • Andrômeda Novo

グループを折りたたむ

collapsedプロパティをtrueに設定することで、リンクのグループをデフォルトで折りたためます。

starlight({
  sidebar: [
    {
      label: '星座',
      // デフォルトでグループを折りたたみます。
      collapsed: true,
      items: ['constellations/andromeda', 'constellations/orion'],
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星座

  • アンドロメダ座
  • オリオン座

自動生成されるグループは、親グループのcollapsed値に従います。

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // デフォルトでグループと自動生成されるサブグループを折りたたみます。
      collapsed: true,
      autogenerate: { directory: 'constellations' },
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星座

  • りゅうこつ座
  • ケンタウルス座
  • seasonal

    • アンドロメダ座

この動作は、autogenerate.collapsedプロパティを定義することで上書きできます。

starlight({
  sidebar: [
    {
      label: '星座',
      // 「星座」グループは折りたたみませんが、自動生成されるサブグループは折りたたみます。
      collapsed: false,
      autogenerate: { directory: 'constellations', collapsed: true },
    },
  ],
});

上の設定により、以下のサイドバーが生成されます。

• 星座

  • りゅうこつ座
  • ケンタウルス座
  • seasonal

    • アンドロメダ座