手動セットアップ

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

Starlightをセットアップする

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

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

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

npx astro add starlight

pnpm astro add starlight

yarn astro add starlight

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

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

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

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

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コレクションを追加します。

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

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

コンテンツの追加

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

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

SSRを有効にするには、Astroドキュメントの「オンデマンドレンダリングアダプター」ガイドに従い、Starlightプロジェクトにサーバーアダプターを追加します。

Starlightによって生成されるドキュメントページは、プロジェクトの出力モードに関係なくデフォルトでプリレンダリングされます。Starlightページのプリレンダリングを無効にするには、prerender設定オプションをfalseに設定します。