Linked Images - Confusing Syntax

Extensions
1

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.

2 Likes
2

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.

4 Likes
3

I agree linked images are Perl level confusing.

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

2 Likes
4

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"
[source_link]: http://example.com/you-can-see-source-here.html

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


[1]: 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!

FWIW.

5

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:

#1

// 0. current implementation
[![caption](src)](link)

// 1. order-based
!(caption)[src][link]

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

#2

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. 
![caption][src]
[text][link]
![caption][src][link]

#3

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.

6

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

7

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.

8

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)

9

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

10

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.