コンポーネントのオーバーライド

StarlightのデフォルトのUIと設定オプションは、柔軟に設計されており、さまざまなコンテンツで機能します。Starlightのデフォルトの見た目の大部分は、CSSと設定オプションによりカスタマイズできます。

デフォルトの内容に満足できない場合には、デフォルトのコンポーネントを拡張したり、オーバーライドしたり（完全に置き換えたり）するためのカスタムコンポーネントを作成することも可能です。

いつオーバーライドするか

以下の場合、Starlightのデフォルトコンポーネントをオーバーライドすると便利です。

カスタムCSSでは不可能な方法で、StarlightのUIの見た目を部分的に変更したい場合。
StarlightのUIの動作を部分的に変更したい場合。
Starlightの既存のUIに別のUIを追加したい場合。

オーバーライドの方法

オーバーライドしたいStarlightコンポーネントを選択します。コンポーネントの完全なリストは、オーバーライドリファレンスにあります。

どのコンポーネントをオーバーライドすればいいかわからない場合は、Starlight Overrides Mapを使用して、StarlightのUIコンポーネントの名前をインタラクティブに調べることができます。

この例では、ページのナビゲーションバーに表示される、StarlightのSocialIconsコンポーネントをオーバーライドします。
Starlightのコンポーネントを置き換えるAstroコンポーネントを作成します。この例では、連絡先のリンクをレンダリングします。
src/components/EmailLink.astro
```
---
const email = 'houston@example.com';
---

<a href=`mailto:${email}`>メールしてね</a>
```

astro.config.mjsのcomponents設定オプションで、カスタムコンポーネントを使用するようStarlightに指示します。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'オーバーライドを設定したドキュメント',
      components: {
        // デフォルトの`SocialIcons`コンポーネントをオーバーライドします。
        SocialIcons: './src/components/EmailLink.astro',
      },
    }),
  ],
});

組み込みコンポーネントを再利用する

StarlightのデフォルトのUIコンポーネントを、自分で作ったものと同じように使うことができます。これにより、Starlightの基本的なUIをデザインとしてすべて保持しながら、そこに別のUIを追加することができます。

以下の例は、デフォルトのSocialIconsコンポーネントと一緒に、メールリンクをレンダリングするカスタムコンポーネントです。

---
import Default from '@astrojs/starlight/components/SocialIcons.astro';
---

<a href="mailto:houston@example.com">メールしてね</a>
<Default><slot /></Default>

カスタムコンポーネント内で組み込みコンポーネントをレンダリングする場合は、デフォルトコンポーネント内に<slot />を追加します。これにより、コンポーネントに子要素が渡された場合、Astroがそれらをどこにレンダリングするかを知ることができます。

名前付きスロットを含むPageFrameやTwoColumnContentコンポーネントを再利用する場合は、これらのスロットを受け渡す必要があります。

以下の例は、受け渡しが必要なright-sidebarという名前付きスロットを含むTwoColumnContentコンポーネントを再利用するカスタムコンポーネントです。

---
import Default from '@astrojs/starlight/components/TwoColumnContent.astro';
---

<Default>
  <slot />
  <slot name="right-sidebar" slot="right-sidebar" />
</Default>

ページデータを使用する

Starlightコンポーネントをオーバーライドすると、現在のページのすべてのデータを含むグローバルなstarlightRouteオブジェクトにアクセスできます。これらの値を使用して、コンポーネントテンプレートのレンダリング方法を制御することができます。

以下の例では、PageTitleの代替コンポーネントが、コンテンツのフロントマターに設定された現在のページのタイトルを表示します。

---
const { title } = Astro.locals.starlightRoute.entry.data;
---

<h1 id="_top">{title}</h1>

<style>
  h1 {
    font-family: 'Comic Sans';
  }
</style>

利用可能なすべてのプロパティについて、詳しくはルートデータリファレンスを参照してください。

特定ページのみでのオーバーライド

コンポーネントのオーバーライドはすべてのページに適用されます。ただし、starlightRouteの値を使用して条件に応じてレンダリングすることで、カスタムUIを表示するタイミング、StarlightのデフォルトUIを表示するタイミング、あるいはまったく別のものを表示するタイミングを決定することができます。

以下は、StarlightのFooterをオーバーライドするコンポーネントの例です。ホームページでのみ「Starlightで作成 🌟」と表示し、それ以外のすべてのページではデフォルトのフッターを表示します。

---
import Default from '@astrojs/starlight/components/Footer.astro';

const isHomepage = Astro.locals.starlightRoute.id === '';
---

{
  isHomepage ? (
    <footer>Starlightで作成 🌟</footer>
  ) : (
    <Default>
      <slot />
    </Default>
  )
}

条件付きレンダリングについて、詳しくはAstroのテンプレート構文ガイドを参照してください。