Asciidoctor-pdf: Images paths in included documents

[plaindocs]

So I have a set up where I have various documents, each with separate images

--doc A
----chapters
----images
--doc B
----chapters
----images
--doc C
----index.adoc

And in doc C I include chapters from doc A and B, each of which have image paths relevant to their respective image dirs.

In doc C these are resolved relative to the top index.adoc in doc C, so the images do not resolve.

What is the best way to fix this? I want the images to work in both situations.

[mojavelinux]

Images always resolve relative to the imagesdir, which is setup to be the directory of the master document by default. The imagesdir does not update as the directory changes with includes unless you set the attribute again at the top of the included document.

I believe this behavior is still being discussed in core.

• https://github.com/asciidoctor/asciidoctor/issues/650
• https://github.com/asciidoctor/asciidoctor/issues/633
• https://github.com/asciidoctor/asciidoctor/issues/894

I think the conclusion is that we need a block macro for subdocuments that has different behavior from include. The include directive is for patching together content without giving the parser any indication that it happened. This is a different use case from subdocuments. We currently don't have a solution for subdocuments, but it can be implemented using extensions today until it finds its way into core.

[roelvs]

I stumbled across an inconsistency between asciidoctor 1.5.2 and asciidoctor-pdf alpha 9 with the :imagesdir: directive similar to this issue.

The syntax below (with the images in their dedicated directories) renders with Asciidoctor (html), but in Asciidoctor-pdf, the second and third 'imagesdir'-directive are not interpreted.

...
:imagesdir: ch01/images
include::ch01/ch01_power.asc[]

:imagesdir: ch02/images
include::ch02/ch02_CPU.asc[]

:imagesdir: ch03/images
include::ch03/ch03_memory.asc[]
...

Would there be a workaround for asciidoctor-pdf? What would be the preferred syntax in this example?

[mojavelinux]

@roelvs Oops. It appears we are caching the resolved imagesdir attribute value, which we can't do or else it breaks this use case. I've fixed it with commit 8bf93d293928222ee52917ae29df879b1c7fcdbf.

[camilotejeiro]

To be able to build the included documents independently and resolve the images directory I normally use an ifndef at the beginning of my included files (it's a workaround, it is probably not pretty).

= document name
// define images directory relative to pwd if not defined in master.   
ifndef::imagesdir[:imagesdir: ../images]

[mojavelinux]

@camilotejeiro That's exactly what I do. That tends to be the recommend approach to indicate that the imagesdir might be overridden externally.

[jfernandz]

@mojavelinux @camilotejeiro but then the folder structure that you have is not the same than @plaindocs has pointed:

--doc A
----chapters
----images
--doc B
----chapters
----images
--doc C
----index.adoc

but more like this other one:

--images
-----doc A
-----doc B
--doc A
----chapters
--doc B
----chapters
--doc C
----index.adoc

Is that right?

[teacherpan]

Tree as:

--doc A
----chapters
----images
--doc B
----chapters
-------index.adoc
----images
----index.adoc
--doc C
----index.adoc

You can add some code as below， and then you can include files as you want，the images will be showed in anywhere.

doc C/index.adoc

:path: doc C/

ifndef::rootpath[]
:rootpath: ./../
endif::rootpath[]

doc B/index.adoc

:path: doc B/
:imagesdir: images/

ifdef::rootpath[]
:imagesdir: {rootpath}{path}{imagesdir}
endif::rootpath[]

ifndef::rootpath[]
:rootpath: ./../
endif::rootpath[]

--doc B/chapters/index.adoc

:path: doc B/chapters/
:imagesdir: ../images/

ifdef::rootpath[]
:imagesdir: {rootpath}{path}{imagesdir}
endif::rootpath[]

ifndef::rootpath[]
:rootpath: ./../../
endif::rootpath[]

Get more: https://github.com/mengyunzhi/asciidoctor-sub-file-image-show