# Support for image dimensions **URL:** \ **Category:** Spec\ **Created:** [September 3, 2014, 11:34pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148 "2014-09-03T23:34:51Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![sam](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/sam/32/71_2.png) [@sam](https://talk.commonmark.org/u/sam)\ **Post date:** [September 3, 2014, 11:34pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/1 "2014-09-03T23:34:51Z")
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? ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [September 4, 2014, 1:28am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/2 "2014-09-04T01:28:19Z")
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. ---
**Author:** ![mb21](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mb21/32/162_2.png) [@mb21](https://talk.commonmark.org/u/mb21)\ **Post date:** [September 4, 2014, 10:31am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/3 "2014-09-04T10:31:10Z")
There’s a discussion about this on the [pandoc issues page](https://github.com/jgm/pandoc/issues/261) where I proposed the following syntax. (However, image dimensions should be seen in light of the [issue of a generic attribute syntax](http://talk.commonmark.org/t/consistent-attribute-syntax/272).) > 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 ``. (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 `` 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 `` 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). ---
**Author:** ![sam](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/sam/32/71_2.png) [@sam](https://talk.commonmark.org/u/sam)\ **Post date:** [September 4, 2014, 11:27am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/4 "2014-09-04T11:27:00Z")
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. ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [September 9, 2014, 6:24am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/5 "2014-09-09T06:24:15Z")
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. ---
**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\ **Post date:** [September 9, 2014, 9:18am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/6 "2014-09-09T09:18:35Z")
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](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): ---
**Author:** ![mislav](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mislav/32/822_2.png) [@mislav](https://talk.commonmark.org/u/mislav)\ **Post date:** [October 29, 2015, 6:27pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/7 "2015-10-29T18:27:55Z")
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 "...")`. ---
**Author:** ![mislav](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mislav/32/822_2.png) [@mislav](https://talk.commonmark.org/u/mislav)\ **Post date:** [October 29, 2015, 8:06pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/8 "2015-10-29T20:06:30Z")
I’ve just been told that this exact syntax is [listed among proposed extensions](https://github.com/jgm/CommonMark/wiki/Deployed-Extensions#image-size) to CommonMark. ---
**Author:** ![Crissov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\ **Post date:** [October 29, 2015, 9:19pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/9 "2015-10-29T21:19:45Z")
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](http://spec.commonmark.org/0.22/#link-destination) 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](http://johnmacfarlane.net/babelmark2/?normalize=1&text=*+!%5Bdirect+image%5D(zeroth.png)%0A*+!%5Bdirect+image%5D(first.png+%22a+title%22)%0A*+!%5Bdirect+image%5D(second.png+(also+a+title))%0A*+!%5BVGA%5D(third.png+%3D640x480)%0A*+!%5BSVGA%5D(fourth.png+%22800+%C3%97+600+pixels%22+%3D800x600)%0A*+!%5BWSVGA%5D(fifth.png+(960+%C3%97+600+pixels)+%3D960x600)%0A*+!%5BDVGA%5D(sixth.png+%3D960x640+%22960+%C3%97+640+pixels%22)%0A*+!%5BWDVGA%5D(seventh.png+%3D1024x640+(1024+%C3%97+640+pixels))%0A*+!%5Breferenced+image%5D%5Breference%5D%0A*+!%5Breferenced+image%5D%5Breference-quote%5D%0A*+!%5Breferenced+image%5D%5Breference-paren%5D%0A*+!%5BXGA%5D%5Bxga%5D%0A*+!%5BXGA%2B%5D%5Bxgaplus%5D%0A*+!%5BWXGA%2B%5D%5Bwxgaplus%5D%0A*+!%5BSXGA%5D%5Bsxga%5D%0A*+!%5BWSXGA%5D%5Bwsxga%5D%0A%0A ____ %0A++%5Breference%5D%3A+eighth.png%0A++%5Breference-quote%5D%3A+ninth.png+%22quoted+title%22%0A++%5Breference-paren%5D%3A+tenth.png+(parenthesized+title)%0A++%5Bxga%5D%3A+eleventh.png+%3D1024x768%0A++%5Bxgaplus%5D%3A+twelfth.png+%221152+%C3%97+864+pixels%22+%3D1152x864%0A++%5Bwxgaplus%5D%3A+thirteenth.png+(1536+%C3%97+864+pixels)+%3D1536x864%0A++%5Bsxga%5D%3A+fourteenth.png+%3D1280x1024+%221280+%C3%97+1024+pixels%22%0A++%5Bwsxga%5D%3A+fifteenth.png+%3D1600x1024+(1600+%C3%97+1024+pixels)%0A), 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. ---
**Author:** ![mislav](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mislav/32/822_2.png) [@mislav](https://talk.commonmark.org/u/mislav)\ **Post date:** [October 31, 2015, 4:53pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/10 "2015-10-31T16:53:11Z")
> [@Crissov](#): > > Could you please show where an RFC allows literal spaces (U+0020) inside a URL or URI? You’re right, URLs don’t really support literal spaces. [Some Markdown implementations will allow one](http://johnmacfarlane.net/babelmark2/?normalize=1&text=!%5B%5D(a+12)) in link or img hrefs and convert it to `%20`, but not CommonMark. ---
**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\ **Post date:** [November 20, 2015, 8:26am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/11 "2015-11-20T08:26:16Z")
Update: Pandoc now supports “Syntax for specifying image size” as shown in [https://github.com/jgm/pandoc/issues/261#event-470079999](https://github.com/jgm/pandoc/issues/261#event-470079999) Merge log: [https://github.com/jgm/pandoc/commit/244cd5644b44f43722530379138bd7bb9cbace9b](https://github.com/jgm/pandoc/commit/244cd5644b44f43722530379138bd7bb9cbace9b) e.g. ``` ![](file.jpg){ width=50% } ``` ---
**Author:** ![Crissov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\ **Post date:** [November 20, 2015, 1:23pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/12 "2015-11-20T13:23:31Z")
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. ---
**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\ **Post date:** [November 27, 2015, 2:24pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/13 "2015-11-27T14:24:48Z")
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 ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [November 29, 2015, 11:34am UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/14 "2015-11-29T11:34:09Z")
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](http://alistapart.com/article/responsive-images-in-practice). 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? ---
**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\ **Post date:** [November 29, 2015, 4:36pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/15 "2015-11-29T16:36:56Z")
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. ---
**Author:** ![mislav](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mislav/32/822_2.png) [@mislav](https://talk.commonmark.org/u/mislav)\ **Post date:** [November 29, 2015, 7:05pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/16 "2015-11-29T19:05:22Z")
> [@chrisalley](#): > > Markdown is for writers, rather application and layout logic. Do we really want writers dealing with this additional complexity? 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. ---
**Author:** ![Mike\_Ward](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mike_ward/32/520_2.png) [@Mike\_Ward](https://talk.commonmark.org/u/Mike_Ward)\ **Post date:** [November 30, 2015, 4:14pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/17 "2015-11-30T16:14:40Z")
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. ---
**Author:** ![Crissov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\ **Post date:** [November 30, 2015, 10:50pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/18 "2015-11-30T22:50:09Z")
Usually, existing extensions and proposals adopt the W3C Selectors syntax with `.class` and unique `#ID`. ---
**Author:** ![Mike\_Ward](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mike_ward/32/520_2.png) [@Mike\_Ward](https://talk.commonmark.org/u/Mike_Ward)\ **Post date:** [November 30, 2015, 11:24pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/19 "2015-11-30T23:24:57Z")
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. ---
**Author:** ![prokher](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/prokher/32/883_2.png) [@prokher](https://talk.commonmark.org/u/prokher)\ **Post date:** [January 16, 2016, 5:46pm UTC](https://talk.commonmark.org/t/support-for-image-dimensions/148/20 "2016-01-16T17:46:56Z")
Consider writing something like typical [README.md](http://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. [Next page](https://talk.commonmark.org/t/support-for-image-dimensions/148.md?page=2)