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

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

デフォルトのサイドバー

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

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

ディレクトリsrc/
- ディレクトリcontent/
  - ディレクトリdocs/
    ディレクトリguides/
    components.md
    i18n.md
    ディレクトリreference/
    configuration.md

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

guides
- Components
- Internationalization (i18n)
reference
- Configuration Reference

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

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

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

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

リンク

labelとlinkプロパティをもつオブジェクトを使用して、内部または外部ページへのリンクを追加します。

starlight({
  sidebar: [
    // CSSとスタイリングガイドへのリンク。
    { label: 'CSSとスタイリング', link: '/guides/css-and-tailwind/' },
    // Astroウェブサイトへの外部リンク。
    { label: 'Astro', link: 'https://astro.build/' },
  ],
});

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

グループ

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

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

starlight({
  sidebar: [
    // 「ガイド」というラベルのリンクグループ。
    {
      label: 'ガイド',
      items: [
        { label: 'コンポーネント', link: '/guides/components/' },
        { label: '国際化（i18n）', link: '/guides/i18n/' },
        // 入れ子のリンクグープ。
        {
          label: 'スタイリング',
          items: [
            { label: 'CSS', link: '/ja/guides/css-and-tailwind/' },
            { label: 'Tailwind', link: '/ja/guides/css-and-tailwind/' },
            { label: 'Shiki', link: '/ja/guides/css-and-tailwind/' },
          ],
        },
      ],
    },
  ],
});

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

ガイド
- コンポーネント
- 国際化（i18n）
- スタイリング

自動生成されるグループ

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

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

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

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

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

ディレクトリsrc/
- ディレクトリcontent/
  - ディレクトリdocs/
    ディレクトリguides/
    components.md
    i18n.md
    ディレクトリadvanced/
    project-structure.md

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

Guides
- Components
- Internationalization (i18n)
- advanced
  - Project Structure

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

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

フロントマターのサイドバーオプションにより、カスタムラベルを設定したり、リンクにバッジを追加したり、サイドバーからリンクを非表示にしたり、カスタムのソート順を定義したりできます。

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

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

ガイド

バッジ

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

starlight({
  sidebar: [
    {
      label: 'ガイド',
      items: [
        // 「新規」バッジ付きのリンク。
        {
          label: 'コンポーネント',
          link: '/guides/components/',
          badge: '新規',
        },
      ],
    },
    // 「非推奨」バッジ付きの自動生成されるグループ。
    {
      label: 'リファレンス',
      badge: '非推奨',
      autogenerate: { directory: 'reference' },
    },
  ],
});

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

ガイド
- コンポーネント新規
リファレンス非推奨

バッジのバリアント

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

textは表示するコンテンツ、たとえば「新規」などを表わします。variantプロパティをnote、tip、danger、caution、successのいずれかに設定することで、サイトのアクセントカラーを使用するdefaultスタイルを上書きできます。

starlight({
  sidebar: [
    {
      label: 'ガイド',
      items: [
        // 「実験的」バッジ付きのリンク。
        {
          label: 'コンポーネント',
          link: '/guides/components/',
          badge: { text: '実験的', variant: 'caution' },
        },
      ],
    },
  ],
});

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

ガイド
- コンポーネント実験的

カスタムHTML属性

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

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

starlight({
  sidebar: [
    {
      label: 'ガイド',
      items: [
        // 新しいタブで開かれる、Astroドキュメントへの外部リンク。
        {
          label: 'Astro Docs',
          link: 'https://docs.astro.build/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

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

ガイド
- Astro Docs

国際化

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

starlight({
  sidebar: [
    {
      label: 'Guides',
      translations: {
        'pt-BR': 'Guias',
      },
      items: [
        {
          label: 'Components',
          translations: {
            'pt-BR': 'Componentes',
          },
          link: '/guides/components/',
        },
        {
          label: 'Internationalization (i18n)',
          translations: {
            'pt-BR': 'Internacionalização (i18n)',
          },
          link: '/guides/i18n/',
        },
      ],
    },
  ],
});

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

Guias
- Componentes
- Internacionalização (i18n)

グループを折りたたむ

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

starlight({
  sidebar: [
    {
      label: 'Guides',
      // デフォルトでグループを折りたたみます。
      collapsed: true,
      items: [
        { label: 'Components', link: '/guides/components/' },
        { label: 'Internationalization (i18n)', link: '/guides/i18n/' },
      ],
    },
  ],
});

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

Guides
- Components
- Internationalization (i18n)

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

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

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

Guides
- Components
- Internationalization (i18n)
- advanced
  - Project Structure

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

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

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

Guides
- Components
- Internationalization (i18n)
- advanced
  - Project Structure