サイドバーのナビゲーション
サイドバーはユーザーがサイト内を移動するための主要な方法の1つであるため、サイドバーを整理することは良いドキュメントの鍵となります。Starlightでは、サイドバーのレイアウトとコンテンツをカスタマイズするためのオプション一式を提供しています。
デフォルトのサイドバー
Section titled “デフォルトのサイドバー”Starlightはデフォルトで、ドキュメントのファイルシステム構造に基づいてサイドバーを自動的に生成します。その際、各ファイルのtitleプロパティをサイドバーのエントリとして使用します。
たとえば以下のファイル構造があるとします。
ディレクトリsrc/
ディレクトリcontent/
ディレクトリdocs/
ディレクトリconstellations/
- andromeda.md
- orion.md
ディレクトリstars/
- betelgeuse.md
すると以下のサイドバーが自動的に生成されます。
自動生成されるサイドバーについては、自動生成されるグループのセクションで詳しく説明します。
リンクとリンクグループを追加する
Section titled “リンクとリンクグループを追加する”サイドバーのリンクと（折りたたみ可能なヘッダー内の）リンクグループを設定するには、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プロパティを追加します。
ページのフロントマターからサイドバーの表示を制御する方法について、詳しくは「自動生成されるリンクのカスタマイズ」を参照してください。
内部リンクの省略記法
Section titled “内部リンクの省略記法”内部リンクは、ページのスラグを文字列として渡すだけの省略記法でも指定できます。
たとえば、以下の設定は上記のslugを使用した設定と同等です。
starlight({ sidebar: ['constellations/andromeda', 'constellations/orion'],});その他のリンク
Section titled “その他のリンク”labelとlinkプロパティをもつオブジェクトを使用して、外部ページやドキュメント以外のページへのリンクを追加します。
starlight({ sidebar: [ // サイト内のドキュメント以外のページへのリンク。 { label: '流星商店', link: '/shop/' }, // NASAのウェブサイトへの外部リンク。 { label: 'NASA', link: 'https://www.nasa.gov/' }, ],});上の設定により、以下のサイドバーが生成されます。
折りたたみ可能な見出しの下に関連するリンクをグループ化することで、サイドバーに構造を追加できます。グループには、リンクと他のサブグループを含められます。
labelとitemsプロパティをもつオブジェクトを使用して、グループを追加します。labelはグループの見出しとして使用されます。items配列にリンクまたはサブグループを追加します。
starlight({ sidebar: [ // 「星座」というラベルのリンクグループ。 { label: '星座', items: [ 'constellations/carina', 'constellations/centaurus', // 季節の星座の入れ子になったリンクグループ。 { label: '季節の星座', items: [ 'constellations/andromeda', 'constellations/orion', 'constellations/ursa-minor', ], }, ], }, ],});上の設定により、以下のサイドバーが生成されます。
自動生成されるグループ
Section titled “自動生成されるグループ”Starlightはドキュメントのディレクトリに基づいて、サイドバーのグループを自動的に生成できます。これはグループ内のサイドバー項目を手動で入力したくない場合に便利です。
デフォルトでは、ページはファイルのslugに従ってアルファベット順に並べ替えられます。
labelとautogenerateプロパティをもつオブジェクトを使用して、自動生成されるグループを追加します。autogenerateの設定には、サイドバーのエントリに使用するdirectoryを指定する必要があります。たとえば、以下のように設定したとします。
starlight({ sidebar: [ { label: '星座', // constellationsディレクトリのリンクグループを自動生成します。 autogenerate: { directory: 'constellations' }, }, ],});そして以下のファイル構造があるとします。
ディレクトリsrc/
ディレクトリcontent/
ディレクトリdocs/
ディレクトリconstellations/
- carina.md
- centaurus.md
ディレクトリseasonal/
- andromeda.md
すると以下のサイドバーが生成されます。
自動生成されるリンクをフロントマターでカスタマイズする
Section titled “自動生成されるリンクをフロントマターでカスタマイズする”個々のページでsidebarフロントマターフィールドを使用して、自動生成されるリンクをカスタマイズできます。
フロントマターのサイドバーオプションにより、カスタムラベルの設定、カスタム属性の使用、リンクへのバッジの追加、サイドバーのリンクの非表示、独自のソート順の定義が可能です。
---title: 私のページsidebar: # このリンクのカスタムラベルを設定します label: カスタムサイドバーラベル # このリンクの順番をカスタマイズします（数字が小さいほど上に表示されます） order: 2 # このリンクにバッジを追加します badge: text: 新規 variant: tip---上記のフロントマターを設定したページと一緒に自動生成されるグループは、以下のサイドバーを生成します。
リンク、グループ、自動生成されるグループには、ラベルの横にバッジを表示するためのbadgeプロパティも含められます。
starlight({ sidebar: [ { label: '星', items: [ // 「超巨星」バッジ付きのリンク。 { slug: 'stars/persei', badge: '超巨星', }, ], }, // 「要更新」バッジ付きの自動生成されるグループ。 { label: '衛星', badge: '要更新', autogenerate: { directory: 'moons' }, }, ],});上の設定により、以下のサイドバーが生成されます。
バッジのバリアントとカスタムスタイル
Section titled “バッジのバリアントとカスタムスタイル”textとvariant、classプロパティをもつオブジェクトを使用して、バッジのスタイルをカスタマイズできます。
textは表示するコンテンツ、たとえば「新規」などを表わします。デフォルトでは、バッジにはサイトのアクセントカラーが使用されます。組み込みのバッジスタイルを使用するには、variantプロパティをnote、tip、danger、caution、successのいずれかに設定します。
また、classプロパティにCSSクラス名を設定することで、カスタムバッジスタイルを作成することも可能です。
starlight({ sidebar: [ { label: '星', items: [ // 「準備中」バッジ付きのリンク。 { slug: 'stars/sirius', badge: { text: '準備中', variant: 'caution' }, }, ], }, ],});上の設定により、以下のサイドバーが生成されます。
詳しくは、バッジの使用とカスタマイズを参照してください。
カスタムHTML属性
Section titled “カスタム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' }, }, ], }, ],});上の設定により、以下のサイドバーが生成されます。
自動生成されるリンクのカスタムHTML属性
Section titled “自動生成されるリンクのカスタム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
すると、自動生成されるすべてのリンクが斜体になった以下のサイドバーが生成されます。
リンクやグループのラベルをサポート対象の言語向けに翻訳するには、リンクやグループのエントリに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', }, ], }, ],});ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。
内部リンクの国際化
Section titled “内部リンクの国際化”内部リンクは、デフォルトでコンテンツのフロントマターの翻訳されたページタイトルを自動的に使用します。
starlight({ sidebar: [ { label: '星座', translations: { 'pt-BR': 'Constelações', }, items: [ { slug: 'constellations/andromeda' }, { slug: 'constellations/scorpius' }, ], }, ],});ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。
多言語サイトでは、slugの値にURLの言語部分は含まれません。たとえば、en/introとpt-br/introにページがある場合、サイドバーを設定する際のスラグはintroとなります。
バッジの国際化
Section titled “バッジの国際化”バッジの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', }, }, }, ], }, ],});ブラジルポルトガル語でドキュメントを閲覧すると、以下のサイドバーが生成されます。
グループを折りたたむ
Section titled “グループを折りたたむ”collapsedプロパティをtrueに設定することで、リンクのグループをデフォルトで折りたためます。
starlight({ sidebar: [ { label: '星座', // デフォルトでグループを折りたたみます。 collapsed: true, items: ['constellations/andromeda', 'constellations/orion'], }, ],});上の設定により、以下のサイドバーが生成されます。
自動生成されるグループは、親グループのcollapsed値に従います。
starlight({ sidebar: [ { label: 'Constellations', // デフォルトでグループと自動生成されるサブグループを折りたたみます。 collapsed: true, autogenerate: { directory: 'constellations' }, }, ],});上の設定により、以下のサイドバーが生成されます。
この動作は、autogenerate.collapsedプロパティを定義することで上書きできます。
starlight({ sidebar: [ { label: '星座', // 「星座」グループは折りたたみませんが、自動生成されるサブグループは折りたたみます。 collapsed: false, autogenerate: { directory: 'constellations', collapsed: true }, }, ],});上の設定により、以下のサイドバーが生成されます。