Support for image dimensions

Spec
1

Is there a reason there is no spec for specifying image dimensions? It seems fairly common.

Is this something plugins are going to need to take care of?

4 Likes
2

Agreed this would be nice to have provided it can be done in a way that does not add a bunch of rules or complexity.

1 Like
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
4

I get this, and the appeal for a generic solution.

But there is also an appeal for a very simple solution here: ![caption](image.png 100x100) its very nice on the eyes.

6 Likes
5

Should image dimensions be explictly declared? The content management system could get the image dimensions automatically from the file. These dimensions could then be added to the HTML after the conversion from Markdown.

6

Ah that was tackled in that genetic syntax thread as well Sam. Basically it can be thought of as “syntactic sugar” and auto converted to the full {} form internally.

http://talk.commonmark.org/t/consistent-attribute-syntax/272/22?u=mofosyne

Here is a copy of the relevant section:

Embedded Media

!mediaType[description](url){#myId .myClass key=val key2="val 2"}

  • assumed to be image if mediaType left blank

  • syntactic sugar ( content of () handled by mediaType handler/extension):

      ![](file.mp4 "video title" 80x10 )
 is equivalent to typing: 

  !video[](file.mp4){title="video title" width=80 height=10}
1 Like
7

I’m interested in image dimensions syntax as well. I propose the following:

![](/img.jpg =80x10)
![](/img.jpg =80) - only width
![](/img.jpg =x10) - only height

The = sign would be a useful delimiter to require since URLs can technically have spaces, and maybe someone would like to embed the /img.jpg%2080x10 URL (notice no = sign) without the final part of it being interpreted as image dimensions. I think requiring delimiter character = would make it easier to write and maintain parser logic for this, like with link titles (url "...").

8

I’ve just been told that this exact syntax is listed among proposed extensions to CommonMark.

9

Could you please show where an RFC allows literal spaces (U+0020) inside a URL or URI?

There may be literal space characters in HTML attributes like src and href, though, which a browser would have to percent-encode as %20. The spec requires parsers to do the same for URLs inside angle brackets <>. It should probably say something more useful for other cases: currently it abandons the link completely if a space is encountered in the “link destination” part and is not followed by a “link title”.

As you can see over at Babelmark, the backwards compatibility for this one really sucks. Maruku’s fallback behavior is okayish and Discount has adopted the proposed syntax (or at least the verbose variant), although I think it was first implemented in another flavor that is not participating in Babelmark.

10

You’re right, URLs don’t really support literal spaces. Some Markdown implementations will allow one in link or img hrefs and convert it to %20, but not CommonMark.

11

Update: Pandoc now supports “Syntax for specifying image size” as shown in https://github.com/jgm/pandoc/issues/261#event-470079999

Merge log: https://github.com/jgm/pandoc/commit/244cd5644b44f43722530379138bd7bb9cbace9b

e.g.

![](file.jpg){ width=50% }
1 Like
12

Even so, CM would still be better of without support for a generic key=value syntax in curly braces. Predefined English/HTML keywords just don’t fly with the markdown spirit. I can envision some shorthands emerging, though.

![alt](src.img "title" #id .class %size ^alignment)
![alt](src.img "title" =400*300/96)
![alt](src.img "title" 400:300 @96)
![alt](src.img "title" 400*300px @96ppi)
![alt](src.img "title" 400*300, file.2x.img 800*600)
![alt](src.img "title" 4:3, file.wide.img 16:9)

etc.pp. and I would be fine with that being limited to reference-style embedded resources.

2 Likes
13

Curly braces key=value is certainly not the most optimal, but it is the safest choice at this stage, in avoiding the pollution of parser syntax.

Most certainly there is a case for shorthands, but it should be implemented more carefully and only for the most commonly used fields (e.g. pixel size).

So I agree with your desire for shorthands, but think its something to tackle after the curly brace approach.

  • Cue the why not both mexican girl taco ad meme
14

I’m still unconvinced of the need to support image dimensions in CommonMark.

For a CMS, static site generator, or a forum such as Discourse, the image dimensions could be added in a pre-processing step performed. All of the information needed to figure out the image dimensions could be programatically pulled from the image file and the dimensions of the site layout.

You may also want the application to render different image sizes responsively, based on the browser window size. Specifying image dimensions assumes a degree of rigidity and isn’t flexible enough to account for layout changes in the future. You may want documents that are copy/pasted between sites with different layout sizes to use different image dimensions.

In any case, image dimensions are a technical detail. Markdown is for writers, rather application and layout logic. Do we really want writers dealing with this additional complexity?

7 Likes
15

I agree, there is something wrong with adding dimentions directly to image syntax. We still have potential hack via {…} for custom attributes. IMHO width/height will be better there.

3 Likes
16

That’s a good point.

For the record, I’m against adding a syntax to add arbitrary attributes to elements. The rationale is pretty much the same as Chris just explained. If anyone remembers Textile, then you would surely remember how it was one of the worse features of Textile, since it made sources less readable and overly technical.

2 Likes
17

Maybe we just need to tag an image to identify it?

![my image](http://myimage.png "title" "tag")

In the case of HTML output, this would become a class attribute for the image. In other output processors, it would be whatever is appropriate.

18

Usually, existing extensions and proposals adopt the W3C Selectors syntax with .class and unique #ID.

19

I find W3C selectors contrary to Markdown syntax.

![my image](http://myimage.png "title" "figure-1")

seems more in line with the aesthetics/intent of Markdown.

20

Consider writing something like typical README.md file. Many people add illustrations to make description more good looking. In such cases I obviously do not want to start image editor to resize the image. Actually, playing with image size inside side opened image editor is not what I want in such cases. It is even more important in the case when the image is refered by a link to another web resource, so I simply do not have control over its size. I am not to deep in discussions about CommonMark flaws, so I have nothing to say about syntax, but it is clear for me that such functionality is a must have one.