Astro Starlight が『OSSドキュメントサイトの本命』に
OSSプロジェクト・APIプロダクト・社内ドキュメントの構築で、従来はDocusaurus・MkDocs・Mintlify等が選択肢でしたが、Astro StarlightがAstroチーム公式の選択肢として2024年以降急速にシェアを伸ばしました。Markdown/MDX対応・i18n標準・検索組み込み・サイドバー自動生成等を最小設定で実現でき、Cloudflare/Vercel/Astro自社が本番採用しています。
採用すべき5つのシグナル
- 新規ドキュメントサイトを最短で構築したい
- Markdown/MDXで書きたい・複雑な設定は避けたい
- i18n（多言語対応）が必要
- Vercel/Cloudflare等への静的デプロイ前提
- OSS・無料・自由度高めを優先
Docusaurus/Mintlify/Starlight比較
Docusaurus: Meta製・React基盤・機能フル装備・複雑。
Mintlify: SaaS・モダンUI・有料プラン中心。
Starlight: Astro公式・無料・OSS・最短構築・カスタマイズ柔軟。
MkDocs: Python・シンプル・GitHub Pages向き。
使い分け: モダンUI・最短構築はStarlight・Reactエコシステム前提はDocusaurus。
主要機能
- Markdown/MDX: 標準対応・コンポーネント埋込
- Pagefind: 検索組み込み（追加設定不要）
- i18n: 多言語対応標準サポート
- Auto Sidebar: ファイル構造から自動生成
- Dark/Light Mode: 標準対応
- Aside/Tabs/Cards: Markdownを拡張するUIコンポーネント
- Versioning: バージョン別ドキュメント（プラグイン経由）
実装パターン
(1) セットアップ: npm create astro@latest -- --template starlight
(2) 記事追加: src/content/docs/にMarkdownを置くだけ
(3) サイドバー: astro.config.mjsのsidebar設定
(4) 多言語化: src/content/docs/ja/にローカライズ版を配置
(5) デプロイ: Vercel/Cloudflare/Netlify等にstatic export
料金感
- OSS: 完全無料
- ホスティング: Vercel/Cloudflare/Netlify無料枠で十分
- 独自ドメイン: 年数千円
- Mintlifyとの比較: 月$150〜の差額が大きい
本番採用の判断基準
- 本番実績: Cloudflare・Vercel・Astro自社
- カスタマイズ: Astroコンポーネントで自由
- SEO: 静的サイトで最強
- ベンダーロックイン: なし（オープンスタンダード）
- 移行コスト: Docusaurus等からの移行はMarkdown互換で容易
実装で詰まる3つの落とし穴
- サイドバーの設計: 大量ドキュメントでの階層化
- 検索Index: 多言語時のPagefind設定
- バージョニング: Versioning Pluginの運用
30日プラン
- 1週目: Starlight初期セットアップ・10ページ作成
- 2週目: サイドバー・Aside等のコンポーネント活用
- 3週目: i18n・検索カスタマイズ
- 4週目: 本番デプロイ・SEO最適化
関連リンク
Astro基礎は Astro Content Collections、Server Islandsは Astro Server Islands深掘り、Astro DBは Astro DB深掘り を参照してください。