Markdownの相対画像パスとドキュメント間リンクのPDF解決テクニック

リポジトリ内のMarkdownドキュメントは、相対パスに強く依存しています。アーキテクチャ図は ./assets/diagram.png に配置され、画面キャプチャは ../images/screen.jpg にあり、別ファイルへのリンクは ./getting-started.md を指しています。コンバーターが階層構造を把握していない場合、画像は欠落しリンクは機能しません。md2pdf はこれらの相対パスを正確に解決し、PDF内に美しく統合します。

本記事では、md2pdfが相対パスを計算する仕組み、ブラウザ側での画像アセット取得、そして文書間リンクをPDF内部ジャンプアンカーに変換する手法を解説します。

静的Markdownにおける相対パスの課題

Markdownファイルは、ローカルディレクトリやGitHubのWebインターフェース上での表示を前提に設計されています:

• 画像のリンク切れ: ![構成図](images/arch.png) のような記述は、親ディレクトリの文脈がないと読み込みに失敗します。
• 無効なファイルリンク: 隣接する文書へのリンク（[設定方法](setup.md)）は、単純な変換ではデッドリンクになります。
• 親ディレクトリへの遡り: ../ を含むパスは、ツリー構造を正しく計算して目的のアセットを特定する必要があります。

Relative Path Resolution Matrix:
Base Document:  docs/guides/installation.md
Image Path:     ../assets/diagram.png
Resolved Asset: docs/assets/diagram.png (Fetched & Inlined)

Link Path:      ./configuration.md
Resolved Link:  Internal PDF Anchor -> Chapter: Configuration

GitHubリポジトリからの画像アセット解決

GitHubからドキュメントを取得する際、md2pdfは各Markdownファイルのディレクトリ階層を正確に追跡します:

1. パスの正規化: ../../images/flow.png のような相対パスを、現在処理中のファイルの位置を基準に正規化します。
2. 生アセットの取得: GitHubのコンテンツ配信URLをブラウザ内で直接構築して画像データをリクエストします。
3. インメモリ埋め込み: 取得した画像はブラウザメモリ上でバイナリバッファに変換され、pdf-lib を通じてPDF内部に埋め込まれます。
4. フォーマット対応: PNG、JPEG、WebP、SVGなど主要な形式に対応し、アスペクト比を保ったまま最適に配置します。

ファイル間リンクのPDF内部ジャンプアンカーへの変換

技術ドキュメント集では、章と章の間の相互参照が頻繁に行われます:

• ローカルリンクの検出: md2pdfは .md ファイルを指すリンクを検出し、結合対象のドキュメントリストと照合します。
• 内部アンカーの生成: リンク先ファイルが同一PDF書籍に含まれている場合、外部リンクではなくPDF内部の該当章へのジャンプリンクに書き換えます。
• Webフォールバック: リンク先が今回のPDF化に含まれていない場合は、GitHub上の公開リポジトリページへの外部リンクとして安全に維持します。

関連画像を含むローカルファイルのアップロード処理

ローカル環境のMarkdownファイルを変換する場合でも、md2pdfは画像アセットの一括処理に対応しています:

ファイル選択時にMarkdownファイルと画像ファイルを同時に指定することで、md2pdfはメモリ上で相対パスとファイル名を関連付けます。外部サーバーに画像をアップロードすることなく、ローカルの図表をそのままPDFに出力できます。

画像とリンクの整合性が保たれたPDFの生成

相対画像と相互リンクを正しく解決することで、レイアウト崩れやリンク切れのない完全なドキュメントが完成します。md2pdfで出力すれば、図表は鮮明に印刷され、章間の移動もスムーズに行える高品質なPDF本が仕上がります。