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:
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]: http://i.stack.imgur.com/abcde.jpg "Descriptive :hover title goes here"
The syntax for an image linked to itself is even easier, of course:
: http://i.stack.imgur.com/abcde.jpg "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
/) 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.
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:
[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.