How to have a diagram with included partials in Antora?

Question

I have my project where the documentation is managed by Antora. What I'd like to achieve in case of Entity relation model is that every entity has its own file while the overall entity relationship model have all of them included.

What I want to achieve with this is the following:

• every entity has its own diagram in its own page, it looks good and professional
• putting everything into a single file will be messy very quickly
• the entity relationship uml description is about the relations and not defining entities

When I compile it the main file containing the relations only shows !include error saying that PlantUML does not find the file should be included.

• puml files are located in the examples directory of the Antora module
• Antora uses PlantUml server according to this in the doc
• using Kroki is a no go as I'll add C4 diagrams

The result:

• the individual entity diagram files (book and structure in this example) are working, they display the diagram
• the file where these small diagrams are included (domain.puml) don't work
• I assume it is something path related problem as the base changes when Antora runs its generating magic, but I don't know how to go after this

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
....

Answer 1

I don't think there is a solution, currently.

Antora gathers its content from Git repos and stores it in a virtual filesystem (the contentCatalog). PlantUML server gets its content over the wire or from the local filesystem.

Since the local filesystem very likely isn't going to match the virtual filesystem, and Antora doesn't know how to compose complete diagrams when !include directives are involved, there is currently no way to achieve your goal.