使用Pandoc将Jekyll生成的HTML转PDF时图片加载失败求助

API 探路者

2026-8-4

解决Pandoc转换Jekyll生成的HTML到PDF时图片缺失的问题

问题根源

Jekyll生成的图片路径是绝对路径（以/开头），Pandoc会将其解析为文件系统的根目录路径（比如file:///assets/images/view.png对应系统根目录下的assets文件夹），而非你的项目目录，这就是图片加载失败的原因。--resource-path参数仅对相对路径的资源生效，所以直接用它无法解决绝对路径的问题。

可行解决方法

方法1：修改Jekyll生成相对路径的图片
在Jekyll模板中调整图片的src路径，去掉开头的/，让其变成相对路径。比如将原标签：
```
<img src="/assets/images/view.png" alt="" />
```
修改为：
```
<img src="assets/images/view.png" alt="" />
```
如果需要适配Jekyll的baseurl配置，可以用模板变量动态生成相对路径：
```
<img src="{{ site.baseurl }}assets/images/view.png" alt="" />
```
确保_config.yml中baseurl为空或设置为相对路径（比如baseurl: ""），这样生成的HTML会使用项目内的相对路径，Pandoc无需额外参数就能正确加载图片。
方法2：用命令行工具批量替换HTML中的绝对路径
不想修改Jekyll配置的话，可以用sed等工具先把HTML里的绝对路径替换成相对路径，再传给Pandoc处理。示例命令：
```
sed 's/src="\/assets\/images\//src="assets\/images\//g' your-generated.html | pandoc -o output.pdf
```
这条命令会把所有/assets/images/开头的图片路径替换成assets/images/，再由Pandoc转换为PDF。
方法3：指定Pandoc的资源根目录
告诉Pandoc将绝对路径的/映射到你的项目根目录，使用--resource-path指定项目根路径。比如你的项目根目录是当前工作目录，执行命令：
```
pandoc --resource-path=. your-generated.html -o output.pdf
```
这样Pandoc会把/assets/images/view.png解析为当前目录下的assets/images/view.png，从而正确加载图片。