Support for image dimensions demonstrates one possible application: pasting screenshots taken on a hi-dpi device into a post may make them appear at the wrong size, unless one can add the appropriate dimensions in css pixels.

The iDOT chunk from Apple appears to be the only metadata which could be used to automate such a size tagging. It is not standardized, will be destroyed by image editors, and doesn’t seem to cater for non-integer pixel densities.

Since the writer is putting an image into the document, you should most definitely give him the ability to control how it is sized. Imagine MS Word not letting you resize or reposition an image in a document because it’s “too complex” for the writers “little mind”. That’s ridiculous!

I’m slightly pissed because the wiki software I’m was trying to use ( is build on and doesn’t have any support at all for setting image sizes. Meanwhile look at all the glorious control I’d have if I was using MediaWiki:

SOrry, but I just had to rant! :rage:

1 Like

Markdown is quite different from MS Word. Whereas a Word document contains layout, presentation, and content information, Markdown is only used to structure content. This gives Markdown documents the advantage of being independent from how they are presented. Different applications can present the contents of the document in different ways - for example, one application could render the document as a single wide column, another in newspaper style columns. Different layouts may require images within the document to be rendered in different sizes too - for example, a mobile layout will typically require that a smaller version of the image is displayed compared to the layout that is rendered when using a desktop browser.

I think that image dimensions are a presentational concern that do not belong in Markdown.

That said, for power users who want to explictly define additional attributes such as image height and width, we could just use consistent attribute syntax rather than inventing a new syntax specifically for image dimensions.


I think that’s total BS, despite what Gruber sez. Nearly every commonmark code is for presentation only.

I wholeheartedly disagree with this.

CommonMark is meant for expressing meaning. It’s declarative. Writing *this is emphasized* doesn’t mean “make the words ‘this is emphasized’ italic”. It’s up to the consumer of the content to determine how the content and meaning expressed in a commonmark document will be presented.

And if you want images to include dimensions I have two suggestions:

  1. use HTML, <img src="..." alt="..." width="..." height="..."> is not difficult to write if you want to be explicit.
  2. use a post-processor.

I definitely recommend #2. CommonMark shouldn’t be overly concerned about specific implementation details, and why bother wasting an author’s time with information that code can easily detect automatically?

It’d be a simple matter of:

  • parsing the HTML
  • finding all the <img> elements
  • reading in each of their sources
  • setting the height and width attributes to the dimensions of the source

Of course, you may need to do something custom to handle SVG, but that’s the beauty of a post-processor. You can make it do whatever you want, or even add parameters to make it have customizable behavior.


Because you can not … eg: retina… a 300x300 image may have the intention of rendering in 100x100 or 150x150. There is no way of conveying this intention short of adding an awkward image tag or non-standard post processor.

You describe a non-standard behavior, and then complain that it may require a post-processing step? If you’re going to be providing retina images you ought to be using srcset or <picture>. Once you do that you’re going to need additional information anyway, such as where the alternative versions of the images are to be found, and what sizes should be supported.

And who’s to say a post-processor can’t have its own set of standards? That’s the point of separating it out. CommonMark shouldn’t be concerned with such things.

And as far as “can not” is concerned, it’s trivial to take <img src="/filename.jpg" alt="..."> and convert it to <img src="/filename.jpg" srcset="/filename-2x.jpg 2x" alt="...">. How the file names are mapped to srcset (or <source> elements for <picture>) can be configured from a post-processor, without cluttering up the raw CommonMark source or the CommonMark spec.


It seems to me that images are by definition a presentational concern. It’s hard to derive any meaning from them until they are rendered.

I disagree.

<img src="" alt="gorilla">

No; it’s not.


I disagree. Images are presentational. Otherwise, why have images in your Markdown? A thousand words or so should suffice.

1 Like

Same reason you might use a <table> or <video>. Supplementary content can be better at communicating specific information. That doesn’t make images a “presentational concern”, and in fact the HTML spec explicitly calls this out (emphasis mine):

The <img> element must not be used as a layout tool. In particular, img elements should not be used to display transparent images, as such images rarely convey meaning and rarely add anything useful to the document.

I hope you realize that what you just implied by referencing the idiom “A picture is worth a thousand words” is that an image can be used as a way of expressing meaning, which runs directly counter to your claim that “images are presentational”.

So if I put an image in a document because I like the way it enhances something in the document is that a presentational element or is it just supplemental? We could get all lawyerly about the answer but it’s kind of silly I think.

The supplemental argument is lost on me. So is the idiom argument.

I acquiesce.

Content = what’s inside the image, plus its title and description.

Presentation = how the image is displayed (including resizing).

I think chrisalley puts it best:

It’s a little tricky because the visual content of an image is not included in the Markdown text. But it’s still content.

1 Like

Another way to think about it: the content of the document (potentially) loses meaning if you don’t include the image when it is combined with another layout/design. Whereas the content of the document shouldn’t lose meaning when images are resized, the font changes, etc, because these concerns are seperate from the meaning of the content.


I’m pretty sure everyone is taking me bit too literal here. I’m simply saying that the nature of images are presentational in that you really can’t derive meaning until you render them. I can read text paragraph and understand it without rendering it. Images require rendering unless you put a very detailed description with them (and even then you don’t get the full effect). That’s what I meant by “1000 words”. It’s not that it isn’t content, it’s content that can’t be understood well until rendered.

Images (in Markdown) are different than other content. Authors want to position and size them.I find it weird that we’re so steadfast against doing this. (Yeah, I realize we’re trying to capture what’s currently done in Markdown in the first round of the spec).

And yes I know the arguments about keeping content and presentation separate. That’s great for those who want to go that way but frankly, most of the Markdown I write would benefit from just a bit of image layout control. Hell, left, center, right would get about 90% of it for me. Instead I’ll keep using clever tricks to get images to layout as I want using attribute selectors and such.

1 Like

I worry that if we start adding custom markup for particular presentational/layout options we’ll clutter documents with a lot of special symbols for layout that are hard to understand unless you already know the syntax. Remember Textile? That’s the direction CommonMark would be going in if we go down that route. But Markdown has a different philosophy from Textile; it is intended to be read as-is “without looking like it’s been marked up with tags or formatting instructions”.

If image dimensions and alignments are granted special syntax, syntax for colours and fonts will be requested next. I feel that that formatting the presentation of particular elements is a special case because (a) we can already do a lot of presentation formatting with rules, and (b) presentation should not necessarily be carried over between applications (mobile layouts in particular are unlikely to use the image alignment information). In cases where particular elements do require extra presentational information, we have raw HTML and the work going into the consistent attribute syntax extension to support these use cases. Because both raw HTML and consistent attribute syntax use plain English for attribute names, the syntax for these attributes is arguably more readable than the formatting symbols used by Textile (if you don’t already know the meaning of the symbols).


I would be even more conservative about this: Markdown is just a way we formalize some behaviors we already have. Back to the days when people send emails with plain text instead of HTML, they had been using similar syntax for years. I can still find some really old mails in mailing-list archives where people just refer to images with bare link, like

Hi everybody. I saw this logo somewhere and I think it *really rocks*:

I hope everyone would like it! I am myself **a big fan** of it.

To be frank, I think even the current syntax for image is not clear enough for anyone who isn’t already familiar to Markdown, not to mention any further “improvement” in this part of spec. Or at least, it should go to “extension” instead of in the spec, and don’t force every implementation to implement it before being able to claim that they support CommonMark.

1 Like

The image syntax is probably the least readable part of Markdown, although it is basically an extension of the link syntax. Images are essentially a type of link where external content is embedded rather than opened by the reader. So I think the same argument applies to the Markdown link syntax.

Since CommonMark is intended to be highly compatible with Markdown, images are unlikely to be changed or removed for the core, but I don’t see why a conforming parser couldn’t have a “lite mode” that skips images.

To warm up this topic: I still believe this is necessary, despite all the arguments that the CommonMark text should not concern itself with how it is being presented / rendered later. While I agree that specifying exact sizes or HTML attributes into CommonMark is not reasonable, I think that at least a way to express “this image should be scaled to X% of the text width” is IMO necessary to make images in CommonMark even remotely usable. Otherwise the rendering engine has an impossible task: It cannot automatically decide whether an image should be up/down-scaled or included 1:1 just by looking at the image and the output format.

  • 400:300
  • 400*300
  • 400x300
  • 400 300

0 voters