correctly sizing PNG images in markdown with pandoc for html/pdf/docx

Question

I am trying to use markdown with pandoc to convert a single document into html, pdf, and docx. It's an extremely simple document containing only math-less text and a few images. The images are in PNG format. I include an image using this in markdown source:

<div style="float:center" markdown="1">

![my caption](./figures/myimage.png)

</div>

and compile it as:

# html
pandoc myarticle.md -c mystyle.css -o myarticle.html
# pdf
pandoc myarticle.md -V geometry:margin=1in -o myarticle.pdf
# docx
pandoc myarticle.md -o myarticle.docx

I noticed that some PNG images that have the same dimensions get sized differently in HTML and PDF formats. A PNG that is 250x256 px with low resolution (72 px/in) will appear in PDF as the correct size roughly on page, and appear in a reasonable size in html, but a PNG that has the same dimensions (250x256 px) but is high-res (300 px/in) get resized to be tiny on the page in the PDF output. I want to keep on set of PNG images in a size that I specify and have them appear in that size in both the HTML/PDF/DOCX formats.

I am willing to give up automatic docx support (or deal with a lot of manual formatting after) just to have PDF/HTML.

How can I tell pandoc not to resize PNGs for PDF or image, and have them appear in their correct images? thanks.

Solution

Dimensions are converted to pixels for output in HTML-like formats. Use the --dpi option to specify the number of pixels per inch. The default is 96dpi.

Find the most common element in your pictures and use that. Only modify the exceptions.

---

Examples: dpi, width, height.

If you give it the dpi information:

Add the --dpi option as stated to override the default.

---

If most of your pictures have a common height or width, that should be easily corrected.

For example, you changed the line to:

![my caption](./figures/myimage.png){ width=250px }

or

![my caption](./figures/myimage.png){ height=256px }

Or do this in straight HTML markup:

<img src="./figures/myimage.png" alt="my caption" style="width: 250px;"/>

or

<img src="./figures/myimage.png" alt="my caption" style="height: 256px;"/>

and the ratio will be correct.

---

Reference: Pandoc Readme

For HTML and EPUB, all attributes except width and height (but including srcset and sizes) are passed through as is. The other writers ignore attributes that are not supported by their output format.

The width and height attributes on images are treated specially. When used without a unit, the unit is assumed to be pixels. However, any of the following unit identifiers can be used: px, cm, mm, in, inch and %.

Dimensions are converted to inches for output in page-based formats like LaTeX. Dimensions are converted to pixels for output in HTML-like formats. Use the --dpi option to specify the number of pixels per inch. The default is 96dpi.

The % unit is generally relative to some available space. For example the above example will render to <img href="file.jpg" style="width: 50%;" /> (HTML), \includegraphics[width=0.5\textwidth]{file.jpg} (LaTeX), or \externalfigure[file.jpg][width=0.5\textwidth] (ConTeXt).

Some output formats have a notion of a class (ConTeXt) or a unique identifier (LaTeX \caption), or both (HTML).

When no width or height attributes are specified, the fallback is to look at the image resolution and the dpi metadata embedded in the image file.

Comments

[John MacFarlane]

A PNG that is 300dpi but only 250x256px should be quite small on the page, shouldn't it? (Less than one inch square.) A PNG with a lower dpi will be bigger on the page. Pandoc takes into account dpi information, as well as pixel size, in sizing the images. And shouldn't it? Perhaps you could use CSS to globally scale down the high-res images in HTML.

[user46976]

@JohnMacFarlane: I see that pandoc's behavior is correct in taking dpi into account - but I want it to ignore dpi and stick with absolute sizes, so that I can keep a single high res PNG for all images. Is the correct way to do this to make lower resolution version of the images, or is there a way to make pandoc simply only use the dimensions of image and ignore resolution? That would be simplest from my end

[rriemann]

One can also use { width=100% } for relative widths to the overall screen/page/linewidth size.

[oarfish]

Can this be used with pandoc-crossrefs {#fig:refname} syntax?

[oarfish]

Answering my own comment: {#fig:refname width=50%} works.