Astro Starlight で技術ドキュメントサイトを作る手順｜サイトマップ・検索・i18n 完全ガイド【2026年版】
Astro Starlight の最新機能でドキュメントサイトを構築する実践ガイド。自動サイトマップ生成、Pagefind 検索統合、多言語対応の実装手順を詳しく解説します。
はじめに
技術ドキュメントサイトの構築において、開発者体験とユーザー体験の両立は常に課題です。Markdown でコンテンツを管理しながら、高速な検索機能、多言語対応、SEO 最適化を実現するのは容易ではありません。
Astro Starlight は、こうした課題を解決するために設計されたドキュメントサイト専用のフレームワークです。2026年4月現在、Starlight は Astro 5.x をベースに、サイトマップ自動生成、Pagefind による検索統合、i18n サポートを標準機能として提供しています。
この記事では、Starlight を使った技術ドキュメントサイトの構築手順を、実際のコード例とともに詳しく解説します。特に以下の3つの機能に焦点を当てます。
- 自動サイトマップ生成と Google Search Console 連携
- Pagefind 統合による高速な全文検索
- i18n 対応と言語ごとの SEO 設定
Starlight プロジェクトのセットアップ
初期構築手順
Starlight プロジェクトは、npm create コマンドで簡単にセットアップできます。以下のコマンドを実行してください。
npm create astro@latest -- --template starlight対話形式のプロンプトで以下を入力します。
- プロジェクト名:
my-docs - TypeScript の使用:
Yes, strict - Git リポジトリ初期化:
Yes - 依存パッケージのインストール:
Yes
プロジェクト構造は以下のようになります。
my-docs/
├── src/
│ ├── content/
│ │ ├── docs/ # ドキュメントファイル（Markdown）
│ │ └── config.ts # コンテンツコレクション設定
│ └── env.d.ts
├── astro.config.mjs # Astro 設定ファイル
├── tsconfig.json
└── package.json基本設定
astro.config.mjs で Starlight の基本設定を行います。
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://yourdomain.com', // 本番環境のURL（サイトマップ生成に必須）
integrations: [
starlight({
title: 'My Docs',
description: '技術ドキュメントサイト',
social: {
github: 'https://github.com/yourusername/my-docs',
},
sidebar: [
{
label: 'ガイド',
items: [
{ label: 'はじめに', link: '/guides/getting-started/' },
{ label: 'インストール', link: '/guides/installation/' },
],
},
],
}),
],
});サイトマップ自動生成と SEO 最適化
Starlight のサイトマップ機能
Starlight は Astro の組み込みサイトマップ機能を活用し、ビルド時に sitemap-index.xml と sitemap-0.xml を自動生成します。
設定は astro.config.mjs に追加します。
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://yourdomain.com', // 必須：絶対URLのベース
integrations: [
starlight({
title: 'My Docs',
// Starlight はサイトマップを自動生成
}),
],
});ビルド後、dist/sitemap-index.xml が生成されます。
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>https://yourdomain.com/sitemap-0.xml</loc>
</sitemap>
</sitemapindex>Google Search Console への登録
サイトマップを Google にインデックスさせる手順は以下の通りです。
- Google Search Console にアクセス: https://search.google.com/search-console
- プロパティを追加: 対象ドメインを入力
- 所有権確認: HTML ファイルアップロードまたは DNS レコード追加
- サイトマップ送信: 左メニュー「サイトマップ」→「新しいサイトマップの追加」→
sitemap-index.xmlを入力
送信後、数日以内にインデックス状況がレポートに反映されます。
動的ページの除外設定
特定のページ（下書き、テスト環境専用ページなど）をサイトマップから除外する場合、astro.config.mjs でカスタマイズできます。
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://yourdomain.com',
integrations: [
starlight({
title: 'My Docs',
}),
],
integrations: [
// サイトマップカスタマイズ
{
name: 'custom-sitemap',
hooks: {
'astro:build:done': async ({ dir, pages }) => {
// 特定パターンを除外するロジックを追加可能
},
},
},
],
});Pagefind 統合による高速検索機能
Pagefind とは
Pagefind は、静的サイト向けの高速な全文検索ライブラリです。ビルド時にインデックスを生成し、クライアント側で軽量な JavaScript で検索を実行します。Starlight は Pagefind をデフォルトで統合しています。
Pagefind の有効化
Starlight プロジェクトでは、Pagefind は自動的に有効化されています。astro.config.mjs で明示的に設定する必要はありません。
ビルド時に以下のコマンドを実行すると、Pagefind インデックスが dist/pagefind/ に生成されます。
npm run build生成されるファイル構成:
dist/
├── pagefind/
│ ├── pagefind.js
│ ├── wasm.unknown.pagefind
│ ├── index/
│ └── fragment/
└── sitemap-index.xml検索 UI のカスタマイズ
Starlight の検索ボックスは、デフォルトでヘッダーに配置されています。デザインをカスタマイズする場合、CSS 変数を上書きします。
src/styles/custom.css を作成:
:root {
--sl-search-input-bg: #f5f5f5;
--sl-search-input-border: #ddd;
--sl-search-result-highlight: #ff6b6b;
}astro.config.mjs で読み込み:
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My Docs',
customCss: ['./src/styles/custom.css'],
}),
],
});検索対象のカスタマイズ
特定のセクションを検索対象から除外したい場合、Markdown のフロントマターで指定できます。
---
title: "内部ドキュメント"
pagefind: false # このページを検索対象から除外
---多言語対応（i18n）の実装
i18n 設定の基本
Starlight は、複数言語をネイティブサポートしています。astro.config.mjs で言語ごとのルートとラベルを定義します。
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://yourdomain.com',
integrations: [
starlight({
title: 'My Docs',
defaultLocale: 'ja', // デフォルト言語
locales: {
ja: {
label: '日本語',
lang: 'ja-JP',
},
en: {
label: 'English',
lang: 'en-US',
},
zh: {
label: '中文',
lang: 'zh-CN',
},
},
}),
],
});コンテンツの言語別配置
各言語のドキュメントは、src/content/docs/ 配下に言語コードごとのディレクトリで管理します。
src/content/docs/
├── ja/
│ ├── index.mdx
│ └── guides/
│ └── getting-started.mdx
├── en/
│ ├── index.mdx
│ └── guides/
│ └── getting-started.mdx
└── zh/
├── index.mdx
└── guides/
└── getting-started.mdx言語切り替えUIの表示
Starlight は、設定された言語に基づいて自動的に言語切り替えドロップダウンをヘッダーに表示します。ユーザーは /ja/guides/getting-started/ から /en/guides/getting-started/ へシームレスに移動できます。
言語ごとのSEO設定
各言語のメタデータは、Markdown のフロントマターで個別に設定できます。
日本語版（src/content/docs/ja/guides/getting-started.mdx）:
---
title: "はじめに"
description: "Starlight ドキュメントサイトの使い方を学びます"
---英語版（src/content/docs/en/guides/getting-started.mdx）:
---
title: "Getting Started"
description: "Learn how to use Starlight documentation site"
---Starlight は、各言語のページに自動的に <html lang="ja-JP"> や <link rel="alternate" hreflang="en-US"> を挿入します。
アーキテクチャ図：Starlight の仕組み
flowchart TD
A["開発者: Markdown作成"] --> B["Astro Build"]
B --> C["Starlight Integration"]
C --> D["サイトマップ生成"]
C --> E["Pagefind インデックス構築"]
C --> F["i18n ルーティング"]
D --> G["dist/sitemap-index.xml"]
E --> H["dist/pagefind/"]
F --> I["dist/ja/, dist/en/"]
G --> J["Google Search Console"]
H --> K["ユーザー: 検索クエリ"]
K --> L["Pagefind.js: クライアント検索"]
L --> M["検索結果表示"]この図は、Starlight のビルドプロセスと各機能の連携を示しています。Markdown からビルド、サイトマップ生成、検索インデックス構築、多言語ルーティングまでの流れを可視化しています。
パフォーマンス最適化
画像の最適化
Starlight は Astro の画像最適化機能を継承しています。.astro ファイル内で <Image> コンポーネントを使うと、自動的に WebP 変換とレスポンシブ画像が生成されます。
---
import { Image } from 'astro:assets';
import screenshot from '../assets/screenshot.png';
---
<Image src={screenshot} alt="ダッシュボードのスクリーンショット" />Lazy Loading とプリフェッチ
Starlight は、ページ遷移時に次のページを自動的にプリフェッチします。これにより、SPA ライクな高速なナビゲーションを実現しています。
設定は不要で、デフォルトで有効です。
実装時のトラブルシューティング
サイトマップが生成されない
原因: astro.config.mjs に site が設定されていない。
解決策:
export default defineConfig({
site: 'https://yourdomain.com', // 必ず絶対URLを設定
// ...
});Pagefind 検索が動作しない
原因: ビルド後のファイルを直接開いている（file:// プロトコル）。
解決策: ローカルサーバーでプレビューする。
npm run preview言語切り替えが表示されない
原因: locales に1つの言語しか定義されていない。
解決策: 最低2つの言語を設定する。
locales: {
ja: { label: '日本語', lang: 'ja-JP' },
en: { label: 'English', lang: 'en-US' },
},まとめ
Astro Starlight を使った技術ドキュメントサイト構築のポイントをまとめます。
- サイトマップ:
site設定だけで自動生成。Google Search Console に登録してインデックスを促進 - 検索機能: Pagefind がデフォルト統合済み。ビルド時に自動でインデックス生成
- i18n 対応:
locales設定で複数言語を管理。SEO 向けの hreflang も自動挿入 - パフォーマンス: 画像最適化、プリフェッチがデフォルトで有効
- カスタマイズ: CSS 変数、フロントマター、Astro フックで柔軟に拡張可能
Starlight は、技術ドキュメントサイトに必要な機能を標準装備しており、最小限の設定で本格的なサイトを構築できます。2026年4月時点で、Astro 5.x ベースの安定版として多くのオープンソースプロジェクトで採用されています。