画像ファイルがフォルダ内に存在していても、原稿が古い場所を参照していればEPUBでは画像切れになります。調べる起点は画像名そのものではなく、「どの原稿が、どの相対パスを書いているか」です。移動前の利用箇所を数え、移動計画を下見し、書き換え後の原稿をディスクから読み直すと、出力後まで事故を持ち越しません。
STUDIO-163の実測標本では assets/figure.png を moved/renamed-figure.png へ移し、参照元 draft/chapter.md の画像リンクを更新しました。操作、入力、保存先、再読込、合格値を一本ずつ対応させます。
参照の起点を原稿側に置く
移動前の原稿には !検証図 が1件ありました。画像フォルダだけを見て同名ファイルの有無を調べても、この文字列がどこに残っているかは分かりません。最初にワークスペースの draft/chapter.md を特定し、画像参照と通常リンクを区別します。
今回の原稿には画像とは別に 資料 もあります。拡張子だけで全リンクを一括置換すると、資料リンクまで巻き込むおそれがあります。対象は assets/figure.png への画像参照1件、移動先は moved/renamed-figure.png と作業票に書き、他の参照は変更対象から外します。
移動票には旧位置と新位置を両方残す
Rune Studioの rune file move で画像を移す前に、旧絶対パスと新絶対パスを記録します。実行結果では fromPath が旧 assets/figure.png、path が新 moved/renamed-figure.png でした。ファイル移動が成功しても原稿は自動的に正しいとは限らないため、この時点では合格にしません。
移動後に旧位置だけを消してしまうと、書き換えに失敗したときの復旧が難しくなります。制作物ではバックアップまたは版管理を用意し、新画像が読めることを確かめるまで旧版を保持します。今回の合成標本は専用ワークスペース内で行い、公開中のEPUBやWordPressには触れていません。
rune refs usage で旧画像を使う原稿を数える
移動前に実行した rune refs usage --workspace <workspace> --path <old-image> は、対象ファイル数1、参照箇所数1を返しました。参照元は draft/chapter.md です。この値は「画像が1枚ある」ではなく「旧画像を使っている原稿が1ファイル、記述が1箇所ある」という意味です。
結果が0なら、指定した旧パスが違う、参照表記が別形式、またはワークスペース外の原稿である可能性があります。推測で置換せず、原稿を開いて実際の文字列を確認します。予想より多い場合は、各参照を更新してよいかを分け、表紙やサンプル原稿を不用意に巻き込まないようにします。
refs plan の下見から refs rewrite へ進む
次に rune refs plan --workspace <workspace> --from <old-image> --to <new-image> で変更候補を下見します。STUDIO-163では draft/chapter.md の1箇所が計画に入りました。パスの起点は参照元原稿の場所なので、原稿に保存される新表記は ../moved/renamed-figure.png です。
候補が対象1件だけであることを確認してから rune refs rewrite を実行しました。書き換え結果も1件でした。下見と実行の件数が違うときは、その間に原稿が変わった可能性があります。結果を受け入れず、最新版を読み直して再計画します。
保存後の chapter.md を再読込する
書き換え後、rune file read --path <workspace>/draft/chapter.md でディスク上の原稿を読み直しました。返った内容は !検証図 で、資料リンク ../assets/note.txt はそのままでした。さらに旧参照を数えると0、新参照は1でした。
合格条件は、移動先画像が存在する、旧参照0、新参照1、再読込した原稿に新しい相対パスがある、対象外リンクが変わっていない、の四つです。エディタ画面の表示だけでは保存の成否を決めず、必ずファイルの再読込値を使います。
同名画像を置くだけでは根本解決にならない
旧フォルダへ同名画像をコピーすれば、一時的に画像切れが見えなくなる場合があります。しかし原稿がどの画像を正としているか不明になり、後日の整理で再発します。とくに figure.png のような一般名は、別章の画像を誤って表示しても気づきにくい名前です。
応急処置が必要なら、旧位置へ戻した理由と期限を記録し、正式な参照更新を別作業にします。画像の見た目が似ていることではなく、原稿の新パスが意図したファイルへ解決されることを受け入れ条件にします。
CLIを使えない場合は一件ずつ手で追う
公開されている製品資料の範囲では、参照調査と書き換えはRune Studioの機能として案内されています。CLIを使わない場合も、原稿内検索で旧相対パスを探し、画像を移動し、各記述を新しい相対パスへ変更し、保存後に閉じて開き直すという順序は同じです。
手作業では件数の取り違えが起きやすいため、移動前件数、更新件数、残存件数を紙やチケットへ残します。画面上の警告色や自動検知は今回の実測対象ではないので、見えたとは書きません。
出力許可は新参照が解決してから出す
この標本の完了値は、参照元1ファイル、旧参照0、新参照1です。原稿の再読込内容、新画像の保存先、対象外リンクの保持も確認できました。この時点で初めてテストEPUBへ進めます。EPUB検査が通っても、別の原稿に旧参照が残っていれば制作側の検査は不合格です。
epub 画像 の切れを防ぐ作業では、移動の成功と参照の成功を分けてください。旧画像を使う原稿を数え、計画を下見し、対象だけを書き換え、保存した原稿を再読込する。この短い連鎖が一つでも欠けたら、その地点へ戻ります。