Astro × Starlight カスタマイズ大全：ドキュメントサイトをブランド化する設計術

2025年10月7日

Astro

Astro × Starlight カスタマイズ大全：ドキュメントサイトをブランド化する設計術

ドキュメントサイトは、プロダクトの顔とも言える重要な存在です。技術的な情報を整理して提供するだけでなく、ブランドの世界観を体現する場でもあります。

Astro の公式ドキュメントテーマである Starlight は、高速でアクセシブルなドキュメントサイトを簡単に構築できる強力なツールですが、デフォルトのままでは他のサイトと差別化できません。本記事では、Starlight を徹底的にカスタマイズして、あなたのブランドに合わせた独自のドキュメントサイトを作る設計術を解説します。

背景

ドキュメントサイトに求められる要素

現代のドキュメントサイトには、単なる情報提供以上の役割が求められています。ユーザー体験、検索性、パフォーマンス、そしてブランドアイデンティティの統一が重要です。

Starlight は Astro のエコシステム内で開発された公式テーマで、以下の特徴を持っています：

高速なビルドとページ遷移: Astro のアイランドアーキテクチャを活用
アクセシビリティ: WCAG 2.1 準拠の設計
多言語対応: i18n を標準サポート
検索機能: Pagefind による高速な全文検索
ダークモード: デフォルトで実装済み

以下の図は、Starlight が提供する基本構造を示しています。

mermaidflowchart TB
  user["読者"] -->|アクセス| starlight["Starlight サイト"]
  starlight -->|ナビゲーション| nav["サイドバー / ヘッダー"]
  starlight -->|コンテンツ| content["Markdown / MDX"]
  starlight -->|検索| search["Pagefind 検索"]
  starlight -->|スタイル| theme["デフォルトテーマ"]

  theme -.->|カスタマイズ| custom["カスタムブランディング"]
  custom -->|CSS変数| colors["配色"]
  custom -->|コンポーネント上書き| components["独自UI"]
  custom -->|プラグイン| plugins["機能拡張"]

要点: Starlight はこれらの機能をデフォルトで提供しますが、カスタマイズすることで独自のブランド体験を構築できるのです。

Starlight の採用事例

世界中の多くのプロジェクトが Starlight を採用し、独自のカスタマイズを施しています。例えば、Astro 公式ドキュメント自体も Starlight で構築されており、洗練されたデザインと優れた UX を実現しています。

課題

デフォルトテーマの限界

Starlight のデフォルトテーマは優れていますが、そのままでは以下の課題があります：

#	課題	影響
1	ブランドカラーが反映されていない	企業やプロダクトの色が使われず、汎用的な見た目になる
2	独自のロゴやアイコンが配置できない	ブランド認知が低下し、他サイトとの差別化が困難
3	レイアウトの柔軟性が低い	独自のセクションやウィジェットを追加しにくい
4	カスタムコンポーネントの組み込みが複雑	React や Vue などのインタラクティブな要素を追加する方法が不明瞭
5	フォントやタイポグラフィの変更が難しい	ブランドのトーンが文字からも伝わらない

以下の状態図は、デフォルトテーマを使う場合とカスタマイズした場合のユーザー体験の違いを示しています。

mermaidstateDiagram-v2
  [*] --> DefaultTheme: Starlight 導入
  DefaultTheme --> GenericLook: デフォルトのまま
  GenericLook --> LowBrandRecognition: ブランド認知低下

  DefaultTheme --> Customization: カスタマイズ実施
  Customization --> BrandedDesign: ブランド色・ロゴ適用
  BrandedDesign --> HighBrandRecognition: ブランド認知向上
  HighBrandRecognition --> [*]

  LowBrandRecognition --> Customization: 改善アクション

ポイント: カスタマイズを行わないと、ブランドの独自性が失われ、ユーザーに印象を残せません。

技術的なハードル

カスタマイズを試みる際には、以下の技術的な壁に直面することがあります：

設定ファイルの複雑さ: どの設定項目がどの部分に影響するか分かりにくい
CSS のオーバーライド方法: スコープやカスケードの理解が必要
コンポーネントの置き換え: Astro のコンポーネントシステムへの理解が求められる
ビルドプロセスの調整: プラグインや統合の設定が必要

これらの課題を解決するために、段階的なカスタマイズのアプローチが必要です。

解決策

カスタマイズの全体像

Starlight のカスタマイズは、以下の 5 つのレイヤーで段階的に進めることができます。

mermaidflowchart TD
  layer1["レイヤー1:<br/>設定ファイル"] -->|基礎| layer2["レイヤー2:<br/>CSS 変数"]
  layer2 -->|スタイル| layer3["レイヤー3:<br/>カスタム CSS"]
  layer3 -->|コンポーネント| layer4["レイヤー4:<br/>コンポーネント上書き"]
  layer4 -->|機能拡張| layer5["レイヤー5:<br/>プラグイン・統合"]

  layer1 -.->|影響範囲| config["サイト構造・メタデータ"]
  layer2 -.->|影響範囲| colors["配色・フォント"]
  layer3 -.->|影響範囲| advanced["詳細なスタイル"]
  layer4 -.->|影響範囲| ui["UI コンポーネント"]
  layer5 -.->|影響範囲| features["独自機能"]

カスタマイズの段階: 基礎となる設定から始め、徐々に高度なカスタマイズに進むことで、効率的にブランド化を実現できます。

それで � は、各レイヤーを詳しく見ていきましょう。

レイヤー 1: 設定ファイルによる基本カスタマイズ

まずは Starlight の設定ファイルから始めます。これがすべてのカスタマイズの土台となりますので、丁寧に設定していきましょう。

プロジェクトのセットアップ

既存の Astro プロジェクトに Starlight を追加する場合、以下のコマンドを実行します。

bash# Starlight パッケージをインストール
yarn add @astrojs/starlight

基本設定ファイルの作成

astro.config.mjs ファイルで Starlight を統合します。このファイルがサイト全体の挙動を制御する中心的な役割を果たします。

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

export default defineConfig({
  integrations: [
    starlight({
      // 基本設定はここに記述
    }),
  ],
});

解説: integrations 配列に starlight() を追加することで、Starlight が有効になります。次に、具体的な設定項目を追加していきます。

サイトの基本情報を設定

サイトのタイトル、ロゴ、ソーシャルリンクなどを設定します。これらはヘッダーやメタデータに反映されます。

javascriptstarlight({
  title: 'あなたのプロダクト名',

  // ロゴの設定（SVG 推奨）
  logo: {
    src: './src/assets/logo.svg',
    replacesTitle: false, // true にするとタイトルテキストを非表示
  },

  // ソーシャルリンク
  social: {
    github: 'https://github.com/your-org/your-repo',
    twitter: 'https://twitter.com/your-account',
    discord: 'https://discord.gg/your-server',
  },
});

ポイント: ロゴは SVG 形式を使うと、解像度に依存せず美しく表示されます。replacesTitle を true にすると、テキストタイトルの代わりにロゴだけを表示できます。

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

ドキュメントサイトの使いやすさを左右するサイドバーナビゲーションを設定します。階層構造を明確にすることで、ユーザーが目的の情報にたどり着きやすくなります。

javascriptstarlight({
  // ...前述の設定

  sidebar: [
    {
      label: 'はじめに',
      items: [
        {
          label: 'クイックスタート',
          link: '/guides/getting-started/',
        },
        {
          label: 'インストール',
          link: '/guides/installation/',
        },
      ],
    },
    {
      label: 'ガイド',
      // autogenerate を使うと、フォルダ内のファイルから自動生成
      autogenerate: { directory: 'guides' },
    },
    {
      label: 'API リファレンス',
      items: [
        {
          label: 'コンポーネント',
          link: '/api/components/',
        },
        {
          label: 'ユーティリティ',
          link: '/api/utilities/',
        },
      ],
    },
  ],
});

便利な機能: autogenerate を使うと、指定したディレクトリ内の Markdown ファイルから自動的にサイドバー項目を生成してくれます。大量のドキュメントがある場合に非常に便利です。

多言語対応の設定

グローバルなユーザーベースを持つプロダクトでは、多言語対応が必須です。Starlight は i18n を標準サポートしています。

javascriptstarlight({
  // ...前述の設定

  // デフォルト言語の設定
  defaultLocale: 'ja',

  // サポートする言語
  locales: {
    ja: {
      label: '日本語',
      lang: 'ja',
    },
    en: {
      label: 'English',
      lang: 'en',
    },
    'zh-cn': {
      label: '简体中文',
      lang: 'zh-CN',
    },
  },
});

多言語サイトの構造: この設定により、/ja/、/en/、/zh-cn/ といったパスで言語別のページが提供されます。

カスタムヘッダーの設定

ヘッダーに独自のナビゲーションリンクを追加できます。プロダクトサイトやブログへのリンクを配置すると、サイト間の回遊性が高まります。

javascriptstarlight({
  // ...前述の設定

  customCss: [
    // カスタム CSS ファイルのパス（後述）
    './src/styles/custom.css',
  ],

  // ヘッダーのカスタムリンク
  head: [
    {
      tag: 'link',
      attrs: {
        rel: 'stylesheet',
        href: 'https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;700&display=swap',
      },
    },
  ],
});

フォントの読み込み: head 配置に任意のタグを追加できるので、Google Fonts などの外部フォントを読み込むことができます。

レイヤー 2: CSS 変数によるテーマカスタマイズ

設定ファイルでサイトの構造を整えたら、次は見た目をブランドに合わせてカスタマイズします。Starlight は CSS カスタムプロパティ（CSS 変数）を豊富に用意しており、簡単に配色やフォントを変更できます。

カスタム CSS ファイルの作成

src/styles/custom.css ファイルを作成し、CSS 変数を上書きします。このファイルが、あなたのブランドカラーを反映する中心的なスタイルシートになります。

css/* src/styles/custom.css */

/* ルート要素に CSS 変数を定義 */
:root {
  /* ブランドカラーの設定 */
  --sl-color-accent: #3b82f6; /* アクセントカラー（リンク、ボタンなど） */
  --sl-color-accent-high: #2563eb; /* アクセントカラーの濃い版 */
  --sl-color-accent-low: #93c5fd; /* アクセントカラーの薄い版 */

  /* テキストカラー */
  --sl-color-text: #1e293b; /* メインテキスト */
  --sl-color-text-accent: #3b82f6; /* 強調テキスト */

  /* 背景カラー */
  --sl-color-bg: #ffffff; /* ページ背景 */
  --sl-color-bg-nav: #f8fafc; /* ナビゲーション背景 */
  --sl-color-bg-sidebar: #f1f5f9; /* サイドバー背景 */
}

CSS 変数の仕組み: --sl-color-accent のような変数を変更するだけで、サイト全体の該当箇所が一括で更新されます。統一感のあるデザインを簡単に実現できるのが魅力です。

ダークモードのカスタマイズ

ダークモードにも対応したカラースキームを設定します。ユーザーの目に優しく、長時間の読書でも疲れにくいデザインが求められます。

css/* ダークモードの設定 */
:root[data-theme='dark'] {
  --sl-color-accent: #60a5fa;
  --sl-color-accent-high: #93c5fd;
  --sl-color-accent-low: #1e40af;

  --sl-color-text: #e2e8f0;
  --sl-color-text-accent: #60a5fa;

  --sl-color-bg: #0f172a;
  --sl-color-bg-nav: #1e293b;
  --sl-color-bg-sidebar: #334155;
}

ダークモードの判定: Starlight は自動的に data-theme="dark" 属性を <html> タグに付与するので、この属性をセレクタとして使えば簡単にダークモード用のスタイルを定義できます。

フォントのカスタマイズ

ブランドのトーンを表現する上で、フォント選びは非常に重要です。欧文フォントと和文フォントを組み合わせて、読みやすさと個性を両立させましょう。

css/* フォントファミリーの設定 */
:root {
  /* 本文フォント */
  --sl-font: 'Noto Sans JP', -apple-system, BlinkMacSystemFont,
    'Segoe UI', 'Hiragino Sans', sans-serif;

  /* 見出しフォント */
  --sl-font-heading: 'Noto Sans JP', -apple-system, BlinkMacSystemFont,
    'Segoe UI', 'Hiragino Sans', sans-serif;

  /* コードフォント */
  --sl-font-mono: 'Fira Code', 'Source Code Pro', Consolas,
    'Courier New', monospace;
}

フォントスタックの工夫: システムフォントをフォールバックとして指定することで、Web フォントの読み込みに失敗しても適切なフォントで表示されます。

サイズとスペーシングの調整

テキストサイズや行間、余白を調整することで、読みやすさが大きく向上します。特にドキュメントサイトでは、長文を読むことが多いため、適切な設定が重要です。

css:root {
  /* フォントサイズ */
  --sl-text-base: 16px; /* 基準サイズ */
  --sl-text-lg: 18px; /* 大きめのテキスト */
  --sl-text-xl: 20px; /* さらに大きいテキスト */
  --sl-text-2xl: 24px; /* 見出しなど */

  /* 行間 */
  --sl-line-height: 1.75; /* 本文の行間 */
  --sl-line-height-headings: 1.3; /* 見出しの行間 */

  /* スペーシング */
  --sl-content-width: 50rem; /* コンテンツの最大幅 */
  --sl-sidebar-width: 20rem; /* サイドバーの幅 */
}

読みやすさの秘訣: 行間を 1.75 程度に設定すると、日本語の文章が非常に読みやすくなります。欧文では 1.6 程度が一般的ですが、日本語では少し広めがおすすめです。

レイヤー 3: カスタム CSS による詳細なスタイリング

CSS 変数だけでは対応できない、より細かいスタイリングを行います。特定の要素にピンポイントでスタイルを適用したい場合に有効です。

ヘッダーのカスタマイズ

ヘッダーに独自のスタイルを適用して、ブランドの印象を強めます。グラデーションや影を使って、立体感のあるデザインにすることもできます。

css/* ヘッダーのカスタムスタイル */
header.header {
  background: linear-gradient(
    135deg,
    #667eea 0%,
    #764ba2 100%
  );
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  border-bottom: none;
}

/* ヘッダー内のリンク */
header.header a {
  color: white;
  font-weight: 600;
  transition: opacity 0.2s ease;
}

header.header a:hover {
  opacity: 0.8;
}

グラデーションの活用: 単色ではなくグラデーションを使うことで、モダンで洗練された印象を与えられます。ただし、やりすぎると読みにくくなるので注意しましょう。

サイドバーのスタイリング

サイドバーは頻繁に使われる UI なので、使いやすさとデザイン性を両立させたいところです。アクティブな項目を目立たせることで、現在位置が分かりやすくなります。

css/* サイドバーのカスタマイズ */
.sidebar {
  background-color: var(--sl-color-bg-sidebar);
  border-right: 1px solid rgba(0, 0, 0, 0.05);
}

/* サイドバーリンク */
.sidebar a {
  border-radius: 6px;
  padding: 0.5rem 1rem;
  transition: all 0.2s ease;
}

/* アクティブなリンク */
.sidebar a[aria-current='page'] {
  background-color: var(--sl-color-accent);
  color: white;
  font-weight: 600;
}

視覚的フィードバック: アクティブなページを背景色で強調することで、ユーザーが今どのページにいるのか一目で分かるようになります。

コードブロックのカスタマイズ

技術ドキュメントでは、コードブロックの見た目も重要です。読みやすく、コピーしやすいデザインを心がけましょう。

css/* コードブロックのスタイル */
pre {
  border-radius: 8px;
  padding: 1.5rem;
  background-color: #1e293b;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  overflow-x: auto;
}

/* インラインコード */
code {
  background-color: rgba(110, 118, 129, 0.1);
  border-radius: 4px;
  padding: 0.2em 0.4em;
  font-size: 0.9em;
  color: var(--sl-color-text-accent);
}

角丸と影: 角を丸くして影を付けることで、コードブロックがページから浮き上がり、視認性が高まります。

レスポンシブデザインの調整

モバイルデバイスでも快適に閲覧できるよう、レスポンシブ対応を強化します。画面サイズに応じてレイアウトを最適化しましょう。

css/* モバイル対応 */
@media (max-width: 768px) {
  :root {
    --sl-text-base: 14px;
    --sl-content-width: 100%;
  }

  .sidebar {
    position: fixed;
    left: -100%;
    transition: left 0.3s ease;
  }

  .sidebar.open {
    left: 0;
  }
}

モバイルファースト: スマートフォンでドキュメントを閲覧するユーザーも多いため、モバイルでの表示も必ず確認しましょう。

レイヤー 4: コンポーネントの上書き

さらに高度なカスタマイズとして、Starlight のデフォルトコンポーネントを独自のコンポーネントで置き換えることができます。これにより、UI の構造自体を変更できます。

コンポーネント上書きの仕組み

Starlight は特定のスロット（コンポーネント配置箇所）を提供しており、そこに独自のコンポーネントを差し込むことができます。以下の図は、コンポーネント上書きの流れを示しています。

mermaidsequenceDiagram
  participant Dev as 開発者
  participant Config as astro.config.mjs
  participant Starlight as Starlight
  participant Custom as カスタムコンポーネント

  Dev->>Config: components オプションを設定
  Config->>Starlight: カスタムコンポーネントパスを渡す
  Starlight->>Custom: デフォルトの代わりに読み込み
  Custom->>Starlight: レンダリング結果を返す
  Starlight->>Dev: カスタマイズされたページを表示

コンポーネント差し替えの流れ: 設定ファイルでパスを指定するだけで、Starlight が自動的にカスタムコンポーネントを読み込んでくれます。

カスタムヘッダーコンポーネントの作成

例えば、ヘッダーに独自の検索ボックスや CTA ボタンを追加したい場合、カスタムヘッダーコンポーネントを作成します。

まず、設定ファイルでコンポーネントの上書きを指定します。

javascript// astro.config.mjs
starlight({
  // ...前述の設定

  components: {
    // Header コンポーネントを上書き
    Header: './src/components/CustomHeader.astro',
  },
});

上書き可能なコンポーネント: Starlight は Header、Footer、Sidebar、PageFrame など、主要なコンポーネントを上書きできるようになっています。

次に、カスタムヘッダーコンポーネントを作成します。

astro---
// src/components/CustomHeader.astro
import { Icon } from '@astrojs/starlight/components';

// Props を受け取る
const { config } = Astro.props;
---

<header class="custom-header">
  <div class="header-container">
    <!-- ロゴ -->
    <a href="/" class="logo">
      <img src={config.logo.src} alt={config.title} />
      <span>{config.title}</span>
    </a>

    <!-- ナビゲーション -->
    <nav class="nav-links">
      <a href="/docs/">ドキュメント</a>
      <a href="/guides/">ガイド</a>
      <a href="/api/">API</a>
    </nav>

    <!-- CTA ボタン -->
    <a href="/get-started/" class="cta-button">
      今すぐ始める
    </a>
  </div>
</header>

<style>
  .custom-header {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    padding: 1rem 2rem;
  }

  .header-container {
    display: flex;
    align-items: center;
    justify-content: space-between;
    max-width: 1200px;
    margin: 0 auto;
  }

  .logo {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    color: white;
    font-weight: 700;
    font-size: 1.25rem;
  }

  .logo img {
    width: 32px;
    height: 32px;
  }

  .nav-links {
    display: flex;
    gap: 2rem;
  }

  .nav-links a {
    color: white;
    font-weight: 500;
    transition: opacity 0.2s;
  }

  .nav-links a:hover {
    opacity: 0.8;
  }

  .cta-button {
    background: white;
    color: #667eea;
    padding: 0.5rem 1.5rem;
    border-radius: 6px;
    font-weight: 600;
    transition: transform 0.2s;
  }

  .cta-button:hover {
    transform: translateY(-2px);
  }
</style>

Astro コンポーネント: Astro の独自記法を使うことで、HTML、CSS、JavaScript を 1 つのファイルにまとめられます。可読性が高く、保守しやすいのが特徴です。

カスタムフッターコンポーネント

フッターにも独自のリンクやソーシャルアイコンを追加できます。企業情報やプライバシーポリシーへのリンクを配置するのが一般的です。

設定ファイルでフッターを上書きします。

javascriptstarlight({
  components: {
    Header: './src/components/CustomHeader.astro',
    Footer: './src/components/CustomFooter.astro',
  },
});

フッターコンポーネントを作成します。

astro---
// src/components/CustomFooter.astro
const currentYear = new Date().getFullYear();
---

<footer class="custom-footer">
  <div class="footer-container">
    <div class="footer-section">
      <h3>製品</h3>
      <ul>
        <li><a href="/features/">機能</a></li>
        <li><a href="/pricing/">料金</a></li>
        <li><a href="/integrations/">連携</a></li>
      </ul>
    </div>

    <div class="footer-section">
      <h3>リソース</h3>
      <ul>
        <li><a href="/docs/">ドキュメント</a></li>
        <li><a href="/blog/">ブログ</a></li>
        <li><a href="/community/">コミュニティ</a></li>
      </ul>
    </div>

    <div class="footer-section">
      <h3>会社</h3>
      <ul>
        <li><a href="/about/">会社概要</a></li>
        <li><a href="/privacy/">プライバシーポリシー</a></li>
        <li><a href="/terms/">利用規約</a></li>
      </ul>
    </div>
  </div>

  <div class="footer-bottom">
    <p>&copy; {currentYear} あなたの会社名. All rights reserved.</p>
  </div>
</footer>

フッターの役割: フッターは SEO 的にも重要で、サイト内の主要ページへのリンクを配置することで、クローラビリティが向上します。

カスタムサイドバーコンポーネント

サイドバーに目次（TOC）以外の要素、例えば広告やフィードバックフォームへのリンクを追加したい場合も、カスタムコンポーネントで対応できます。

astro---
// src/components/CustomSidebar.astro
import { Sidebar } from '@astrojs/starlight/components';

const { sidebar, currentPage } = Astro.props;
---

<div class="custom-sidebar">
  <!-- デフォルトのサイドバーを含める -->
  <Sidebar sidebar={sidebar} currentPage={currentPage} />

  <!-- カスタムセクションを追加 -->
  <div class="feedback-section">
    <h4>フィードバック</h4>
    <p>このページは役に立ちましたか？</p>
    <div class="feedback-buttons">
      <button class="feedback-btn">👍 はい</button>
      <button class="feedback-btn">👎 いいえ</button>
    </div>
  </div>
</div>

既存コンポーネントの再利用: Starlight の既存コンポーネントをインポートして、その上下に独自要素を追加する方法がおすすめです。

レイヤー 5: プラグインと統合による機能拡張

最後に、プラグインや他の Astro 統合を使って、さらに高度な機能を追加します。これにより、単なるドキュメントサイト以上の体験を提供できます。

Astro 統合の活用

Astro はプラグインエコシステムが豊富です。代表的な統合を組み合わせることで、機能を大幅に拡張できます。

#	統合	用途
1	@astrojs/mdx	MDX を使ってコンポーネントを埋め込む
2	@astrojs/sitemap	SEO 用のサイトマップ自動生成
3	@astrojs/tailwind	Tailwind CSS を使った高速スタイリング
4	@astrojs/react	React コンポーネントを埋め込む
5	astro-og-canvas	OG 画像を自動生成

以下のコマンドで、必要な統合をインストールします。

bash# MDX と Sitemap をインストール
yarn add @astrojs/mdx @astrojs/sitemap

設定ファイルに統合を追加します。

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

export default defineConfig({
  site: 'https://your-site.com', // サイトマップ生成に必要

  integrations: [
    starlight({
      // Starlight の設定
    }),
    mdx(), // MDX サポート
    sitemap(), // サイトマップ自動生成
  ],
});

統合の順序: starlight() の後に他の統合を追加するのが一般的です。

MDX でインタラクティブなコンテンツを作成

MDX を使うと、Markdown の中に React や Vue などのコンポーネントを埋め込めます。ドキュメント内にインタラクティブなデモを配置したい場合に便利です。

まず、React 統合をインストールします。

bashyarn add @astrojs/react react react-dom

設定ファイルに追加します。

javascriptimport react from '@astrojs/react';

export default defineConfig({
  integrations: [
    starlight({
      // ...
    }),
    mdx(),
    react(),
  ],
});

React コンポーネントを作成します。

jsx// src/components/InteractiveDemo.jsx
import { useState } from 'react';

export default function InteractiveDemo() {
  const [count, setCount] = useState(0);

  return (
    <div className='interactive-demo'>
      <h3>インタラクティブなデモ</h3>
      <p>現在のカウント: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        カウントアップ
      </button>
      <button onClick={() => setCount(0)}>リセット</button>
    </div>
  );
}

React の活用: Starlight は静的サイトですが、部分的に React を使うことで、インタラクティブな要素を追加できます。

MDX ファイル内でコンポーネントをインポートして使います。

mdx---
title: インタラクティブガイド
---

# インタラクティブガイド

このページでは、実際に操作できるデモを用意しています。

import InteractiveDemo from '../../components/InteractiveDemo.jsx';

<InteractiveDemo client:load />

上記のデモを試してみてください。

client:load ディレクティブ: Astro では、コンポーネントをクライアント側で動作させるために client: ディレクティブを指定します。client:load はページ読み込み時にすぐに実行されます。

検索機能の強化

Starlight はデフォルトで Pagefind を使った検索機能を提供していますが、Algolia DocSearch などの外部サービスと統合することで、さらに高度な検索を実現できます。

Algolia DocSearch を統合する例を見てみましょう。まず、Algolia の設定を取得します。

javascript// astro.config.mjs
starlight({
  // ...前述の設定

  // Algolia DocSearch の設定
  head: [
    {
      tag: 'link',
      attrs: {
        rel: 'preconnect',
        href: 'https://your-algolia-app-id.algolia.net',
        crossorigin: 'anonymous',
      },
    },
    {
      tag: 'script',
      attrs: {
        src: 'https://cdn.jsdelivr.net/npm/@docsearch/js@3',
      },
    },
  ],
});

カスタムスクリプトで Algolia を初期化します。

javascript// public/algolia-init.js
document.addEventListener('DOMContentLoaded', () => {
  docsearch({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    container: '#docsearch',
  });
});

検索の重要性: ドキュメントサイトでは、ユーザーが目的の情報を素早く見つけられることが最優先です。高性能な検索機能は UX を大きく向上させます。

OG 画像の自動生成

ソーシャルメディアでシェアされたときに美しいプレビューが表示されるよう、OG 画像を自動生成します。

bashyarn add astro-og-canvas

設定ファイルに追加します。

javascriptimport { defineConfig } from 'astro/config';
import ogImage from 'astro-og-canvas';

export default defineConfig({
  integrations: [
    starlight({
      // ...
    }),
    ogImage(),
  ],
});

各ページの frontmatter で OG 画像を設定します。

mdx---
title: カスタマイズガイド
ogImage:
  title: Starlight カスタマイズガイド
  description: ドキュメントサイトをブランド化する方法
---

OG 画像の効果: Twitter や Facebook でシェアされたときに、魅力的な画像が表示されることで、クリック率が大幅に向上します。

具体例

ここまで解説した内容を総合して、実際のカスタマイズ例を見ていきましょう。架空の SaaS プロダクト「CloudSync」のドキュメントサイトを構築する想定です。

プロジェクト構成

最終的なプロジェクト構造は以下のようになります。

mermaidflowchart TD
  root["プロジェクトルート"] --> config["astro.config.mjs<br/>(設定ファイル)"]
  root --> src["src/"]

  src --> content["content/<br/>(Markdown コンテンツ)"]
  src --> components["components/<br/>(カスタムコンポーネント)"]
  src --> styles["styles/<br/>(CSS ファイル)"]
  src --> assets["assets/<br/>(画像・ロゴ)"]

  content --> docs["docs/<br/>(ドキュメント)"]
  content --> guides["guides/<br/>(ガイド)"]
  content --> api["api/<br/>(API リファレンス)"]

  components --> header["CustomHeader.astro"]
  components --> footer["CustomFooter.astro"]
  components --> demo["InteractiveDemo.jsx"]

  styles --> custom["custom.css"]

プロジェクト構成のポイント: コンテンツ、コンポーネント、スタイルを明確に分離することで、保守性が向上します。

完全な設定ファイル

すべての設定を統合した astro.config.mjs の最終形です。

javascript// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import react from '@astrojs/react';

export default defineConfig({
  site: 'https://docs.cloudsync.example.com',

  integrations: [
    starlight({
      title: 'CloudSync',

      logo: {
        src: './src/assets/cloudsync-logo.svg',
        replacesTitle: false,
      },

      social: {
        github: 'https://github.com/cloudsync/cloudsync',
        twitter: 'https://twitter.com/cloudsync',
        discord: 'https://discord.gg/cloudsync',
      },

      defaultLocale: 'ja',
      locales: {
        ja: {
          label: '日本語',
          lang: 'ja',
        },
        en: {
          label: 'English',
          lang: 'en',
        },
      },

      sidebar: [
        {
          label: 'はじめに',
          items: [
            {
              label: 'クイックスタート',
              link: '/guides/getting-started/',
            },
            {
              label: 'インストール',
              link: '/guides/installation/',
            },
          ],
        },
        {
          label: 'ガイド',
          autogenerate: { directory: 'guides' },
        },
        {
          label: 'API リファレンス',
          autogenerate: { directory: 'api' },
        },
      ],

      customCss: ['./src/styles/custom.css'],

      components: {
        Header: './src/components/CustomHeader.astro',
        Footer: './src/components/CustomFooter.astro',
      },

      head: [
        {
          tag: 'link',
          attrs: {
            rel: 'stylesheet',
            href: 'https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;700&display=swap',
          },
        },
      ],
    }),
    mdx(),
    sitemap(),
    react(),
  ],
});

設定の全体像: すべてのカスタマイズがこの 1 つのファイルに集約されています。各セクションがどの機能を制御しているか、コメントを追加すると保守しやすくなります。

カスタム CSS の完全版

ブランドカラーを反映した CSS の完全版です。

css/* src/styles/custom.css */

/* Google Fonts の読み込み */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;600;700&display=swap');

/* ライトモードの設定 */
:root {
  /* ブランドカラー（CloudSync のコーポレートカラー） */
  --sl-color-accent: #0ea5e9; /* スカイブルー */
  --sl-color-accent-high: #0284c7;
  --sl-color-accent-low: #7dd3fc;

  /* テキストカラー */
  --sl-color-text: #1e293b;
  --sl-color-text-accent: #0ea5e9;

  /* 背景カラー */
  --sl-color-bg: #ffffff;
  --sl-color-bg-nav: #f8fafc;
  --sl-color-bg-sidebar: #f1f5f9;

  /* フォント */
  --sl-font: 'Noto Sans JP', -apple-system, BlinkMacSystemFont,
    sans-serif;
  --sl-font-heading: 'Noto Sans JP', -apple-system, BlinkMacSystemFont,
    sans-serif;
  --sl-font-mono: 'Fira Code', 'Consolas', monospace;

  /* タイポグラフィ */
  --sl-text-base: 16px;
  --sl-line-height: 1.75;
  --sl-line-height-headings: 1.3;

  /* レイアウト */
  --sl-content-width: 50rem;
  --sl-sidebar-width: 20rem;
}

/* ダークモードの設定 */
:root[data-theme='dark'] {
  --sl-color-accent: #38bdf8;
  --sl-color-accent-high: #7dd3fc;
  --sl-color-accent-low: #0369a1;

  --sl-color-text: #e2e8f0;
  --sl-color-text-accent: #38bdf8;

  --sl-color-bg: #0f172a;
  --sl-color-bg-nav: #1e293b;
  --sl-color-bg-sidebar: #334155;
}

/* ヘッダーのカスタマイズ */
header.header {
  background: linear-gradient(
    135deg,
    #0ea5e9 0%,
    #0284c7 100%
  );
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* サイドバーのカスタマイズ */
.sidebar a[aria-current='page'] {
  background-color: var(--sl-color-accent);
  color: white;
  font-weight: 600;
  border-radius: 6px;
}

/* コードブロック */
pre {
  border-radius: 8px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

/* ボタンスタイル */
.cta-button {
  background: white;
  color: var(--sl-color-accent);
  padding: 0.5rem 1.5rem;
  border-radius: 6px;
  font-weight: 600;
  transition: transform 0.2s, box-shadow 0.2s;
}

.cta-button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(14, 165, 233, 0.3);
}

/* レスポンシブ対応 */
@media (max-width: 768px) {
  :root {
    --sl-text-base: 14px;
  }
}

CSS の保守性: セクションごとにコメントを入れることで、後から見返したときにどの部分がどこに影響するか一目で分かります。

インタラクティブなデモページ

MDX を使って、実際に操作できるデモページを作成します。

mdx---
title: API クライアントの使い方
description: CloudSync API クライアントのインタラクティブなデモ
---

import InteractiveDemo from '../../components/ApiDemo.jsx';

# API クライアントの使い方

CloudSync API クライアントを使うと、わずか数行のコードでクラウドストレージと連携できます。

# クイックスタート

以下のデモで、実際に API を試してみましょう。

<InteractiveDemo client:load />

# インストール

API クライアントをインストールします。

```bash
yarn add @cloudsync/api-client
```

基本的な使い方

クライアントを初期化して、ファイルをアップロードします。

typescriptimport { CloudSyncClient } from '@cloudsync/api-client';

// クライアントを初期化
const client = new CloudSyncClient({
  apiKey: 'your-api-key',
  region: 'us-west-2',
});

// ファイルをアップロード
const result = await client.upload({
  file: fileBlob,
  path: '/documents/report.pdf',
});

console.log('アップロード完了:', result.url);

このように、シンプルな API でファイル操作が可能です。

perl
**MDX の利点**: Markdown の簡潔さと、コンポーネントの柔軟性を両立できます。技術ドキュメントとインタラクティブなデモを同じページに配置できるのが魅力です。

## デプロイとパフォーマンス最適化

カスタマイズしたサイトをビルドしてデプロイします。

````bash
# プロダクションビルド
yarn build

# ビルド結果をプレビュー
yarn preview

パフォーマンスのポイント: Astro は静的サイトを生成するので、非常に高速です。Lighthouse スコアで 90 点以上を目指しましょう。

Vercel や Netlify にデプロイする場合、設定ファイルは不要です。リポジトリをリンクするだけで自動的にビルド・デプロイされます。

bash# Vercel にデプロイ（Vercel CLI を使う場合）
yarn global add vercel
vercel

継続的デプロイ: Git リポジトリにプッシュすると自動的にデプロイされるように設定すれば、ドキュメントの更新が楽になります。

まとめ

Starlight を使ったドキュメントサイトのカスタマイズは、5 つのレイヤーに分けて段階的に進めることで、効率的にブランド化を実現できます。

カスタマイズの 5 つのレイヤー

レイヤー	内容	難易度	効果
1	設定ファイル	★☆☆	サイト構造・基本情報の設定
2	CSS 変数	★★☆	配色・フォントのブランド化
3	カスタム CSS	★★★	詳細なスタイリング
4	コンポーネント上書き	★★★★	UI 構造の変更
5	プラグイン・統合	★★★★★	機能拡張・インタラクティブ要素