Support for image dimensions

Spec
3

There’s a discussion about this on the pandoc issues page where I proposed the following syntax. (However, image dimensions should be seen in light of the issue of a generic attribute syntax.)

The syntax for inline images is:

![caption](image.png){#id .class key1="val 1" key2="val 2"}

and for reference images:

![caption]

[caption]: image.png {#id .class key1="val 1" key2="val 2"}
  • For HTML/EPUB all attributes are passed through “as is”. This provides elegant support for all future responsive image properties (e.g. srcset, sizes) as well as a consistent way to specify the plain old HTML attributes width and height. So if you write ![](image.png){width=300 height=200}, you’ll get <img src="image.png" width="300" height="200">. (This is also useful to instruct the browser to reserve a 300x200 pixel box until the image is loaded to prevent a jarring reflow when the image arrives, but this could also be done with CSS.)
  • The other writers ignore attributes that are not supported by their output format.
  • The width and height attributes need special treatment. When used without a unit, the number’s unit is in pixels (to keep the syntax consistent with passing through HTML attributes). However, one of the following units can be used: px, cm, inch and %.
    • Pixels are converted to cm/inch for output in page-based formats like LaTeX and vice versa for output in HTML. Pandoc could introduce a --dpi option, but the default would be 96dpi.
    • If % is used, the result would be for example <img href="file.jpg" style="width: 50%;" /> or \includegraphics[width=0.5\textwidth]{file.jpg} (LaTeX) and finally \externalfigure[file.jpg][width=0.5\textwidth] (ConTeXt).
  • In formats like HTML and ConTeXt that have a notion of a class, ![](file.jpg){.myClass} will result in <img href="file.jpg" class="myClass" /> and \externalfigure[file.jpg][myClass] respectively. (Note that the complete ConTeXt syntax is \externalfigure[file.jpg][width=8cm, height=1cm][myClass] and the class has always lower precedence, whereas CSS has always higher precedence than the HTML attributes.)
  • When no attributes are specified, the behaviour is obviously the same as now (DPI image metadata, for example, can still be used).
3 Likes