Antora中如何实现包含局部文件的PlantUML实体关系图？

需求说明 #

我在Antora里管理项目文档，想把实体关系模型拆分成单个实体的puml文件，再用一个总文件来定义实体间的关联，目的是：

• 每个实体的图表能在独立页面展示，保持专业整洁
• 避免把所有内容塞进单个文件导致杂乱
• 总文件只负责维护实体间的关系，不包含实体本身的定义

遇到的问题 #

单个实体的puml文件（比如book-entity.puml、structure-entity.puml）能正常渲染，但总文件domain.puml编译时会报!include error，提示PlantUML找不到被引入的实体文件。

环境细节 #

• 所有puml文件都放在Antora模块的examples目录下
• 使用PlantUML服务器渲染图表（因为要加C4图，没法用Kroki）

相关代码示例 #

structure-entity.puml #

@startuml

entity Structure {
  'removed for brevity
}

@enduml

book-entity.puml #

@startuml

entity Book {
  'removed for brevity
}

@enduml

domain.puml #

@startuml

  !include structure-entity.puml
  !include book-entity.puml

  Structure .. Book

@enduml

book-entity-doc.adoc（可正常显示） #

.This diagram works
[plantuml]
....
include::example$book-entity.puml
....

domain-doc.adoc（无法正常显示） #

.This diagram does not work
[plantuml]
....
include::example$domain.puml
....

我的推测 #

应该是Antora生成过程中路径基准变了，导致PlantUML解析!include时找不到正确的文件路径，但不知道具体怎么排查和解决。

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