ページ

Starlightは、Markdownのフロントマターにより提供される柔軟なオプションを使用して、コンテンツに基づいてサイトのHTMLページを生成します。さらにStarlightプロジェクトは、Astroの強力なページ生成ツールに完全にアクセスできます。このガイドでは、Starlightのページ生成の仕組みについて説明します。

コンテンツページ

ファイルフォーマット

Starlightは、設定なしでMarkdownとMDXによってコンテンツを作成できます。Markdocのサポートを追加するには、実験的なAstroのMarkdocインテグレーションをインストールします。

ページの追加

.mdまたは.mdxファイルをsrc/content/docs/に作成することで、サイトに新しいページを追加できます。サブフォルダを使用してファイルを整理し、複数のパスセグメントを作成できます。

たとえば次のファイル構造は、example.com/hello-worldとexample.com/reference/faqにページを生成します。

ディレクトリsrc/
- ディレクトリcontent/
  - ディレクトリdocs/
    hello-world.md
    ディレクトリreference/
    faq.md

型安全なフロントマター

すべてのStarlightページは、ページの表示方法を制御するためのカスタマイズ可能な共通のフロントマタープロパティを共有しています。

---
title: こんにちは、世界！
description: これは私のStarlight製サイトのページです
---

何か重要なことを忘れてしまっていても、Starlightがあなたに教えてくれるでしょう。

カスタムページ

発展的なユースケースとしては、src/pages/ディレクトリを作成しておこなうカスタムページの追加があります。src/pages/ディレクトリはAstroのファイルベースルーティングを使用しており、他のページフォーマットに加えて.astroファイルをサポートしています。これは、完全にカスタムのレイアウトでページを作成したり、異なるデータソースからページを生成する必要がある場合に役立ちます。

たとえば以下のプロジェクトは、src/content/docs/のMarkdownコンテンツと、src/pages/のAstroとHTMLルートを混在させています。

ディレクトリsrc/
- ディレクトリcontent/
  - ディレクトリdocs/
    hello-world.md
- ディレクトリpages/
  - custom.astro
  - archived.html

詳しくはAstroドキュメントの「ページ」ガイドを参照してください。

カスタムページでStarlightのデザインを使用する

カスタムページでStarlightのデザインを使用するには、ページコンテンツを<StarlightPage />コンポーネントでラップします。これは、コンテンツを動的に生成したいものの、Starlightのデザインも使用したいような場合に役立ちます。

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
import CustomComponent from './CustomComponent.astro';
---

<StarlightPage frontmatter={{ title: '私のカスタムページ' }}>
  <p>これはカスタムコンポーネントを用いたカスタムページです:</p>
  <CustomComponent />
</StarlightPage>

Props

<StarlightPage />コンポーネントは以下のpropsを受け付けます。

`frontmatter`（必須）

type: StarlightPageFrontmatter

ページのフロントマタープロパティを設定します。これは、Markdownページのフロントマターと同様です。titleプロパティは必須ですが、その他のプロパティは任意です。

以下のプロパティはMarkdownのフロントマターと異なります。

slugプロパティはサポートされておらず、カスタムページのURLに基づいて自動的に設定されます。
editUrlオプションは、編集リンクを表示するためのURLが必要です。
自動生成されるリンクグループにページを表示する方法をカスタマイズするためのsidebarフロントマタープロパティは利用できません。<StarlightPage />コンポーネントを使用するページはコレクションの一部ではなく、自動生成されるサイドバーグループには追加できません。

`sidebar`

type: SidebarEntry[]
default: グローバルなsidebar設定値に基づき生成されるサイドバー

ページにカスタムのサイトナビゲーションサイドバーを設定します。未設定の場合、ページはデフォルトのグローバルサイドバーを使用します。

たとえば以下のページは、ホームページへのリンクと星座へのリンクグループによりデフォルトのサイドバーをオーバーライドします。サイドバーの現在のページはisCurrentプロパティを使用して設定され、またリンクアイテムにオプションのbadgeが追加されています。

<StarlightPage
  frontmatter={{ title: 'オリオン座' }}
  sidebar={[
    { label: 'ホーム', href: '/' },
    {
      label: '星座',
      items: [
        { label: 'アンドロメダ座', href: '/andromeda/' },
        { label: 'オリオン座', href: '/orion/', isCurrent: true },
        { label: 'こぐま座', href: '/ursa-minor/', badge: 'スタブ' },
      ],
    },
  ]}
>
  何らかのコンテンツ。
</StarlightPage>

`hasSidebar`

type: boolean
default: frontmatter.templateが'splash'の場合はfalse、それ以外の場合はtrue

ページにサイドバーを表示するかどうかを制御します。

`headings`

type: { depth: number; slug: string; text: string }[]
default: []

ページのすべての見出しの配列を指定します。指定された場合、Starlightはこれらの見出しからページの目次を生成します。

`dir`

type: 'ltr' | 'rtl'
default: 現在のロケールの記述方向

ページのコンテンツを記述する方向を設定します。

`lang`

type: string
default: 現在のロケールの言語

enやzh-CN、pt-BRなど、ページのBCP-47言語タグを設定します。

`isFallback`

type: boolean
default: false

現在の言語に対する翻訳がない結果、ページがフォールバックコンテンツを使用しているかどうかを示します。

ページ