ページ上の差分
ページの URL に diff パラメーターを付けると、そのページの上に変更が示される。
追加と変更は緑で、削除した文は、削除した位置に赤の取り消し線で示す。
diff パラメーター
パラメーターは git と同じ記法で書く。
版には次の 3 つを使える。
- コミットハッシュ：4 文字以上。このページを変えたコミットに限る。短縮したハッシュが複数のコミットに一致したときは、候補を並べて示す。
- タグ：リポジトリの任意のタグ（
tagPatternで絞り込める）。ページを変えていない時点も指せる。 HEAD：ページの最新の版。
リリースのタグ
?diff= に書くコミットハッシュは、そのページを変えたコミットに限る。
そのため、あるリリース以降にページで変わったことをすべて示すには、リリースの時点を指す名前が要り、それを与えられるのはタグだけである。
タグがあれば、リリースのコミットでページが変わったかどうかにかかわらず、どのページでも ?diff=v2.0.. が使える。
タグのないリポジトリでは、範囲の指定はほとんど役に立たない。
- リリースごとにタグを付ける：
v2.0のように付ける。 multiVersionを使うサイト：リリースでは、開発中のディレクトリを新しいバージョンのディレクトリにコピーすることが多い（docs/dev/からdocs/2.0/など）。そのコピーをしたコミットにタグを付ける。このコミットでは 2 つのディレクトリの内容が同じなので、同じ範囲で 2 つのことを確かめられる。- 開発中のバージョンのページでは、
?diff=v2.0..がリリース以降の変更、つまり次のリリースでの変更を示す。 - リリースしたバージョンのページでは、
?diff=v2.0..がリリース後に入れた修正を示す。
- 開発中のバージョンのページでは、
- 後から古いコミットに付けたタグ：同じ結果になるとは限らない。タグを付けたコミットで、開発中のディレクトリにすでに次のリリースの変更が入っていた場合、開発中のバージョンのページでは、そのタグはリリースではなくその変更を含む版を指す。また、タグの時点でページが別のパスにあった場合、git がその移動をリネームとして追跡していなければ、そのページではタグを使えない。
tagPatternを設定する：/^v\d/のようにリリースのタグに絞ると、リポジトリのほかのタグを?diff=で使えなくなる。
タグはサイトのビルド時に読み出すので、新しいタグは push した時点ではなく、次のビルドの後にサイトで使えるようになる。
since を設定したときは、since の子孫にあたるタグだけを書き出す（大きなサイトを参照）。
印の付き方
このプラグインは、差分を別に描くのではなく、描画されたページそのものに印を付ける。
- 段落とリストの項目：段落がソースの複数の行にわたるときは、変わった行だけに印を付ける。一文一行で書いた文書なら、文の単位で印が付く。
- 表：変わった行に印を付ける。削除した行は、列ごとのセルに分けて取り消し線で示す。
- コードブロック：コードの行ごとに印を付け、削除した行はそのあいだに差し込む。
- 削除したブロック：削除した段落は、削除した位置に、Markdown のソースのまま赤い枠で示す。
ページには常に最新の版が表示されている。 そのため、古いコミットを指定したときは、そのコミットで加えた行を最新の版までたどって示す。 その後のコミットで書き換えた行は、「その後さらに変更」として黄色で示す。
ページ上に示せない変更もある。
フロントマターと import の行は描画されないので、示せなかった行数を画面下部のバーに表示する。
これらはソースの差分で確かめられる。
画面下部のバー
差分を表示しているあいだ、画面下部のバーに、変更の日時、要約行、作者と、色の凡例を表示する。
- ↑ と ↓：変更箇所を移動する。キーボードの
nかjで次へ、pかkで前へ移る。削除した文とそれを置き換えた文は、1 か所の変更として数える。 - 変更箇所がすべて画面に収まっているときは、変更箇所の数だけを表示する。
- ソースの差分：Markdown のソースの差分をダイアログで開く。統合と左右に並べる形を切り替えられる。
- 閉じる：パラメーターを外して、通常のページに戻る。
制約
- 開発サーバーで、コミットしていない編集があるページを開くと、印の位置がずれることがある。行番号を最新のコミットの内容に合わせているためである。
- 段落の最初の文を削除したときは、文の位置ではなく、段落の前に枠で示す。
- 印の位置合わせは Rspress の既定のテーマを前提にしている。テーマを大きく作り替えたサイトでは、印が付かない変更が出る可能性がある。その場合もソースの差分では確かめられる。