ドキュメント履歴

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

概要

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

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

• ドキュメントが時間の経過とともにどのように変化したかを確認する

• リビジョン間で何が変更されたかを理解する

• ドキュメント全体のコンテンツ変更を監査する

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

zfb.config.tsでdocHistoryをtrueに設定します：

export default defineConfig(
  zudoDoc({
    // ...
    docHistory: true,
  }),
);

新しい scaffold は docHistory を選択したとき、実際の History アイランドを生成されるすべてのルート形状へ静的に配線します。ボタン用の bindings モジュールやルート編集は不要です。古い既存 scaffold では、各ドキュメントスタブを現在の生成形状へ更新します。DocHistory を静的にインポートし、chromeBindings の後から重ねることで、ほかのホストスロットを落とさずアイランドをスキャナーから到達可能に保ちます。

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

ページごとの表示制御

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

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

2. 詳細ページはデフォルトで表示 — カテゴリインデックスでない具体的なリーフページはすべてボタンを表示します。

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

---
title: My Page
doc_history: false # always hide the button on this page
---

---
title: My Category Index
doc_history: true # opt back in even though this is an index page
---

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

インデックスページにそれなりの分量の本文があり、変更履歴を残す価値がある場合は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履歴の抽出はスタンドアロンパッケージ@takazudo/zudo-doc-history-server（packages/doc-history-server/に配置）が処理します。このパッケージは開発用と本番ビルド用の2つのモードで動作します。

ビルドモード

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

• build-siteジョブ：フルクローン（fetch-depth: 0）、pnpm buildでzfbサイトをビルド（SKIP_DOC_HISTORYなし — preBuildがSSGメタブロック生成のためにフルgit履歴が必要）

• build-historyジョブ：フルクローン（fetch-depth: 0）、@takazudo/zudo-doc-history-server generateを実行

• deployジョブ：両方のアーティファクトをマージしてデプロイ

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

GEN_DOC_HISTORY=1 pnpm build

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

dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json      # locale-prefixed
  ja/guides/writing-docs.json

開発モード

開発モードでは、doc-history-serverがポート4322でスタンドアロンREST APIサーバーとして実行され、zfb開発サーバーと同時に起動されます。これは既存プロジェクトでdocHistory: trueを設定するだけで自動的に得られるものではありません — docHistoryを選択した新規create-zudo-doc scaffoldは、devスクリプトとしてrun-p dev:zfb dev:history（zfb devとインストール済みのdoc-history-serverバイナリを同時に実行）を生成します。これは、単純なzfb devだけではポート4322のサーバーが起動しないためです。doc-historyのzfbプラグインのdevMiddlewareフックがブラウザからの/doc-history/*リクエストをこのサーバーにプロキシします。

run-pは末尾の引数を飲み込んでしまうため、これらのscaffoldではpnpm dev -- --host 0.0.0.0を渡しても静かに無視されます。LANアクセスが必要な場合は代わりに専用のpnpm dev:networkスクリプトを使ってください。zfbだけが0.0.0.0にバインドされ、doc-history-serverはループバック限定のまま（同じ/doc-history/*プロキシ経由でアクセスされます）。それ以外のzfbフラグを渡したい場合は、pnpm dev経由ではなく<pm> run dev:zfb -- <flags>でzfbプロセスへ直接転送してください。

履歴パネルを開くと、その場で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;          // Document route path
  filePath: string;      // File path in the repository
  entries: Array<{
    hash: string;        // Full commit hash
    date: string;        // ISO 8601 date
    author: string;      // Commit author name
    message: string;     // Commit message (first line)
    content: string;     // Full file content at this revision
  }>;
}

Diffアルゴリズム

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

リネーム追跡

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

doc-history-serverパッケージ

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

• 並列CIビルド -- 履歴生成とサイトビルドが独立したジョブとして実行可能

• 独立した開発 -- サーバーを独立して開発、テスト、バージョニング可能

• 柔軟な使用方法 -- 同一パッケージが開発サーバーとCIジェネレーターの両方を提供

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