ページ
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ページは、ページの表示方法を制御するためのカスタマイズ可能な共通のフロントマタープロパティを共有しています。
何か重要なことを忘れてしまっていても、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のデザインも使用したいような場合に役立ちます。
Props
<StarlightPage />
コンポーネントは以下のpropsを受け付けます。
frontmatter
(必須)
type: StarlightPageFrontmatter
ページのフロントマタープロパティを設定します。これは、Markdownページのフロントマターと同様です。title
プロパティは必須ですが、その他のプロパティは任意です。
以下のプロパティはMarkdownのフロントマターと異なります。
slug
プロパティはサポートされておらず、カスタムページのURLに基づいて自動的に設定されます。editUrl
オプションは、編集リンクを表示するためのURLが必要です。- 自動生成されるリンクグループにページを表示する方法をカスタマイズするための
sidebar
フロントマタープロパティは利用できません。<StarlightPage />
コンポーネントを使用するページはコレクションの一部ではなく、自動生成されるサイドバーグループには追加できません。
sidebar
type: SidebarEntry[]
default: グローバルなsidebar
設定値に基づき生成されるサイドバー
ページにカスタムのサイトナビゲーションサイドバーを設定します。未設定の場合、ページはデフォルトのグローバルサイドバーを使用します。
たとえば以下のページは、ホームページへのリンクと星座へのリンクグループによりデフォルトのサイドバーをオーバーライドします。サイドバーの現在のページはisCurrent
プロパティを使用して設定され、またリンクアイテムにオプションのbadge
が追加されています。
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
現在の言語に対する翻訳がない結果、ページがフォールバックコンテンツを使用しているかどうかを示します。