手動セットアップ
入門で述べたように、新しいStarlightサイトを作成する最も簡単な方法は、create astro
を使用することです。このガイドでは、既存のAstroプロジェクトにStarlightを追加する方法について説明します。
Starlightをセットアップする
このガイドを進めるには、既存のAstroプロジェクトが必要です。
Starlightインテグレーションの追加
StarlightはAstroのインテグレーションです。プロジェクトのルートディレクトリでastro add
コマンドを実行してサイトに追加します。
これにより、必要な依存関係がインストールされ、Astro設定ファイルのintegrations
配列にStarlightが追加されます。
インテグレーションの設定
Starlightインテグレーションの設定は、astro.config.mjs
ファイルでおこないます。
まずはtitle
を追加してみましょう。
他の利用可能なオプションについては、Starlightの設定リファレンスを参照してください。
コンテンツコレクションの設定
StarlightはAstroのコンテンツコレクションの上に構築されています。この設定はsrc/content/config.ts
ファイルでおこないます。
コンテンツの設定ファイルを作成または更新し、StarlightのdocsSchema
を使用するdocs
コレクションを追加します。
コンテンツの追加
以上でStarlightの設定は完了し、コンテンツを追加する準備が整いました!
src/content/docs/
ディレクトリを作成し、index.md
ファイルを追加します。これが新しいサイトのホームページになります。
Starlightはファイルベースのルーティングを使用してます。そのため、src/content/docs/
にあるMarkdown、MDX、Markdocファイルはすべて、サイトのページへと変換されます。フロントマターのメタデータ(上記の例ではtitle
とdescription
フィールド)により、各ページの表示方法を変更できます。利用可能なオプションについては、フロントマターのリファレンスを参照してください。
既存サイトのためのヒント
既存のAstroプロジェクトがある場合は、Starlightを使用して、サイトにドキュメントセクションを迅速に追加できます。
サブパスへのStarlightの追加
Starlightのすべてのページをサブパスに追加するには、ドキュメントのコンテンツをsrc/content/docs/
のサブディレクトリに配置します。
たとえば、Starlightのページがすべて/guides/
で始まる場合は、コンテンツをsrc/content/docs/guides/
ディレクトリに追加します。
ディレクトリsrc/
ディレクトリcontent/
ディレクトリdocs/
ディレクトリguides/
- guide.md
- index.md
ディレクトリpages/
- …
- astro.config.mjs
将来的には、src/content/docs/
内にネストされたディレクトリを必要としないよう、このユースケースに対するサポートを改善する予定です。
StarlightとSSR
Astroドキュメントの「オンデマンドレンダリングアダプタ」ガイドに従うことで、Starlightをカスタムのオンデマンドレンダリングページと併用できます。
現在、Starlightによって生成されるドキュメントページは、プロジェクトの出力モードに関係なく常にプリレンダリングされます。近い内にStarlightページのオンデマンドレンダリングをサポートしたいと考えています。