https://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-tp3040p3108.html
Mark,
The unit of measure for the height and width of images is pixels by default. In the HTML backend, these values are assigned directly to the width and height attributes on the img tag, as you can see here:
The unit of measure matches the default for HTML (CSS pixels).
I agree this would be good to document.
However, the default stylesheet for Asciidoctor adds responsive characteristics to images, so the pixels are only suggested values. The image will reduce in size to fit the screen as the viewport shrinks. What's really important is the aspect ratio that these numbers capture (as that is preserved).
The PDF backend (via DocBook) uses these values merely to understand the resolution and aspect ratio of the image. You can set the relative width (relative to the page) using the scaledwidth attribute on the image macro.
image::image.png[Alt Text, 300, 200, scaledwidth=25%]
fopub includes some logic that will scale the image appropriately even when scaledwidth is not set. See:
You could copy and reuse this logic in your DocBook pipeline. I go tit from the PressGang team at Red Hat.
Other than that, we don't have a lot of control yet from the AsciiDoc over image scaling in PDF. This is something we're actively discussing in the issue tracker. Your input is welcome.
Cheers,
-Dan