ドキュメントサイトの技術選定

本ページは 2026-10-12 に主要な静的ドキュメントフレームワークを調査した結論と、本リポジトリのドキュメントサイトフレームワークに関する最終決定を記録したものです。

決定記録

日付	決定	理由
2026-10-12（調査日）	Astro Starlight を採用し、VitePress から移行する	Starlight はデフォルトでクライアント JS がゼロでフレームワーク非依存であり、本リポジトリの「ランタイム JS ゼロ」という哲学に最も近い。3 つのデータ駆動リファレンスページを純粋な Astro コンポーネントへ書き換えたことで、vue / vitepress / vite の 3 依存を完全に削除できた。Node ≥22.12 という要件も許容範囲
2026-10-12（調査日、事前判断）	VitePress を維持する	当時は移行のメリットがコストを上回らなかった——ファミリーの 7 サイトがすべて VitePress 上にあり、本リポジトリのドキュメントサイトもすでに完成していたため。この結論は同日の移行決定に取って代わられており、歴史的記録として以下に残す

移行自体は一度で完了しました（単一のコミット内で Astro の骨組みを構築し、全ページを移し終えることで、中間状態がビルド不能になるのを回避）。ファミリーの他のサイトは依然として VitePress を使っており、本リポジトリはファミリーの統一を求めません。将来ファミリー全体でフレームワークを統一する場合、本リポジトリの Starlight の実践がそのまま参照例になります。

調査結論（歴史的記録、2026-10-12 のデータに基づく）

• もし今日ゼロから始め、かつファミリーの一貫性という制約がないなら、最有力の代替は Astro Starlight——性能、フレームワーク非依存、デフォルトのクライアント JS ゼロが、本リポジトリの「ランタイム JS ゼロ」哲学に最も近い。（この判断が最終的に上記の移行決定につながった。）
• VuePress は事実上停滞しており、新規プロジェクトでの採用は勧めない（リポジトリの最後の push は 2024-08-07 で、v2 は今も rc のまま）。
• 移行前に唯一、長期的な観察に値したのは VitePress 2.0（当時 next タグは 2.0.0-alpha.20 で、alpha 段階だった）。

アクティビティデータ

データ収集日：2026-10-12。GitHub のデータは api.github.com から、npm のダウンロード数は 2026-10-04 〜 10-10 の週間統計、バージョン番号は registry.npmjs.org の dist-tags から取得。star 数は時間とともに増えるため、引用時は鮮度に注意してください。

フレームワーク	技術スタック	GitHub Stars	リポジトリの最終 push	npm 週間ダウンロード	最新安定版
VitePress	Vue 3 + Vite	18.4k	2026-10-11	1,305,159	1.6.4（next: 2.0.0-alpha.20）
Docusaurus	React + MDX	66.5k	2026-10-10	1,504,459	3.10.2
Astro Starlight	Astro（フレームワーク非依存）	9.4k	2026-10-09	1,431,284（astro 本体 7.22M）	astro 7.3.8 / starlight 0.42.6
docsify	ランタイム JS レンダリング	31.5k	2026-10-11	80,727	5.0.0
Nextra	Next.js + React	13.9k	2026-07-31	238,757	4.6.1
Fumadocs	Next.js + React	13.3k	2026-10-09	—	—
MkDocs Material	Python	27.6k	2026-10-02	PyPI のため対象外	—
Sphinx	Python / RST	8.1k	2026-10-05	PyPI のため対象外	—
VuePress	Vue + Webpack	22.7k	⚠️ 2024-08-07	71,177	1.9.10（v2 は 2.0.0-rc.31 で停滞）
Dumi	Umi + React	3.8k	2026-09-14	20,163	2.4.50
Rspress	Rspack + React	2.3k	2026-10-10	19,631	1.47.2（2.0 beta.21）

主な読み：VitePress と Docusaurus が月間ダウンロード 100 万を超える唯一の二強。Starlight は Astro 本体（722 万）を追い風に台頭した第三極。VuePress は 2.3 万 star を持つものの、リポジトリは 2 年以上コミットがなく、VitePress に事実上取って代わられた。

グループ別の長所と短所

第 1 グループ：VitePress / Docusaurus / Astro Starlight

VitePress（本リポジトリの移行前まで使用。ファミリーの他のサイトは今も使用中）

• 長所：Vue 単一ファイルコンポーネントをそのまま markdown に書ける（本リポジトリのトークンリファレンス / コンポーネント契約 / ゴールデンケースという 3 つのリファレンスページはまさにこれに支えられていた）。ビルド期データローダー（*.data.ts）は JSON 真源の読み込みに自然に合い、dev 時は watch glob でホットリロードもできる。Vite dev は極めて高速。デフォルトテーマはすぐ使えて設定はほぼ不要。中国語コミュニティと資料も豊富。
• 短所：MDX サポートが弱い（MDX エコシステムではない）。バージョン管理されたドキュメントや i18n などのエンタープライズ向け機能は、自前で用意するかプラグインを探す必要がある。テーマのカスタマイズ深度は Docusaurus に劣る。検索はローカルインデックスのため、大規模サイトでは効果が限定的。

Docusaurus（Meta 製、エコシステム最大）

• 長所：バージョン管理ドキュメントのプラグイン（複数バージョンのドキュメント共存）と i18n は全フレームワーク中で最も成熟している。MDX エコシステム、プラグイン体系、テーマ注入（swizzle）も充実。Meta の後ろ盾があり、長期保守に安心感がある。
• 短所：React 一式の依存が重く、ビルド成果物の JS サイズが大きい。設定項目が多く、認知負荷が高い。データパイプライン（loadContent ライフサイクル）で JSON 真源に接続するのは VitePress の loader よりも回りくどい。ファミリーでの前例がない。

Astro Starlight（フレームワーク非依存、性能の基準。本リポジトリで採用中）

• 長所：デフォルトでクライアント JS ゼロで、本リポジトリの「ランタイム JS ゼロ」哲学に最も合致する。コンテンツコレクション（Content Collections）による型安全なデータ層。Vue / React / Svelte のコンポーネントを混在させられる。ビルド成果物が最も軽量。Starlight テーマのドキュメント体験は極めて良好（サイドバー、アンカーナビゲーション、i18n 内蔵）。
• 短所：Starlight は依然 0.x（0.42.6）で、API に破壊的変更があり得る。コンテンツコレクションはファイル型コンテンツ（md / mdx）向けで、tokens/*.json のような外部 JSON を読むにはコレクションを迂回し、.astro ページで直接 import する必要がある（本リポジトリは frontmatter から codegen モジュールを直接呼び出して解決済み）。ファミリーに前例がなく、デプロイ / nginx / サイドバーの規約を一から確認する必要があった（本リポジトリで確認済み。詳しくは デプロイ手順 を参照）。

第 2 グループ：Nextra / Rspress / Fumadocs / Dumi

• Nextra：Next.js エコシステム、MDX が強力、ドキュメントも美しい。ただし Next.js + React に強く縛られ、デプロイモデル（SSG / SSR / Edge）がファミリーの nginx 静的ホスティングとは異なる。v4 のコンテンツディレクトリ規約は VitePress と大きく異なる。移行の動機がない。
• Rspress（ByteDance の web-infra-dev 製）：ビルド速度が最速（Rspack）で、数千ページの大規模ドキュメントサイトでは VitePress より明らかに優位。中国語メンテナーのコミュニティも親切。ただしエコシステム / プラグインが最も少なく（週間ダウンロード 2 万）、データローダーに標準的なパターンもない。本リポジトリは 30 数ページしかなく、速度のために支払う学習コストが見合わない。
• Fumadocs：ここ 2 年で最も勢いのある新星（13.3k star、オープンな issue は 2 件のみ）。Next.js + モダンなデザインシステムで、検索 / ビュー切り替えの体験が良い。これも Next.js に強く縛られ、中国語圏の資料も少ない。ブックマークには値するが、今導入するのは勧めない。
• Dumi：コンポーネントライブラリのデモ（live demo、プロパティ表の自動生成）のために生まれた。本リポジトリはビルド期のトークンリポジトリで、デモできるランタイム UI が一切なく、中心的な売りがまったく使えないうえ、Umi / React に強く縛られる。明確に対象外。

第 3 グループと特殊項目

• MkDocs Material / Sphinx（Python 系）：ドキュメント品質は極めて高いが、Python ツールチェーンを要求し、本リポジトリの Node ≥20 + pnpm + TS ツールチェーンとはエコシステムが異なるため、codegen の TS 型や読み込み関数を再利用できない。対象外。
• docsify（ランタイムレンダリング）：ビルド期がなく CDN から読み込むだけですぐ使え、「単一ページを素早く公開する」小規模ドキュメントに向く。しかしビルド期に HTML を生成せず（SEO が弱く、初回表示が遅い）、ビルド期データローダーで schema 検証もできない（本リポジトリのリファレンスページはまさにこの能力に依存している）。対象外。

本リポジトリの制約との逐一対照

本リポジトリの制約 / 要件	VitePress	Docusaurus	Starlight	その他
ファミリー 7 サイトで同一体系（nginx プレフィックス / サイドバー / デプロイ）	✅ ファミリーの他サイトで使用中	❌ 一から確認が必要	✅ 本リポジトリで確認済み（nginx の 3 つの契約は引き続き適用。詳しくは デプロイ手順）	❌
ビルド期に JSON 真源を読んでリファレンスページをレンダリング	✅ ネイティブ loader で実装済み	⚠️ カスタムプラグインが必要	✅ 実装済み（.astro ページの frontmatter から codegen の load / resolve を直接呼び出し）	⚠️ さらに手間がかかる
中国語のみ、i18n 不要	✅	強みが使えない	✅	—
インタラクティブなデモのない散文 + 表 + コード	✅	✅	✅	✅
「ランタイム JS ゼロ」の性格	⚠️ ランタイム JS あり（サイト限定で、レッドラインの範囲外）	❌ JS が重い	✅ デフォルトで JS ゼロ	—
codegen の TS モジュール（型 / 検証）を再利用	✅ 検証済み（vite ^5.4.21 以降は SSR で import.meta.dirname をサポート）	✅	✅ 検証済み（astro 7 内蔵の vite 8 は SSR で import.meta.dirname をサポート）	✅

補足の判断根拠 2 点：

• 「ランタイム JS ゼロ」のレッドラインが対象とするのは codegen の dist/ 生成物であり、ドキュメントサイトではありません。ドキュメントサイト自体がフレームワークのランタイムで動いてもレッドラインには違反しません——dist/ とは完全に隔離されており、ビルド成果物は .gitignore に入ります。ただし Starlight へ移行した後は、サイト自体もデフォルトでクライアント JS ゼロになり（検索 / テーマ切り替えなど少数のインタラクションのみ必要時に読み込み）、レッドラインの精神とより一致するようになりました。
• Docusaurus のバージョン管理ドキュメントと i18n の強みは本リポジトリでは使えません：本リポジトリは中国語のみ、単一バージョンで、内容は codegen に追随するため、「旧版トークンドキュメントの共存」という状況が存在しません。

今後の観察項目

1. Starlight 1.0：本リポジトリは現在 ^0.42.6 に固定しています。0.x 段階では破壊的変更がまだあり得るため、1.0 正式版のリリース後にアップグレードパスを評価します（Starlight の移行ガイドに変更点が列挙されます）。
2. VitePress 2.0：beta に入ったら評価します。ファミリーの他のサイトは依然 VitePress 上にあり、主な注目点はビルド性能と Vite 7 への追随です。
3. 再選定を引き起こすシグナル：Starlight が長期間メンテナンスされない、またはファミリー全体でドキュメントフレームワークを統一する決定がなされた場合（その際は本リポジトリの Starlight の実践がそのまま参照例になります）。