コンテンツにスキップ
Starlight

手動セットアップ

入門で述べたように、新しいStarlightサイトを作成する最も簡単な方法は、create astroを使用することです。このガイドでは、既存のAstroプロジェクトにStarlightを追加する方法について説明します。

Starlightをセットアップする

このガイドを進めるには、既存のAstroプロジェクトが必要です。

Starlightインテグレーションの追加

StarlightはAstroのインテグレーションです。プロジェクトのルートディレクトリでastro addコマンドを実行してサイトに追加します。

Terminal window
npx astro add starlight

これにより、必要な依存関係がインストールされ、Astro設定ファイルのintegrations配列にStarlightが追加されます。

インテグレーションの設定

Starlightインテグレーションの設定は、astro.config.mjsファイルでおこないます。

まずはtitleを追加してみましょう。

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


export default defineConfig({
  integrations: [
    starlight({
      title: '私の楽しいドキュメントサイト',
    }),
  ],
});

他の利用可能なオプションについては、Starlightの設定リファレンスを参照してください。

コンテンツコレクションの設定

StarlightはAstroのコンテンツコレクションの上に構築されています。この設定はsrc/content/config.tsファイルでおこないます。

コンテンツの設定ファイルを作成または更新し、StarlightのdocsSchemaを使用するdocsコレクションを追加します。

src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';


export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
};

コンテンツの追加

以上でStarlightの設定は完了し、コンテンツを追加する準備が整いました！

src/content/docs/ディレクトリを作成し、index.mdファイルを追加します。これが新しいサイトのホームページになります。

src/content/docs/index.md
---
title: 私のドキュメント
description: Starlightで作成されたこのドキュメントサイトで、私のプロジェクトについてもっと学びましょう。
---


ようこそ私のプロジェクトへ！

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ページのオンデマンドレンダリングをサポートしたいと考えています。