路径困境：解决AsciiDoctor PDF与Hugo的图片渲染路径差异

方法1：命令行参数覆盖:imagedir #

完全可以在调用Asciidoctor PDF时通过命令行参数动态设置:imagedir的值，无需修改原始adoc文件：

• 若adoc文件中配置的是适合Hugo的:imagedir: ../，生成PDF时执行：

  asciidoctor-pdf -a imagedir=. your-document.adoc
  

  这里的-a imagedir=.会覆盖adoc内的配置，让PDF生成器使用当前目录（与adoc同目录）加载图片。

• 若图片放在adoc文件的子目录（比如images/），Hugo需要:imagedir: ../images，则生成PDF时执行：

  asciidoctor-pdf -a imagedir=images your-document.adoc
  

方法2：在adoc中使用条件属性自动适配 #

更省心的方式是在adoc文件内添加条件判断，根据输出格式自动切换:imagedir，无需每次手动传参数：

# 针对PDF输出设置图片路径
ifdef::backend-pdf[]
:imagedir: .
endif::backend-pdf[]

# 针对HTML（Hugo）输出设置图片路径
ifdef::backend-html[]
:imagedir: ../
endif::backend-html[]

# 若图片在子目录，调整为对应路径
ifdef::backend-pdf[]
:imagedir: images/
endif::backend-pdf[]
ifdef::backend-html[]
:imagedir: ../images/
endif::backend-html[]

Asciidoctor会根据输出后端（PDF/HTML）自动加载对应的:imagedir配置，Hugo生成网页和Asciidoctor生成PDF时都能正确解析图片路径。

内容的提问来源于stack exchange，提问作者rmfberlin