ドキュメント履歴

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

概要

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

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

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

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

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

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

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

履歴ビューアの使用方法

有効にすると、各ドキュメントページの右下にフローティングHistoryボタンが表示されます。

リビジョンの閲覧

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

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

リビジョンの比較

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

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

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

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

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

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

仕組み

ビルドモード

pnpm buildの実行中、Astroインテグレーションがすべてのコンテンツファイルのgit履歴を抽出し、JSONファイルとしてdist/doc-history/に書き出します。各JSONファイルには、各コミット時のファイル内容を含む単一ドキュメントの完全なリビジョンリストが格納されます。

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

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

開発モード

開発モード（pnpm dev）では、Viteミドルウェアが履歴リクエストを動的に処理します。履歴パネルを開くと、その場でgitコマンドが実行されます — 事前生成は不要です。これにより、履歴は最新のコミットと常に同期されます。

本番出力サイズ

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

リネーム追跡

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