Libx サンプルドキュメント

ドキュメントバージョニング概要

サンプルドキュメントプロジェクトへようこそ！このページでは、libx モノレポで実際に採用しているドキュメントのバージョニング構造と、v1/v2 のように異なるバージョンを併存させるワークフローを俯瞰します。

libx でのバージョニング

libx では、各アプリケーションごとに apps/<project-name>/src/content/docs/<version>/<lang>/ という物理構造を持たせ、project.config.json に記述したバージョン情報を元に UI を組み立てます。sample-docs プロジェクトの構造は次のとおりです。

apps/sample-docs/
├── src/
│   ├── config/project.config.json   # バージョン・言語定義を集約
│   └── content/docs/
│       ├── v1/
│       │   └── ja/01-guide/...
│       └── v2/
│           ├── ja/
│           └── en/
└── public/sidebar/                  # 自動生成されたサイドバーJSON

project.config.json の versioning.versions で ID、表示名、リリース日、最新フラグを管理することで、ヘッダーのバージョンセレクターや URL の自動切替が機能します。新バージョンを追加するときは node scripts/create-version.js sample-docs v3 を実行すると、すべての言語/カテゴリが一括で生成されます。

v1 と v2 を分ける理由

  • 移行計画の可視化: v1 を残したまま v2 を育てられるため、利用者に段階的な移行ガイドを提供可能。
  • URL の安定性: /docs/sample-docs/ja/v1/... と /docs/sample-docs/ja/v2/... で明確に区別でき、検索エンジンに対しても別のページとして扱ってもらえる。
  • 翻訳負荷の制御: バージョンごとに翻訳の進捗を管理できるため、scripts/add-language.js のロールバック機構や .backups/ の履歴と連携しやすい。

バージョン1（このページ）

  • 目的: バージョニングの考え方を手短に把握
  • 内容: ディレクトリ構造、設定ファイル、コマンドの基礎
  • 想定読者: libx のレイアウトを初めて確認する人

バージョン2（メインドキュメント）

  • 目的: ドキュメント作成・編集・自動化までを体系立てて解説
  • 内容: ガイド、コンポーネント、上級トピック、リファレンス
  • 想定読者: 実際に sample-docs を編集する人

多言語とサイドバー

sample-docs はロケール優先（/docs/sample-docs/<lang>/<version>/...）の URL パターンを採用しています。@docs/content-utils の getSidebarAsync に pathPattern: 'locale-first' を渡すことで、言語ごと・バージョンごとのサイドバー JSON（apps/sample-docs/public/sidebar/sidebar-ja-v2.json など）が自動生成されます。

バージョニングの運用ポイント

  1. 構造を変えずに並行更新: v1 のカテゴリ構造をそのまま v2 にコピーし、v2 で新規セクションを育てる。
  2. 設定ファイルは JSON: project.config.json を直接編集するよりも scripts/create-version.js や scripts/add-language.js を使い、バックアップ付きで安全に更新する。
  3. サイドバーの再生成: バージョンを増やしたりカテゴリを追加したら pnpm build:sidebar で JSON を再生成し、pnpm dev --filter=sample-docs で挙動を確認する。

次のステップ

最新の v2 ガイドでは、実際にドキュメントを書き進めるための具体的な手順を扱っています。

次のページへ進み、実際のプロジェクトでの手順を確認しましょう。