Linked Images - Confusing Syntax

Linked images are the achilles heel of the CommonMark spec. It is the only thing that routinely trips up the dozens of writers who use our platform implementation for CommonMark. I would guess that for this reason alone, editors seldom link images.


For the novice writer, that is hard to decipher and anything but intuitive.

I am not sure there is any good way to demystify this syntax but would love to hear if there is something I have overlooked or if there is a proposal or a more usable solution in the works.


Maybe this just confirms your point, but you’ve given an example of an image with a link in its “image description,” not a linked image (i.e., a link with an image in its “link text”). A linked image would be:

[![image description](/imageurl)](/linkurl)

Granted, this isn’t beautiful, but it’s the application of two general-purpose rules which are easy enough to remember.


I agree linked images are Perl level confusing.

Average users don’t have much occasion to link images, though.


I take it that means that StackOverflow/Exchange users are above- (I assume) average? I do this regularly on my main SE hangout: the image “on-site” adjusts to the column size, the link to source allows interested readers to see it in context, or a link to the image itself to facilitates viewing at full size. (This is usually for manuscript images where detail matters.)

My own preferred format for image + source is:

[imgLink]: "Descriptive :hover title goes here"

The syntax for an image linked to itself is even easier, of course:

[1]: "Descriptive :hover title goes here"

And I agree with @jgm. It’s simple enough, especially if you start with the (“inner”) image link, then add the (“outer”) source (or full-sized) link. Besides - hard to know what a better alternative would be!


I suppose that’s a conversation that might be worth having, it might lead to improvements. I haven’t contemplated this much but off-the-cuff I can propose a few alternatives:


// 0. current implementation

// 1. order-based

// 1a. shorthand for !(caption)[src][src] -- link to self


Or taking a bigger leap, what if square brackets became synonymous to round brackets. This would require sniffing the link text (should start with http, #, ?, /) or similar but it would rid the problem of round-vs-square brackets, which is frankly, quite annoying. Semantically I know that [] is for grouping text and () follows grammar convention of auxiliary text but I am not sure if those semantics have much use here.

// 2. 


Taking an even bigger leap forward could be to make the ! optional and inferring an image based on the extension. Since this is optional, for an image source without an extension, the ! would provide a fallback. Again this can be done in a backward compatible fashion while still reducing the operands from three !, (), [] to just one []. Usability-wise, this would be a big win. This is what it would look like:

// 3
[caption][src.png]    // inserts image (inferred via extension)
[text][link]          // links text
[caption][src][link]  // links src with caption

// 3a. linking to an image (leverages alternative 1)
[text][src][src]   // inserts image. links image
[text][src][]      // shorthand for above

I have seen other alternatives in Wikis such as [foo bar link] or [[foo bar link]] where the last word is a link. The minor downside is that the link cannot have spaces since the implementation requires word boundaries but I still prefer [text][link] for clarity.

I think it wouldn’t hurt if images automatically linked to the source (full-size), unless an explicit link is provided.

There would be no opt-out mechanism for this so that alone would make this feature opinionated, which probably isn’t that good.

I would personally find it quite annoying if all images were hyperlinked–especially if the full-res version is already being used, making the linked image redundant. For a better UX, modal dialogs and zoom-icons (for zoomable images at ~70% threshold) is probably a better approach.

I agree that if the full versions are already being displayed, the “thumbnails” shouldn’t link to the full-size versions; but as for modal dialogs, I can’t imagine CommonMark having a say on that kind of UX for clients. A link would probably be the lowest common denominator, and the output could then be progressively enhanced to whatever extent the particular site/app desires (from simply opening the links in a new tab/window by default, to a full-on modal display and similar interfaces)

Just pointing out that most “lightbox” implementations like what you described would require images to be links anyways.

I meant this should be done independently of Markdown. It should probably not be a Markdown feature since this is (1) behaviour and (2) platform dependent.