自动解析 Markdown 相对路径图片与跨文档超链接转 PDF

代码仓库中的技术文档高度依赖相对路径。架构拓扑图通常存放于 ./assets/diagram.png，界面截屏保存在 ../images/screen.jpg，章节互链则指向 ./getting-started.md。如果转换工具脱离了目录上下文，图片就会加载失败，超链接也会全部失效。通过 md2pdf，相对路径能够被精准解析并无缝内嵌到生成的 PDF 中。

本文将深入介绍 md2pdf 如何解析相对路径、在浏览器端调取图像资源，以及如何将跨文档链接重写为 PDF 内部无缝跳转锚点。

静态 Markdown 中相对路径的技术痛点

Markdown 文件原本是为本地目录树或 GitHub 网页界面设计的：

• 图片碎图占位：脱离了上级目录，像 ![架构图](images/arch.png) 这样的相对路径将无法定位资源。
• 失效的跨文件链接：指向同级文档的 [快速上手](setup.md) 链接在转为静态单体 PDF 后往往变成死链。
• 上溯多级父目录：包含 ../ 的复杂相对路径需要根据当前文档位置进行严密的路径矩阵推导。

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 会全程追踪记录每篇文档的真实目录层级：

1. 路径规范化推导：以当前文档所在路径为基准，精确推导出 ../../images/flow.png 对应的完整相对地址。
2. 前端直连拉取：md2pdf 动态拼接出 GitHub 内容分发网络（CDN）的原始资源地址并在浏览器内直接获取。
3. 内存转换与内嵌：下载的图片数据在内存中转为二进制 Buffer，并通过 pdf-lib 原生内嵌至 PDF 页面中。
4. 全格式兼容：原生支持 PNG、JPEG、WebP 与矢量 SVG 等主流格式，并按真实宽高比保持页面版式平衡。

将跨文件链接重塑为 PDF 内部跳转锚点

专业的技术文献体系包含极其密集的章节互引：

• 检测本地文件链接：md2pdf 会深度扫描所有指向 .md 文件的超链接，并与待排版目录对比。
• 重写为内部跳转目标：若被引用的文档已被包含在本次电子书合集中，系统会自动将其重写为 PDF 内部目的地的跳转链接。
• 外部兜底链接策略：若目标文档未被选入本次 PDF 编译，则智能回退为该文档在 GitHub 上的在线网页链接。

支持本地 Markdown 与配套图片的组合导入

在处理本地离线文档时，md2pdf 同样支持将 Markdown 与配套图表打包解析：

您可以在文件选择框中同时选取 Markdown 文件与其引用的本地图片。md2pdf 会在浏览器内存中建立文件名映射表，无需将私密图片上传至任何图床，即可直接渲染出包含完整插图的 PDF。

导出图文并茂、链接灵动的 PDF 手册

精准解析图片与路径消除了排版中的断点与死链。借助 md2pdf，您的图表将在 PDF 中呈现印刷级的高清画质，所有章节互链均可顺畅点击跳转，打造顶级的数字化阅读体验。