How reference correctly images through many .adoc files located in different folders

Question

I am working with Atom Editor + the two plugins/packages available about asciidoctor.

• asciidoc-preview
• language-asciidoc

All work how it is expected. But I am with the following situation:

I have the following directory structure:

xml
  figures
     findOneXml.adoc
     findOneXml.png
  urls
     findOne.adoc

Where findOneXml.adoc (within figures folder) has

[[findOneXml]]
image::findOneXml.png[caption="Figure - " title="findOneXml"]

With the live preview I can see the image and its respective description

Now with findOne.adoc (within url folder) contains among many things the following line:

include::../figures/findOneXml.adoc[]

I think the path reference is ok. if I use other, the live preview shows an error message about an invalid or wrong path.

But through the live preview I see broken the image but I can see the description.

What is wrong or missing?

Even with include::./../figures/findOneXml.adoc[] fails

Note: in the sub/child document I need add other data how notes, tips (Admonition), that child document would be reused many times by other parents. So I only don't need refer to the image only.

Thanks

Undecided

Answer 1

The image is resolved relative to an internal base path of the asciidoc rendering engine. In your case I assume the engine takes the path of the rendered (main, parent) document. So, images are resolved relative to that. Try:

image::../figures/findOneXml.png[]

This should work for both adoc documents, as the path moves up to the parent directory and then explicitly down into the figures directory.

In case you want to have a common absolute base for images, you can also set the :imagesdir: attribute to the base url of your images directory. This should then also work with live previews:

• Asciidoctor Documentation Site - Set the Images Directory
• Asciidoctor Documentation Site - Image Paths and Formats

Nominalism

Hello, thanks by the reply. Even when that works (not tested yet) in the sub/child document I need add other data how notes, tips (Admonition), that child document would be reused many times by other parents. So I only don't need refer to the image only. – Undecided

When running asciidoctor (not sure about the plugins, if they make this option available or not) you'll want to set the root directory to some parent folder then adjust the references as needed, in your example I'd say use xml as the parent directory. – Luzluzader

Added more info to my answer to make you aware of the :imagesdir: attribute. – Nominalism

@ManuelJordan I suspect now that you misunderstood my answer. I suggested that you add that image::../figures/findOneXml.png[] reference to your SUB/CHILD document. I do not suggest that you directly reference the image from your parent document. – Nominalism

Thanks a lot, with :imagesdir: works perfect now. About your latest answer, the figure.png is in the same location than the sub-child document – Undecided

Hi @MartinSchimak just curious if exists a way that :imagesdir: adocs/results/figures works for subfolders of figures too. – Undecided

@ManuelJordan Once you have set the :imagesdir: folder it affects all image::* references, even with subfolders - so in case you need to reference an image in a subfolder of :imagesdir:, just use e.g. image::sub/findTwoXml.png – Nominalism

@ManuelJordan I still think you misunderstand the first part of my answer. As long as your parent documents are on the same "depth" of your folder hierarchy as the included figures/findOneXml.adoc (regardless of the specific folder!), you can use image::../figures/findOneXml.png[] within figures/findOneXml.adoc and your parent documents (which include findOneXml.adoc) will successfully show the images, because the path ../figures/findOneXml.png is fully valid for them, too. In this case you don't need the :imagesdir: - it all depends on your very specific requirements... – Nominalism

Thanks @MartinSchimak by the clarification. Really appreciate your support. – Undecided

According your two latest comments, seems more cleaner and less verbose use :imagesdir: . Thanks a lot! It avoids use "../" and therefore I am able to change any .adoc in the structure of my directories. – Undecided

See also the comment at github.com/asciidoctor/asciidoctor/issues/1567. (I wish we could assemble asciidoc hierarchically, not just by simple preprocessor.) – Barrow