Support for image dimensions

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.

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

There’s two approaches that can be used here, general and particular.

For scaling the images generally, the content management system can include a post-processing rule regarding how the dimensions HTML is generated. This approach is adquate, maybe even preferred, for a number of systems where you’d want the system (instead of the author) to take care of how the images are scaled automatically (e.g. making all of the images in a news article or forum topic the same width).

For scaling particular images to particular dimensions, I agree some kind of additional syntax would be required. Since people are wanting to add other particular attributes to page elements in Markdown, this is a good fit for the consistent attribute syntax extension, rather than creating a seperate syntax just for image dimensions. Different scaling attributes/techniques could be supported via different attributes too.

I don’t believe support for image dimensions needs to be added to the core spec, since the general approach + HTML for particulars has worked fine up until now and the already large CommonMark core is focused on the features found in the original Markdown spec. So I propose we move this discussion to “Extensions”.

Honestly I wish what we do here was just spec cause it works great in practice




1 Like


I’d like to bring this subject on the table as it seems important and not decided yet.

The basic reason we need image dimensions flags is that a standard cannot rely on definition only but has to include resolution too, and both at the same time if possible.

The world is going high dpi, (or retina for fruit people), and the quality of a document should not rely on a design based on one only (old) type of screen device.

The same way you are pleased to have vector quality for your fonts, why do you want to force the image item type to be stuck at a basic level of quality ?

Example: I want to include a screenshot in my markdown to show how to use a GUI, I don’t want to have to reduce the quality of my GUI screenshot to 640x480 where it becomes unreadable just so it can fit into my markdown page, a simple example like this should be enough to prove the current limitation of the image markdown support.

Ps: The dimension feature should not rely on percentage because the layout needs to be source quality/definition agnostic.

here my humble syntax proposal:

![](/img.ext | 640x480) for setting width / height at the same time
![](/img.ext | 640x) for setting the width and auto-ratio for height
![](/img.ext | x480) for setting the height and auto-ratio for width

Thanks for reading me, I hope it can help and make things moving the right way.

1 Like

Is this still under discussion? This thread is linked from all over the internet (e.g. StackExchange) as the canon of image dimensions in markdown, but it doesn’t seem there’s been any movement in a couple years.

FWIW, I would love to have this option, with really any syntax.

This is unlikely to land any time soon in CommonMark without any extensions. But if you’re looking for an implementation, see e.g.