コンポーネントの使用

コンポーネントを使用すると、UIの一部やスタイリングを一貫して簡単に再利用できます。例えば、リンクカードやYouTube埋め込みなどが挙げられます。StarlightはMDXとMarkdocファイルでのコンポーネントの使用をサポートしており、またよく使う共通コンポーネントも複数提供しています。

Astro Docsでコンポーネントの作成方法についてさらに学ぶ。

MDXでコンポーネントを使用する

コンポーネントを使用するには、MDXファイルにインポートし、JSXタグとしてレンダリングします。見た目はHTMLタグに似ていますが、import文で指定した名前に合わせて先頭が大文字で始まります。

---
title: 私のドキュメントへようこそ
---

import { Icon } from '@astrojs/starlight/components';
import CustomCard from '../../components/CustomCard.astro';

<Icon name="open-book" />

<CustomCard>
  コンポーネントには**ネストされたコンテンツ**も含められます。
</CustomCard>

StarlightはAstroを基盤としているため、MDXファイルでは、AstroがサポートしているUIフレームワーク（React、Preact、Svelte、Vue、Solid、Alpine）で作成したコンポーネントを利用できます。詳しくは、AstroドキュメントのMDXでコンポーネントを使用するを参照してください。

Markdocでコンポーネントを使用する

Markdocのセットアップガイドに従って、Markdocでコンテンツを作成するためのサポートを追加してください。

Starlight Markdocプリセットを使用すると、Markdocの{% %}タグ構文でStarlightの組み込みコンポーネントを使用できます。MDXとは異なり、Markdocではコンポーネントをインポートする必要がありません。以下の例では、MarkdocファイルでStarlightのカードコンポーネントをレンダリングしています。

---
title: 私のドキュメントへようこそ
---

{% card title="星" icon="star" %}
シリウス、ベガ、ベテルギウス
{% /card %}

Markdocファイルでのコンポーネントの使用方法についての詳細は、AstroのMarkdocインテグレーションドキュメントを参照してください。

組み込みコンポーネント

Starlightは、一般的なドキュメントのユースケースに対応した組み込みコンポーネントを提供しています。これらのコンポーネントは、MDXファイルでは@astrojs/starlight/componentsパッケージから、MarkdocファイルではStarlight Markdocプリセットから利用できます。

利用可能なコンポーネントの一覧と使用方法については、サイドバーを参照してください。

Starlightのスタイルとの互換性

Starlightは、Markdownコンテンツにデフォルトのスタイリングを適用します。例えば、要素間にマージンを追加します。これらのスタイルがコンポーネントの外観と競合する場合は、not-contentクラスをコンポーネントに設定して無効化できます。

<div class="not-content">
  <p>Starlightのデフォルトのコンテンツスタイリングの影響を受けません。</p>
</div>

コンポーネントのprops

astro/typesのComponentProps型を使用すると、コンポーネント自体がPropsをエクスポートしていない場合でも、コンポーネントが受け取れるPropsを参照できます。これは、既存のコンポーネントをラップしたり拡張したりする際に便利です。

以下の例では、ComponentPropsを使用してStarlight組み込みのBadgeコンポーネントが受け取るpropsの型を取得しています。

---
import type { ComponentProps } from 'astro/types';
import { Badge } from '@astrojs/starlight/components';

type BadgeProps = ComponentProps<typeof Badge>;
---