🌟

もうドキュメントサイトは Starlight でいいんじゃない？

2025/07/03に公開

ドキュメントサイトを構築する機会があったので、試しに Starlight を使ってみた
必要な機能がだいたい揃っているし、i18n まわりの対応が他のフレームワークに比べて
整っている印象。使っていくうちに、タイトルの気持ちになったので雑に紹介しておこうと思う
なお、Starlight は Cloudflare Docs などでも利用されています。

標準機能

サイトナビゲーション
サイト内全文検索（Pagefind）
国際化（i18n）対応
SEO
読みやすいタイポグラフィ
コードのハイライト
モバイル（レスポンシブ）対応
Dark & Light モード対応
etc...

i18n

標準でたくさんの言語をサポートしているところが魅力的

アラビア語
イタリア語
インドネシア語
ウクライナ語
オランダ語
カタロニア語
ガリシア語
スウェーデン語
スペイン語
スロバキア語
チェコ語
デンマーク語
ドイツ語
トルコ語
ノルウェー語(ブークモール)
ハンガリー語
ヒンディー語
フランス語
ベトナム語
ヘブライ語
ペルシア語
ポーランド語
ポルトガル語
ラトビア語
ルーマニア語
ロシア語
英語
韓国語
中国語
中国語 (台湾)
日本語

フォールバックコンテンツ機能^[1]があるため、デフォルト以外の言語（翻訳コンテンツ）は後から適宜追加できます。

設定例

日本語（デフォルト）と英語に対応したドキュメントサイトの実装例です。

まずは、コンテンツ置き場を作っておきます。
このサンプルでは、src/content/docs/{lang}/guides/ がドキュメントファイル置き場になります。

$ mkdir -p src/content/docs/ja/guides
$ mkdir -p src/content/docs/en/guides
$ tree -d -L 4 --gitignore src/
src/
├── assets
└── content
    └── docs
        ├── en
        │   └── guides
        └── ja
            └── guides

8 directories

defaultLocale と locales を設定

astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: "My Docs",
      defaultLocale: "ja",
      locales: {
        ja: { label: "日本語" },
        en: { label: "English" },
      },
      sidebar: [
        {
          label: "ガイド",
          translations: {
            en: "Guides",
          },
          autogenerate: { directory: "guides" },
        },
      ],
    }),
  ],
});

このサンプルでは URL パスに必ず {lang} が含まれます。（コンテンツを提供する URL の一貫性を保つことができる）
ただし、このままだとドキュメントルートに対するアクセスで 404 エラーが発生するため、src/pages ディレクトリへ
index.html ファイルを作成しドキュメントページ（デフォルト言語）へのリダイレクトを追加しておきます。

$ mkdir src/pages
$ echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0;url=/ja/"></head></html>' > src/pages/index.html

多言語化対応に関する基本的な設定は概ね完了です。あとは、適宜コンテンツを追加してください。

デプロイガイド

Git リポジトリとホスティングサービスを連携して、自動デプロイするようにしておきましょう

Cloudflare Pages にデプロイしてみる

Wrangler を利用して、Cloudflare Pages にデプロイするだけなら
3 分程度でドキュメントサイトが構築できます。

プロジェクトを作成

$ npm create astro@latest -- --template starlight

コンテンツをビルド

$ npm run build

デプロイ

$ npx wrangler pages deploy dist

構築されたサイトは、すべての Lighthouse スコアが 💯 満点でした。

脚注

未翻訳のコンテンツがあっても、「未翻訳である旨の警告メッセージ」を添えてデフォルト言語のコンテンツを表示する ↩︎

GitHubで編集を提案

標準機能

i18n

設定例

デプロイガイド

Cloudflare Pages にデプロイしてみる

Discussion