Skip to content

Latest commit

 

History

History
387 lines (255 loc) · 14.4 KB

components.mdx

File metadata and controls

387 lines (255 loc) · 14.4 KB
title description
コンポーネント
StarlightにおけるMDXでのコンポーネントの利用。

コンポーネントにより、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パッケージから利用できます。

タブ

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

<Tabs>と<TabItem>コンポーネントを使用して、タブインターフェースを表示できます。各<TabItem>は、ユーザーに表示するlabelを必要とします。また、任意のicon属性を指定すると、ラベルの横にStarlightの組み込みアイコンを1つ含められます。

# src/content/docs/example.mdx

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

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

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

シリウス、ベガ、ペテルギウス イオ、エウロパ、ガニメデ

カード

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

<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>

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

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

シリウス、ベガ、ペテルギウス イオ、エウロパ、ガニメデ

:::tip[ヒント] プロジェクトの主要な機能を示すために、ホームページでカードグリッドを使いましょう。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>

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

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

補足情報

「警告」や「吹き出し」とも呼ばれる補足情報（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>

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

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

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

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

// たとえばコードスニペット。
パスワードは誰にも教えないでください。

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

コード

ファイルやデータベース、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} />

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

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

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

インポートされたコード

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

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

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

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

import importedCode from '/src/env.d.ts?raw';

ファイルツリー

<FileTree>コンポーネントにより、ファイルアイコンと折りたたみ可能なサブディレクトリを使ってディレクトリの構造を表示できます。

<FileTree>内でMarkdownの順序なしリストを使い、ファイルとディレクトリの構造を指定します。サブディレクトリを作成するにはリストをネストさせます。あるいは、リストアイテムの最後に/を追加することで、中身を指定しないディレクトリとしてレンダリングできます。

以下の構文により、ファイルツリーの見た目をカスタマイズできます。

  • 名前を太字にして、ファイルやディレクトリをハイライトできます。たとえば**README.md**のようにします。
  • 名前の後ろにテキストを追加して、ファイルやディレクトリにコメントを追加できます。
  • ...または…を名前として使用して、ファイルやディレクトリのプレースホルダーを追加できます。
# src/content/docs/example.mdx

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

<FileTree>

- astro.config.mjs **重要**ファイル
- package.json
- README.md
- src
  - components
    - **Header.astro**
  - …
- pages/

</FileTree>

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

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

  • astro.config.mjs 重要ファイル
  • package.json
  • README.md
  • src
    • components
      • Header.astro
    • …
  • pages/

ステップ

<Steps>コンポーネントにより、順序のあるタスクのリストをスタイリングできます。これは、各ステップを明確に強調する必要があるような、複雑なステップバイステップのガイドに便利です。

<Steps>でMarkdown標準の順序付きリストをラップします。<Steps>内では、通常のMarkdownの構文はすべて使用できます。

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

<Steps>

1. MDXファイルにコンポーネントをインポートします。

   ```js
   import { Steps } from '@astrojs/starlight/components';
   ```

2. 順序付きリストの各アイテムを`<Steps>`でラップします。

</Steps>

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

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

  1. MDXファイルにコンポーネントをインポートします。

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

  2. 順序付きリストの各アイテムを<Steps>でラップします。

アイコン

import { Icon } from '@astrojs/starlight/components'; import IconsList from '~/components/icons-list.astro';

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" />

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

すべてのアイコン

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