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

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

デフォルトのサイドバー

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

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

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • components.md
        • i18n.md
      • Directoryreference/

        • 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/' },
	],
});

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

• CSSとスタイリング
• Astro

グループ

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

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）
  • スタイリング

    • CSS
    • Tailwind
    • Shiki

自動生成されるグループ

Starlightはドキュメントのディレクトリに基づいて、サイドバーのグループを自動的に生成できます。これはグループ内のサイドバー項目を手動で入力したくない場合に便利です。ページはデフォルトではファイル名のアルファベット順に並べ替えられます。

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

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

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

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • components.md
        • i18n.md
        • Directoryadvanced/

          • project-structure.md

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

• Guides

  • Components
  • Internationalization (i18n)
  • advanced

    • Project Structure

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

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

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

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

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

• ガイド

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

Note

フロントマターのsidebar設定は、自動生成されるリンクにのみ使用され、手動で定義されたリンクに対しては無視されます。

バッジ

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

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

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

• ガイド

  • コンポーネント 新規

バッジのバリアント

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

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

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

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

• ガイド

  • コンポーネント 実験的

国際化

リンクやグループのラベルをサポート対象の言語向けに翻訳するには、リンクやグループのエントリにtranslationsプロパティを使用します。labelプロパティは、デフォルトのロケールと、翻訳がない言語に対して使用されます。

starlight({
	sidebar: [
		{
			label: 'Guides',
			translations: {
				es: 'Guías',
			},
			items: [
				{
					label: 'Components',
					translations: {
						es: 'Componentes',
					},
					link: '/guides/components/',
				},
				{
					label: 'Internationalization (i18n)',
					translations: {
						es: 'Internacionalización (i18n)',
					},
					link: '/guides/i18n/',
				},
			],
		},
	],
});

スペイン語でドキュメントを閲覧すると、以下のサイドバーが生成されます。

• Guías

  • Componentes
  • Internacionalización (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