Is it possible to have images next to .adoc files in the pages folder?

Question

The structure of the family directories, as outlined in the docs requires every image to be placed inside the images directory. However, the OptaPlanner documentation contains both images and asciidoc files in the same directory per chapter. Please see the directory structure below:

https://github.com/kiegroup/optaplanner/tree/main/optaplanner-docs/src/main/asciidoc

Changing the current structure is undesired due to existing references from external repositories (breaking backward compatibility).

Is there a way of configuring Antora to pick up images from the pages directory and its subdirectories?

Answer 1

No.

The best-practices answer: Antora requires a specific directory structure and you have to adopt it.

You can adjust the Asciidoc markup to achieve this goal:

image::./relative/path/to/image.jpg[]

However, doing so could break your compatibility.

Antora 3 (currently in alpha) will provide symlink support, so you could create symlinks in the images folder that point to the images within the pages folder. Once that is in place, you can refer to those images like any other image in the images folder.

With Antora 3, you also could write an extension that locates images within the pages folder and add them to the contentCatalog as if they had been in the images folder. That would be notably more effort.