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

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
```
---
import type { Props } from '@astrojs/starlight/props';
---

<a href="mailto:houston@example.com">メールしてね</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 type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/SocialIcons.astro';
---

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

組み込みコンポーネントをカスタムコンポーネント内でレンダリングする場合、

Astro.propsを展開します。これにより、レンダリングに必要なすべてのデータを受け取ることができます。
デフォルトのコンポーネント内に<slot />を追加します。これにより、コンポーネントに子要素が渡された場合、Astroがそれらをどこにレンダリングするかを知ることができます。

ページデータを使用する

Starlightコンポーネントをオーバーライドすると、カスタム実装側には、現在のページのすべてのデータを含む、標準のAstro.propsオブジェクトが渡されます。これらの値を使用して、コンポーネントテンプレートのレンダリング方法を制御することができます。

たとえば、ページのフロントマターの値をAstro.props.entry.dataとして取得できます。以下の例では、PageTitleを置き換えるコンポーネントが、現在のページのタイトルを表示するためにこれを使用しています。

---
import type { Props } from '@astrojs/starlight/props';

const { title } = Astro.props.entry.data;
---

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

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

利用可能なすべてのpropsについて、詳しくはオーバーライドリファレンスを参照してください。

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

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

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

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/Footer.astro';

const isHomepage = Astro.props.slug === '';
---

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

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