ドキュメント履歴

各ドキュメントページのgitリビジョン履歴と行単位のdiffを表示します。

概要

zudo-docは各ドキュメントページのgitリビジョン履歴を表示できます。有効にすると、各詳細ページにHistoryボタンが表示され、過去のリビジョンを閲覧したり、行単位のdiffビューアで任意の2つのバージョンを比較できるサイドパネルが開きます。

これは以下の用途に便利です：

• ドキュメントが時間の経過とともにどのように変化したかを確認する
• リビジョン間で何が変更されたかを理解する
• ドキュメント全体のコンテンツ変更を監査する

ドキュメント履歴の有効化

src/config/settings.tsでdocHistoryをtrueに設定します：

export const settings = {
  // ...
  docHistory: true,
};

この機能はビルドを高速に保つため、デフォルトでは無効です。

ページごとの表示制御

docHistoryがグローバルに有効化されたあと、各ページは以下の2つのルールでHistoryボタンを表示するかどうかを決定します。

1. カテゴリインデックスページの自動抑制 — エントリIDが/indexで終わるページ（例：guides/index.mdx）は、デフォルトでボタンを非表示にします。これらのページは通常ナビゲーションのハブやランディングページであり、リビジョン履歴を表示する意味が薄いためです。
2. 詳細ページはデフォルトで表示 — カテゴリインデックスでない具体的なリーフページはすべてボタンを表示します。

doc_historyフロントマターフラグでページごとにデフォルトを上書きできます。

---
title: My Page
doc_history: false # このページでは常にボタンを非表示
---

---
title: My Category Index
doc_history: true # インデックスページでも明示的に表示
---

フロントマターの指定はどちらの方向にも優先されます。

インデックスページにそれなりの分量の本文があり、変更履歴を残す価値がある場合はdoc_history: trueを指定してください。逆に、自動生成された詳細ページや、コミット履歴を表に出したくない詳細ページにはdoc_history: falseを指定します。

履歴ビューアの使用方法

有効にすると、各詳細ページの本文とフッターの間にある Body Foot Util エリア の中に History ボタンが表示されます。カテゴリインデックスページではデフォルトで非表示です。詳しくは上記ページごとの表示制御を参照してください。

リビジョンの閲覧

ボタンをクリックするとリビジョンパネルが開きます。右側からスライドインし、現在のドキュメントを変更したすべてのgitコミットが新しい順に表示されます。各エントリには以下が表示されます：

• コミットハッシュ（短縮形）
• コミットの日付
• 著者名
• コミットメッセージ（1行目）

リビジョンの比較

2つのリビジョン間のdiffを表示するには：

1. コミットの横にあるAボタンをクリックしてA（古いリビジョン）を選択
2. 別のコミットの横にあるBボタンをクリックしてB（新しいリビジョン）を選択
3. Compareボタンをクリック

diffビューアはサイドバイサイド比較を表示します — 左側に古いリビジョン、右側に新しいリビジョン：

• 緑色の背景 — 新しいリビジョンで追加された行（右側）
• 赤色の背景 — 古いリビジョンから削除された行（左側）
• 灰色のセル — 一方に対応する行がない空のプレースホルダー
• 変更なしの行 — 両側に表示されるコンテキスト

キーボードショートカット

• Escape — 履歴パネルを閉じる
• 別のページに移動するとパネルは自動的に閉じます

仕組み

git履歴の抽出はスタンドアロンパッケージ@zudo-doc/doc-history-server（packages/doc-history-server/に配置）が処理します。このパッケージは開発用と本番ビルド用の2つのモードで動作します。

ビルドモード

本番環境では、スタンドアロンCLIジェネレーターがすべてのコンテンツファイルをバッチ処理し、JSONの履歴ファイルをdist/doc-history/に書き出します。これはAstroサイトビルドと並行した独立したCIジョブとして実行されます：

• build-siteジョブ：シャロークローン、SKIP_DOC_HISTORY=1でAstroサイトをビルド
• build-historyジョブ：フルクローン、@zudo-doc/doc-history-server generateを実行
• deployジョブ：両方のアーティファクトをマージしてデプロイ

この並列戦略により、履歴生成（フルgitクローンを必要とし、すべてのコミットを走査する）がAstroビルドとは独立して実行されるため、合計CIビルド時間が短縮されます。

出力構造はコンテンツディレクトリをミラーします：

dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json      # ロケールプレフィックス付き
  ja/guides/writing-docs.json

開発モード

開発モード（pnpm dev）では、doc-history-serverがポート4322でスタンドアロンREST APIサーバーとして実行され、run-pを使用してAstro開発サーバーと同時に起動されます。Astroインテグレーションがブラウザからの/doc-history/*リクエストをこのサーバーにプロキシします。

履歴パネルを開くと、その場でgitコマンドが実行されます — 事前生成は不要です。サーバーのファイルインデックスは10秒ごとにリフレッシュされるため、新しいファイルやリネームされたファイルが自動的に検出されます。これにより、履歴は最新のコミットと常に同期されます。

本番出力サイズ

zudo-docはサーバーサイドランタイムなしの完全な静的サイトを生成するため、リクエスト時にgitコマンドを実行するサーバーがありません。代わりに、ビルドステップですべての履歴データを事前抽出し、dist/doc-history/ディレクトリに静的JSONファイルとして出力します。

各JSONファイルにはすべてのリビジョンでの完全なファイル内容（最大50コミット）が含まれます。これにより、合計出力サイズは以下に比例します：

• ドキュメントファイルの数
• ファイルあたりのgitコミット数
• 各リビジョンでの各ファイルのサイズ

小〜中規模のドキュメントサイトでは通常無視できる程度です。深い履歴を持つ大規模サイトでは、doc-history/ディレクトリが大幅に増加する可能性があります。これらのファイルはオンデマンドでのみ取得されるため（ユーザーがHistoryボタンをクリックした時）、初期ページ読み込みには影響しません — ただし、デプロイサイズには追加されます。

ローカライゼーションサポート

ドキュメント履歴は設定されたすべてのロケールで動作します。各ロケールのコンテンツディレクトリは、ロケールコードがプレフィックスされた独自の履歴ファイルセットを生成します：

• 英語ドキュメント：/doc-history/{slug}.json
• 日本語ドキュメント：/doc-history/ja/{slug}.json
• ドイツ語ドキュメント：/doc-history/de/{slug}.json

履歴パネルは現在のページに基づいて適切なロケール固有の履歴を自動的にリクエストします。

技術詳細

データ形式

各ドキュメントの履歴は以下の構造のJSONファイルとして保存されます：

interface DocHistoryData {
  slug: string;          // ドキュメントのルートパス
  filePath: string;      // リポジトリ内のファイルパス
  entries: Array<{
    hash: string;        // 完全なコミットハッシュ
    date: string;        // ISO 8601形式の日付
    author: string;      // コミット著者名
    message: string;     // コミットメッセージ（1行目）
    content: string;     // このリビジョンでの完全なファイル内容
  }>;
}

Diffアルゴリズム

diffビューアは<code>diff</code>ライブラリのdiffLines関数を使用して、2つのリビジョン間の行レベルの差分を計算します。GitHubのスプリットdiffビューに似たサイドバイサイドのテーブルレイアウトで表示されます。隣接する削除ブロックと追加ブロックは同じ行にペアリングされるため、何が変更されたかを一目で確認できます。

リネーム追跡

履歴抽出はgit log --followを使用してファイルのリネームを追跡します。ドキュメントが移動またはリネームされた場合、リネーム前のコミットを含む完全な履歴が保持されます。

doc-history-serverパッケージ

履歴抽出ロジックはAstroビルドパイプライン内ではなく、スタンドアロンパッケージ（packages/doc-history-server/）に配置されています。この設計により以下が可能になります：

• 並列CIビルド — 履歴生成とサイトビルドが独立したジョブとして実行可能
• 独立した開発 — サーバーを独立して開発、テスト、バージョニング可能
• 柔軟な使用方法 — 同一パッケージが開発サーバーとCIジェネレーターの両方を提供

REST APIエンドポイント、CLI引数、データ型、アーキテクチャの詳細については、Doc History Serverリファレンスを参照してください。