Posted by Jeremie Bresson on Jan 23, 2015; 7:51am
URL: https://discuss.asciidoctor.org/asciidoctor-maven-plugin-and-images-tp2695.html

I would like to understand how images are handled using the asciidoctor-maven-plugin used to generate html

In the pom file, I can read this:

---
Embed stylesheets but link images (default)::
  - don't set embedAssets option
  - don't set linkcss attribute
  - set imagesdir attribute to path relative to AsciiDoc source file

  <attributes>
      <imagesdir>./images</imagesdir>
  </attributes>

IMPORTANT: When you enable image embedding, you must qualify the path the the imagesdir, as shown above.

---

Well... I am not sure to understand what this means, and how to use it.

== 1/ first use-case: renaming

Rename
`asciidoctor-maven-examples/asciidoc-to-html-example/src/docs/asciidoc/images`
to
`asciidoctor-maven-examples/asciidoc-to-html-example/src/docs/asciidoc/imgs`

Because `<imagesdir>` is defined in the pom.xml, it is the leading declaration.
It needs to be changed from
`<imagesdir>./images</imagesdir>`
to
`<imagesdir>./imgs</imagesdir>`.

I think it is a good practice to also modify the imagesdir declaration on top of the `example-manual.adoc`:
`ifndef::imagesdir[:imagesdir: imgs]`
This way if you have a preview program to watch how the document will look like.

== 2/ second use-case: location of the image folder.

I have tried to move the images folder somewhere else:
`asciidoctor-maven-examples/asciidoc-to-html-example/src/imgs`
In the document the imagesdir declaration becomes:
`ifndef::imagesdir[:imagesdir: ../../imgs]`

This works well with a preview program. But the maven plugin is not capable of handling this.
The maven plugin copy the content (without the asciidoctor files) of sourceDirectory (`src/docs/asciidoc`) to the `target/generated-docs`.

If you set the imagesdir property in the pom file to: `<imagesdir>./images</imagesdir>` [imagesdir2]. The path in the `src` attribute of the `img` tag doesn't point to the image.

My expectations would be that the images from
`asciidoctor-maven-examples/asciidoc-to-html-example/src/imgs` [imagesdir1]
should be copied to
`asciidoctor-maven-examples/asciidoc-to-html-example/target/generated-docs/images` [imagesdir2].
During this operation, it would be nice to copy only the images (from imagesdir1 to imagesdir2) that are used in the produced html file.

Such program is really not complicated to write (few lines of java code if you combine jsoup and google guava).
I have no idea if it is easy to plug such a program into the maven chain (in order to run it after the generation of the html using asciidoctorj).
Instead of jsoup, if acsiidoctorj is capable to produce the list of used images, this can also be used as input.

---

Maybe I do not understand it well.
Feel to explain me the philosophy behind image handling.

Another approach for asciidoctorj (or asciidoctor-maven-plugin) could be:

* with imagesdir you specify where the images are (this how it seems to work anywhere else)
* with an additional parameter imagesdir_out you specify where the images should be. The default value is iamgesdir, but if you specify something else you can.

I have noticed the gradle plugin has a special note about handling additional files.

Also related to this topic, the issue in asciidoctor-pdf about images: Images are not being correctly inserted