ADR 022: Starlight (Astro) によるドキュメントサイトの構築

• Status: Accepted
• Date: 2026-04-22
• Deciders: Lead Engineer

Context

ADR や Design Doc を GitHub Pages で公開するにあたり、当初 Jekyll (minima テーマ + actions/jekyll-build-pages) を採用した。しかし以下の問題が発生した:

1. actions/jekyll-build-pages のメンテナンス停滞: 最終リリースが 2024 年で、依存するライブラリの脆弱性リスクが高まっている
2. Jekyll のカスタマイズ困難: minima テーマの header_pages 設定が期待通り動作せず、全ページがナビゲーションに表示される問題の解消に _includes/header.html のオーバーライドが必要だった
3. Ruby 依存: moonshot プロジェクトは Node.js/TypeScript ベースであり、Jekyll (Ruby) はツールチェインの異物となる

Decision

ドキュメントサイトの SSG (Static Site Generator) として Starlight (Astro) を採用する。

ドキュメントは moonshot 本体リポジトリ (docs/adr/, docs/design/) をソースオブトゥルースとし、公開用の moonshot-docs リポジトリに Starlight 用 front matter を付与して配置する。

技術構成

• Astro 6 + @astrojs/starlight: ドキュメント特化フレームワーク
• GitHub Pages: ホスティング (GitHub Actions で pnpm build → dist/ をデプロイ)
• Pagefind: Starlight 組み込みのローカル全文検索

Alternatives Considered

• Jekyll (minima) を継続: actions/jekyll-build-pages のメンテナンス停滞と、ナビゲーション制御の困難さから却下
• VitePress: Vue ベースで高機能だが、moonshot が React/Next.js プロジェクトであり Vue 依存は技術スタックの乖離となる。また検索機能に Algolia DocSearch の申請 or 設定が必要で、Starlight の組み込みローカル検索に比べセットアップコストが高い
• MkDocs (Material for MkDocs): Python 依存であり、Jekyll と同様のツールチェイン異物問題がある。機能は豊富だが ADR/Design Doc 程度の規模にはオーバースペック

Consequences

Positive

• サイドバー・検索・ダークモードがゼロコンフィグで整う
• Node.js エコシステムに統一され、pnpm でビルドが完結する
• Astro の Islands Architecture により、クライアント JS が最小限で高速
• actions/jekyll-build-pages への依存を排除し、サプライチェーンリスクを低減
• Pagefind によるローカル全文検索が外部サービス不要で動作する

Negative

• moonshot 本体の docs/ と moonshot-docs リポジトリの二重管理が発生する（ADR 追加時に手動同期が必要）
• Astro/Starlight の学習コストが若干発生する（ただし Markdown ファイルはほぼそのまま使用可能）

Deployment Architecture

1. moonshot (本リポジトリ) の docs/adr/** または docs/design/** が main に push される
2. trigger-docs-deploy.yml が repository_dispatch イベントを moonshot-docs リポジトリに送信
3. moonshot-docs 側の workflow が moonshot を sparse-checkout し、docs/ を Starlight front matter 付きで同期
4. Starlight でビルドし GitHub Pages へデプロイ