Starlight に CMS を導入する

既存の Starlight ドキュメントサイトに、チームで使えるビジュアル CMS を導入します。管理者がリポジトリと公開方法を設定すれば、執筆者は Git コマンドを覚えずにガイド、ページ属性、対応コンポーネントを編集できます。

Starlight のサイト、URL、ビルドは維持します。このガイドでは、リポジトリの検出から本文とナビゲーションの変更を確認して公開するまでを進めます。

1. docs コレクションを確認する

Starlight を使う Astro アプリケーションとドキュメントファイルを含むリポジトリを用意します。標準の docs コレクションは Starlight のローダーと schema を使います。

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

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

すでに設定されている場合は、そのまま使ってください。対応する静的な schema 拡張でフィールドを追加・上書きできます。Prosefly は定義を読み取り、アプリケーションは実行しません。

2. 接続・スキャン後、ナビゲーションを確認する

組織設定 → リポジトリで GitHub リポジトリを接続し、リポジトリをスキャン を選びます。アカウント連携と GitHub App の認証手順は GitHub の接続をご覧ください。

検出された Starlight アプリケーション、文書ディレクトリ、コレクションの属性、エディターのプロファイル、標準ナビゲーション設定を確認します。コンテンツスペースと対応するナビゲーションの紐付けを確定し、インデックス作成を待ちます。

全体の流れでこの操作を試せます。

3. ガイドとページ属性を編集する

コンテンツ からガイドを開きます。Markdown と、アサイド、タブ、カード、ファイルツリーなどの対応 Starlight コンポーネントをビジュアル編集できます。プロパティ で タイトルや説明 を変更し、その他の対応フィールドは その他のプロパティ から開きます。

全体の流れでこの操作を試せます。

独自コンポーネントや、専用の操作がない式は ソースで編集できます。Starlight エディターのサンプルでも操作を試せます。登録は不要で、再読み込みすると内容がリセットされます。

4. 手動項目と自動グループを並べ替える

プロパティとアウトラインの横にある ナビゲーション を開きます。対応する静的な Starlight サイドバーでは、手動項目と自動ディレクトリを組み合わせられます。既存の starlight() 設定内の例です。

sidebar: [
  { label: 'Start Here', items: ['overview'] },
  { label: 'Guides', autogenerate: { directory: 'guides' } },
];

• 手動グループ：既存の編集可能なグループ内で対応項目を並べ替えたり、未掲載ページの配置先を選んだりできます。
• 自動グループ：autogenerate.directory が対象ページを決めます。同じディレクトリ内の既存ページをドラッグして並べ替えると、sidebar.order が更新されます。

全体の流れでこの操作を試せます。

自動ページの並べ替えで Markdown ファイル自体は移動しません。レビューを開く前に、ナビゲーションの保存完了を確認してください。この時点では下書きで、Git には書き込まれていません。

5. 変更ファイルを確認して公開する

公開前レビューを開き、すべての変更ファイルを確認します。手動サイドバーの変更では astro.config.mjs、自動ページの並べ替えでは frontmatter の sidebar.order が変わる場合があります。本文と一緒に確認してください。

全体の流れでこの操作を試せます。

コンテンツスペースに設定された Commit または Pull request で公開します。PR は対象ブランチへのマージが必要です。その後、既存の Starlight ビルドでサイトが生成・デプロイされます。完了したらページとサイドバーを確認します。

設定から編集可能な標準ナビゲーションを紐付けられない場合は、必要に応じて本文のみを公開します。この方法ではページはサイドバーに追加されません。操作の詳細はサイトナビゲーションと Git への公開をご覧ください。

6. 今の Starlight サイトを使い続ける。

Git への公開後、既存の Astro ビルドでサイトが生成・デプロイされます。プルリクエストは先にマージが必要です。下の一連の流れにある Web サイトのステージで、Starlight の例を確認できます。

全体の流れでこの操作を試せます。

一連の流れを試す

サンプルは編集から始まります。ステージ操作で接続、コンテンツの確認、編集、ナビゲーション、レビュー、Web サイトのプレビューを切り替えられます。

Prosefly/リポジトリ

getting-started.mdxProsefly / Starlight / Docs

Starlight

サンプルをリセット変更を確認

ビジュアルソース

ドキュメントパネル

エディターを読み込み中…

ガイドの編集例を適用下書きはこのページ内に保存

最初の更新を確認する

タイトル、本文、サイドバー上の位置、自動グループの順番を確認してください。Prosefly の外で設定やファイルを変えた場合は、再スキャンしてインデックスを更新してから編集を続けます。

次は Starlight 向け CMS の紹介、製品ドキュメントの管理、MDX コンポーネントのガイド、Starlight のコンテンツ作成ドキュメントをご覧ください。