Asciidoctor: different imagesdir handling

[wols]

asciidoctor-1.5.5, asciidoctor-pdf-1.5.0.alpha.16

├── common
│   └── variables.adoc
├── export
│   ├── Article.html
│   └── Article.pdf
├── images
│   ├── diagram
│   │   └── dataflow.png
│   ├── figure
│   │   └── dataflow-components.png
│   └── logo.png
├── locale
│   └── attributes-de.adoc
└── Article.adoc

cd Article
asciidoctor-pdf -b pdf -D export Article.adoc



md5-337b986f6184f8bb3e40d112fc33ee32



asciidoctor [-b html5] -D export Article.adoc

...requires :imagesdir: ../images for correct output to export/Article.html.
Bug or feature or is the fault with me?

[mojavelinux]

The imagesdir has a different meaning / purpose for PDF and HTML. For PDF, it's interpreted relative to the source document. For HTML, it's interpreted relative to the output document (unless the images are embedded, in which case it behaves like PDF).

Here's why there is a difference.

When converting a PDF, the imagesdir tells the converter where to look for the image to embed. The converter is going to look for the image relative to the source document.

When converting the HTML, the imagesdir tells the client browser where to look for the image. The value should be the path from the output document to the location where you're publishing the images (which sit alongside the HTML document).

That's why there's a difference. So you have to set the attribute accordingly.

[wols]

Thanks for the fast clarification.
Would not a output handling in the options be better?
One unchanged source file and the relativity triggerd by -D...

[mojavelinux]

This behavior was defined by AsciiDoc Python and thus in order to be compliant (and not break a lot of documents) it must remain this way. However, I have often discuss of adding new attributes that would be used to control image handling in a more fine grained way. That's likely the path forward.

[wols]

I will handle my configuration so:

:imagesdir: images
ifdef::backend-html5[:imagesdir: ../images]

[mojavelinux]

You've got the idea!

[johannesjh]

Note, also see related issues https://github.com/asciidoctor/asciidoctor/issues/650 and https://github.com/asciidoctor/asciidoctor/issues/894 where imagesdir is discussed in the context of standalone subdocuments.