ADR-007: VitePress採用（ドキュメントツール）
ステータス
採用済み
意思決定者
- 太田裕貴（CTO）
決定日
2024年頃
背景（Context）
Qudenの開発チームは、技術ドキュメント、API仕様、開発ガイド等を管理する必要があります。従来はNotionを使用していましたが、以下の課題がありました。
現状の課題
- Notionはコラボレーションツールとしては優秀だが、技術ドキュメントとしては制約がある
- コードブロックのシンタックスハイライトが限定的
- Markdownファイルとして管理できないため、Gitでのバージョン管理ができない
- ローカル検索が不十分
- 開発者向けのドキュメントツールとしての機能（目次自動生成、リンク検証等）が不足
解決したいこと
- Markdownでドキュメントを管理し、Gitでバージョン管理
- 強力なシンタックスハイライト
- ローカル検索機能
- 高速で軽量な静的サイト生成
- 開発者フレンドリーなドキュメント作成環境
要件（Requirements）
機能要件
- Markdownでドキュメントを記述
- コードブロックの強力なシンタックスハイライト
- ローカル検索機能
- 目次自動生成
- レスポンシブデザイン
- ダークモード対応
非機能要件
- パフォーマンス: 高速なページ読み込み
- 開発効率: ホットリロード、プレビュー機能
- 保守性: シンプルな設定ファイル
- カスタマイズ性: テーマのカスタマイズが容易
制約条件
- 技術的制約: Viteベースで高速ビルド
- ビジネス的制約: 無料のオープンソースツール
- 時間的制約: 既存NotionドキュメントからのMarkdown移行が容易
検討した選択肢
選択肢1: Notion（現状維持）
概要
Notionをそのままドキュメント管理ツールとして使用。
メリット
- 学習コストゼロ（既に使用中）
- リッチなコラボレーション機能
- データベース機能が強力
デメリット
- Gitでのバージョン管理ができない
- コードブロックのシンタックスハイライトが限定的
- Markdown出力が不完全
- ローカル検索が不十分
- 技術ドキュメントとしての機能が不足
実装コスト
- 初期実装: ゼロ
- 学習コスト: ゼロ
- 保守コスト: 中（外部ツールで管理）
選択肢2: Docusaurus（Meta製）
概要
Reactベースの静的サイトジェネレーター。Meta（Facebook）が開発。
メリット
- Reactベースでカスタマイズ性が高い
- 多言語対応が強力
- バージョニング機能
- プラグインエコシステムが充実
デメリット
- ビルドが遅い（Reactベース）
- 設定ファイルが複雑
- カスタマイズに React の知識が必要
- オーバースペック（Quden の用途には不要な機能が多い）
実装コスト
- 初期実装: 中
- 学習コスト: 中〜高
- 保守コスト: 中
選択肢3: VitePress（Vue公式）
概要
Viteベースの静的サイトジェネレーター。Vue.js 公式ドキュメントで使用されている。
メリット
- Viteベースで高速: ビルド・HMRが非常に高速
- シンプルな設定: 最小限の設定でドキュメントサイトを構築
- Markdown拡張: Vue コンポーネントをMarkdown内で使用可能
- 強力なシンタックスハイライト: Shikiによる美しいコードハイライト
- ローカル検索: 標準でローカル検索機能を提供
- 軽量: 静的サイト生成で、ランタイムが軽量
- ダークモード: 標準対応
- レスポンシブ: モバイルフレンドリー
デメリット
- Vueエコシステムに依存
- プラグインエコシステムがDocusaurusより小さい
- バージョニング機能がない（将来的に追加予定）
実装コスト
- 初期実装: 低
- 学習コスト: 低
- 保守コスト: 低（シンプルな設定）
決定（Decision）
選択した技術: VitePress
選択理由
要件との適合性
- Markdownでドキュメントを記述でき、Gitでバージョン管理可能
- Shikiによる強力なシンタックスハイライト
- ローカル検索機能が標準で提供
- 目次自動生成、レスポンシブデザイン、ダークモードすべて標準対応
技術的妥当性
- Viteベースの高速ビルド: 開発時のHMRが非常に高速で、開発効率が向上
- シンプルな設定: 最小限の設定でドキュメントサイトを構築可能
- Markdown拡張: Vueコンポーネントを埋め込み可能で、カスタマイズ性が高い
- 軽量: 静的サイト生成で、パフォーマンスが優れている
コスト対効果
- 学習コストが低く、短期間でドキュメントサイトを構築可能
- オープンソースで無料
- 保守コストが低い（シンプルな設定）
将来性
- Vue.js公式ドキュメントで使用されており、継続的な開発が期待できる
- Viteエコシステムの成長により、さらなる機能追加が期待できる
実装方針
Markdownファイルの管理
data/dev_docs/ディレクトリで Markdown ファイルを管理- Gitでバージョン管理
サイドバー・ナビゲーション
.vitepress/config.mtsで設定- ドキュメントのカテゴリごとにサイドバーを構成
ローカル検索
search.provider: 'local'で設定- 日本語検索もサポート
テーマのカスタマイズ
- デフォルトテーマをベースに、必要に応じてカスタマイズ
Notion → Markdown 移行
- Notion API を使って、既存ドキュメントをMarkdownに変換
- 定期的に同期スクリプトを実行
受け入れたトレードオフ
トレードオフ1: Vueエコシステムへの依存
- 影響: Vueエコシステムに依存する
- 受け入れ理由: チームがTypeScript/JavaScriptに慣れており、Vueの学習コストは低い
- 軽減策: カスタマイズが必要な場合のみVueコンポーネントを作成
トレードオフ2: バージョニング機能の不在
- 影響: ドキュメントのバージョニング機能がない
- 受け入れ理由: Qudenのドキュメントは最新版のみを管理すれば十分
- 軽減策: 必要に応じて、Gitのタグ・ブランチでバージョン管理
トレードオフ3: プラグインエコシステムの小ささ
- 影響: Docusaurusと比べて、プラグインが少ない
- 受け入れ理由: Qudenの用途では、標準機能で十分
- 軽減策: 必要に応じて、Vueコンポーネントでカスタム機能を実装
結果（振り返り）
うまくいったこと（Pros）
- 高速なビルド: Viteベースで、ビルド・HMRが非常に高速
- シンプルな設定: 最小限の設定でドキュメントサイトを構築できた
- 美しいコードハイライト: Shikiによるコードハイライトが非常に美しい
- ローカル検索: 標準のローカル検索が強力で、日本語検索も問題なく動作
- Markdownベース: Gitでバージョン管理でき、開発者フレンドリー
うまくいかなかったこと（Cons）
- Notion移行の手間: Notion APIを使った移行スクリプトの作成に時間がかかった
- カスタマイズの学習: Vueコンポーネントのカスタマイズに若干の学習コストがあった
学び
- Markdownの威力: Markdownベースでドキュメントを管理することで、開発者の生産性が向上
- ローカル検索の重要性: ローカル検索機能により、ドキュメントの検索性が大幅に向上
- Viteの高速性: Viteの高速なHMRにより、ドキュメント作成の効率が大幅に向上
今後の改善点
- Notion同期の自動化: Notion APIを使った定期的な同期スクリプトの自動化
- カスタムコンポーネントの追加: 必要に応じて、カスタムVueコンポーネントを追加
- OGP画像の自動生成: ドキュメントページのOGP画像を自動生成する仕組みの導入