StarLight 環境構築入門

Starlight 環境構築入門

Starlightは、Astroを基盤としたドキュメントサイト構築のためのフレームワークです。Astroのシンプルなセットアップをさらに最適化し、美しいドキュメントサイトを素早く立ち上げることができます。このガイドでは、Starlightを使って新しいドキュメントプロジェクトを作成し、コンテンツを追加する基本的な手順を解説します。

1. 新規プロジェクトの作成 🚀

まず、ターミナルを開き、以下のコマンドを実行してStarlightの公式インストーラーを起動します。

# npmを使う場合
npm create astro@latest -- --template starlight

このコマンドは、Astroのインストーラーを実行し、テンプレートとしてstarlightを直接指定します。

コマンドを実行すると、対話形式でいくつかの質問が表示されます。

• Where would you like to create your new project? (プロジェクトを作成する場所は？) プロジェクト名を入力します。例: ./my-starlight-docs

• Would you like to install dependencies? (依存関係をインストールしますか？) yを入力してnpmなどのパッケージをインストールします。

• Would you like to initialize a new git repository? (Gitリポジトリを初期化しますか？) バージョン管理にGitを使う場合はyを選択します。

セットアップが完了したら、作成されたプロジェクトのディレクトリに移動します。

cd my-starlight-docs

2. 開発サーバーの起動

プロジェクトの準備ができたので、開発サーバーを起動してみましょう。以下のコマンドを実行してください。

npm run dev

サーバーが起動すると、ターミナルにローカルURL（通常は http://localhost:4321）が表示されます。ブラウザでこのURLにアクセスすると、Starlightのドキュメントサイトが表示されます。このサーバーにはホットリロード機能があり、リアルタイムで変更を確認できます。

3. コンテンツの追加

Starlightは、src/content/docs/ディレクトリ内のファイルをドキュメントとして扱います。MarkdownまたはMDXファイルとしてコンテンツを作成するだけで、自動的にページが生成されます。

新しいページの作成

例として、「最初のページ」を作成してみましょう。src/content/docs/にfirst-page.mdxというファイルを作成します。

---
title: 最初のページ
description: これはStarlightで作成した最初のページです。
author: あなたの名前
date: 2023-10-01
tags: [Starlight, Astro, ドキュメント]
version: 1.0
category: ガイド
layout: default
status: published
---

# Starlightへようこそ！

これはStarlightで作成した最初のドキュメントページです。

**太字**や*斜体*など、通常のMarkdown構文を使ってコンテンツを記述できます。

ファイルを保存すると、開発サーバーが自動的に更新され、サイドバーに新しいページが表示されます。

フロントマターについて

Markdownファイルの冒頭にある---で囲まれた部分はフロントマターと呼ばれ、ページのメタデータを定義します。titleやdescriptionは必須項目です。

Starlight フロントマター完全リファレンス ✨

必須プロパティ

プロパティ名	型	説明
title	string	ページのタイトル。ブラウザのタブやサイドバーに表示されます。
description	string	ページの要約。SEOのメタタグとして使用されます。

レイアウトと表示に関するプロパティ

プロパティ名	型	説明
editUrl	boolean or string	ページ編集リンクの表示を制御します。falseで非表示、trueでデフォルトのGitHubリンク、stringでカスタムURLを設定します。
tableOfContents	boolean or object	ページの目次（TOC）を表示するか、およびどのレベルの見出しまで表示するかを制御します。
template	’doc’ or ‘splash’	ページのレイアウトテンプレートを指定します。splashはランディングページ用で、ヒーローセクションを表示します。
head	HeadConfig[]	ページの 要素にカスタムタグを追加します。外部スタイルシートやスクリプトの読み込みに便利です。
hero	HeroConfig	template: ‘splash’指定時にヒーローセクションを設定します。titleやtagline、actionsなどを定義できます。

ナビゲーションに関するプロパティ

プロパティ名	型	説明
sidebar	object	サイドバーの表示をカスタマイズします。labelで表示名を、orderで表示順を、badgeでバッジを制御します。
lastUpdated	boolean	ページの最終更新日を表示するかどうかを制御します。
prev	boolean or SidebarLink	ページ下部に前のページへのリンクを表示するかを制御します。
next	boolean or SidebarLink	ページ下部に次のページへのリンクを表示するかを制御します。
pagination	boolean	ページ下部に前後のページリンクを表示するかをまとめて制御します。

コンテンツのメタデータと表示オプション

プロパティ名	型	説明
pagefind	boolean	このページを検索インデックスに含めるかどうかを制御します。
slug	string	ページのURLをカスタマイズします。ファイル名とは異なるURLを設定できます。
lang	string	ページの言語コードを設定します。多言語サイトで使用します。

サイドバーのカスタマイズ

サイドバーの表示順やグループ分けは、src/content/config.tsで設定します。これにより、ドキュメントの構成を整理できます。

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

export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      // サイドバーのカスタマイズ
      sidebar: [
        {
          label: 'はじめに',
          items: [
            { label: '最初のページ', link: '/first-page/' },
            { label: 'もう一つのページ', link: '/another-page/' },
          ],
        },
      ],
    }),
  }),
};

Starlightは、ドキュメントの作成と管理を非常に簡単にする強力なツールです。このシンプルなセットアップから始めて、独自のドキュメントサイトを構築しましょう。