如何配置Antora支持读取pages目录下与.adoc文件同存的图片？

完全可以通过配置实现该需求，无需调整现有目录结构，具体操作如下：

方案1：修改Antora内容源扫描规则 #

Antora默认仅会识别pages目录下后缀为.adoc的文件，你可以在Antora playbook配置文件（通常命名为antora-playbook.yml）中，为对应内容源添加自定义资源匹配规则，将图片文件纳入扫描范围：

content:
  sources:
    - url: ./optaplanner # 替换为你本地OptaPlanner仓库的实际路径
      start_path: optaplanner-docs/src/main/asciidoc
      # 新增资源匹配规则，覆盖默认的仅扫描adoc文件的限制
      files:
        - '**/*.adoc'
        - '**/*.png'
        - '**/*.svg'
        - '**/*.jpg'
        - '**/*.jpeg'
        - '**/*.gif'

配置后即可直接在.adoc文件中通过文件名引用同目录下的图片，无需添加额外路径前缀。

方案2：搭配Asciidoc全局属性适配 #

如果仅配置扫描规则后仍存在图片路径识别异常，可在playbook的Asciidoc配置段添加imagesdir属性：

asciidoc:
  attributes:
    # 将图片根目录映射为当前adoc文件所在的目录
    imagesdir: '{docdir}'

该配置会自动适配每篇adoc文件的所在路径，确保同目录下的图片可以被正常定位、加载。

兼容性说明 #

• 上述配置兼容Antora 2.3及以上所有版本
• 配置完成后执行一次完整构建即可验证效果，不会影响原有外部链接的可用性

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