コンポーネント

コンポーネントにより、UI やスタイリングの一部を一貫性を保って簡単に再利用できます。例として、リンクカードやYouTubeの埋め込みなどが考えられます。StarlightはMDXファイルでのコンポーネントの使用をサポートしており、すぐに使える一般的なコンポーネントもいくつか提供しています。

コンポーネントの作り方について、詳しくはAstroドキュメントを参照してください。

コンポーネントを使う

コンポーネントは、MDXファイルにインポートしてJSXタグとしてレンダリングすることで使用できます。HTMLタグのように見えますが、import文の名前と同じ大文字で始まります。

src/content/docs/example.mdx

---
title: Welcome to my docs
---

import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';

<SomeComponent prop="何か" />

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

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

Starlightのスタイルとの互換性

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

src/components/Example.astro

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

組み込みのコンポーネント

Starlightは、一般的なドキュメントのユースケースに対して組み込みのコンポーネントをいくつか提供しています。これらのコンポーネントは、@astrojs/starlight/componentsパッケージから利用できます。

タブ

<Tabs>と<TabItem>コンポーネントを使用して、タブインターフェースを表示できます。各<TabItem>は、ユーザーに表示するlabelを必要とします。

src/content/docs/example.mdx

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="恒星">シリウス、ベガ、ペテルギウス</TabItem>
  <TabItem label="衛星">イオ、エウロパ、ガニメデ</TabItem>
</Tabs>

上のコードは、ページに以下のタブを生成します。

恒星

シリウス、ベガ、ペテルギウス

衛星

イオ、エウロパ、ガニメデ

カード

<Card>コンポーネントを使用すると、Starlightのスタイルに合わせたボックス内にコンテンツを表示できます。十分なスペースがある場合は、複数のカードを<CardGrid>コンポーネントで囲むことで、カードを並べて表示できます。

<Card>はtitleを必須とし、また任意でStarlightの組み込みアイコンの1つを名前に設定したicon属性を含められます。

src/content/docs/example.mdx

import { Card, CardGrid } from '@astrojs/starlight/components';

<Card title="確認しよう">強調したい興味深いコンテンツ。</Card>

<CardGrid>
  <Card title="恒星" icon="star">
    シリウス、ベガ、ペテルギウス
  </Card>
  <Card title="衛星" icon="moon">
    イオ、エウロパ、ガニメデ
  </Card>
</CardGrid>

上のコードにより、ページに以下が生成されます。

確認しよう

強調したい興味深いコンテンツ。

恒星

シリウス、ベガ、ペテルギウス

衛星

イオ、エウロパ、ガニメデ

ヒント

プロジェクトの主要な機能を示すために、ホームページでカードグリッドを使いましょう。stagger属性を追加すると、カードの2番目の列を垂直方向にシフトして、視覚的な面白さを引き出します。

<CardGrid stagger>
  <!-- カード -->
</CardGrid>

リンクカード

<LinkCard>を使用すると、他のページへのリンクを目立たせることができます。

<LinkCard>はtitleとhref属性を必須とします。短いdescriptionや、targetなど他のリンク属性も指定できます。

十分なスペースがある場合、<CardGrid>により複数の<LinkCard>をグループ化して、カードを並べて表示できます。

src/content/docs/example.mdx

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<LinkCard
  title="Starlightのカスタマイズ"
  description="Starlightサイトをカスタマイズして、独自のスタイル、フォントなどを追加する方法について学びます。"
  href="/ja/guides/customization/"
/>

<CardGrid>
  <LinkCard
    title="Markdownでのコンテンツ作成"
    href="/ja/guides/authoring-content/"
  />
  <LinkCard title="コンポーネント" href="/ja/guides/components/" />
</CardGrid>

上のコードにより、ページに以下が生成されます。

Starlightのカスタマイズ Starlightサイトをカスタマイズして、独自のスタイル、フォントなどを追加する方法について学びます。

Markdownでのコンテンツ作成

コンポーネント

補足情報

「警告」や「吹き出し」とも呼ばれる補足情報（Asides）は、ページのメインコンテンツと並べて補助的な情報を表示するのに便利です。

<Aside>には、note（デフォルト）、tip、caution、dangerのいずれかのtypeを任意で指定できます。title属性を設定すると、補足情報のデフォルトのタイトルが上書きされます。

src/content/docs/example.mdx

import { Aside } from '@astrojs/starlight/components';

<Aside>カスタムタイトルなしのデフォルトの補足情報。</Aside>

<Aside type="caution" title="気を付けて！">
  カスタムタイトルを指定した警告用の補足情報。
</Aside>

<Aside type="tip">

その他のコンテンツも補足情報に含められます。

```js
// たとえばコードスニペット。
```

</Aside>

<Aside type="danger">パスワードは誰にも教えないでください。</Aside>

上のコードにより、ページに以下が生成されます。

ノート

カスタムタイトルなしのデフォルトの補足情報。

気を付けて！

カスタムタイトルを指定した警告用の補足情報。

ヒント

その他のコンテンツも補足情報に含められます。

// たとえばコードスニペット。

危険

パスワードは誰にも教えないでください。

Starlightは、<Aside>コンポーネントの代わりとして、MarkdownやMDXで補足情報をレンダリングするためのカスタム構文も提供しています。カスタム構文の詳細については、「Markdownでのコンテンツ作成」ガイドを参照してください。

アイコン

Starlightは、<Icon>コンポーネントを通じてコンテンツ内に表示可能な、一般的なアイコンのセットを提供しています。

<Icon>はnameを必須とし、任意でlabel、size、color属性を含められます。

src/content/docs/example.mdx

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

<Icon name="star" color="goldenrod" size="2rem" />

上のコードにより、ページに以下が生成されます。

すべてのアイコン

以下に、利用可能なすべてのアイコンとその名前を示します。アイコンをクリックすると、対応するコンポーネントのコードをコピーできます。

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

コード

ファイルやデータベース、APIなど、外部ソースからのデータをレンダリングするためMarkdownのコードブロックを使用できない場合に、<Code>コンポーネントを使用してシンタックスハイライトされたコードをレンダリングできます。

<Code>がサポートするプロパティの詳細については、Expressive Codeの「Code Component」ドキュメントを参照してください。

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';

export const exampleCode = `console.log('これはファイルやCMSから来た文字列!');`;
export const fileName = 'example.js';
export const highlights = ['ファイル', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

上のコードにより、ページに以下が生成されます。

example.js

console.log('これはファイルやCMSから来た文字列!');

インポートされたコード

Viteの?rawインポートサフィックスを使用して、任意のコードファイルを文字列としてインポートできます。

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />

上のコードにより、ページに以下が生成されます。

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />