Doctoolchain generateSite图片相对路径解析异常问题求助

这是Doctoolchain默认站点生成流程的集成行为导致的，并非单纯Asciidoctor或Jbake的单一问题，具体原因如下：

• Doctoolchain的资源管理逻辑：默认情况下，Doctoolchain会将所有文档引用的媒体文件统一归集到站点输出目录的中央images文件夹，并通过修改Asciidoctor的输出配置，把图片路径重写为指向这个中央目录（也就是你看到的../images/media/image.png）。但它的资源复制逻辑没有正确处理"文档同目录子文件夹"这种场景，导致路径改了但原文件没被复制到目标位置。
• 单独Asciidoctor的差异：直接用asciidoctor编译单个文件时，不存在Doctoolchain额外的资源归集和路径重写逻辑，所以会严格保留你写的相对路径，自然不会出现问题。

如果要保留媒体文件和生成的文档在同一目录，可以通过调整Doctoolchain的配置实现：

1. 修改资源复制规则：找到Doctoolchain的核心配置文件（如doctoolchain.yml），调整资源复制的任务规则，让文档同目录下的media文件夹被同步复制到输出目录对应的文档子目录中。
2. 禁用路径重写：在你的Asciidoc文档头部添加属性配置:imagesdir: media，强制Asciidoctor输出相对当前文档的路径；同时确保Doctoolchain不会重写这个路径配置，或者在Jbake的配置中关闭媒体文件的中央归集行为。

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