Linked Images are the achilles heel of Markdown and this has come up before but after running into this repeatedly over the past couple of months, I am convinced that there are many ways to simplify this. I propose the simplest one below:
// current notation
[](cats.html)
// simplified notation
(cats.html)
It’s succinct and least disruptive as it just tacks on a link at the end.
What does that render like in “classic” Markdown, though?
Since shortcut reference link syntax like
[cats run wild]
[cats run wild]: cats.html
should work, I wonder if the same with embedded media like images
![cats run wild]
[cats run wild]: cats.jpg
should, too, and what about images nested in links
[![cats run wild]]
[cats run wild]: cats.jpg
which at least in Maruku gives a self-linked image, or even links nested in images
![[cats run wild]]
[cats run wild]: cats.jpg
which could be useful with <figure> instead of <img> or <picture>.
Degrades fairly gracefully imo. The link is in round brackets adjacent to the image. If you have auto-linking turned on, the UX is a bit more improved since the link is clickable too.
Note: For some reason this editor on talk.commonmark.org doesn’t render it correctly if it finds []()(), even though try.commonmark.org works fine.
The idea is nice, but there’s a cost to introducing yet another incompatible change to classic Markdown. It’s not that much harder to write
(http%3A%2F%2Ftalk.commonmark.org%2F)%0A){kind=link}
[](url)
than it is to write
(url)
I agree the second is easier, but writing the first gives you something that will work on all Markdown implementations.
A plain web address (vulgo URL) is not a link! If you wanted graceful fallback, you would rather use angle brackets, although that only seems to work reliably with absolute addresses (that include the domain part):
%3Ccats.html%3E%0A*+!%5Bcats+run+wild%5D(cats.jpg)%3Chttp%3A%2F%2Fexample.com%2Fcats.html%3E%0A){kind=link}
<cats.html>
<http://example.com/cats.html>@Crissov I did clarify that auto-linking would need to be enabled but I do like your suggestion and improvement over the original much better than my own even though it introduces a new notation (angled brackets).
@jgm admittedly we are all a bit tone-deaf as to the usability of it for non-programmers. This issue actually came up a year back when addressing a newsroom of 30+ editor after they had been using Markdown for over a year. I am talking about political science, arts & humanities and business majors. They don’t take well to:
[![]()]()Is the use case for images with links really that common? I very rarely see it in the wild (compared to plain images), and in that case I think breaking compatibility with classic Markdown in this particular case may not be such a big deal. And given that, I’d strongly support a clean, readable and above all easily memorable format.
The syntax that all Markdown implementations already support, namely
[](url)
is more easily memorable than the suggested alternative, because to remember it you don’t need to know anything more than what you need anyway to form a link and to form an image. (You just put together those two bits of knowledge.) The suggested alternative would be yet another syntactic fact you have to memorize. I think that’s a strike against it, and even more so if these cases are not common.
I’d argue that there’s a difference between memorable and deducible. I certainly don’t know the syntax for image links by heart (although I do for images and for links). Instead, if I want to use one, I have to stop and reason about what it must (logically) be, given the component syntaxes. And even then, I might wonder whether the link wraps the image, or is contained in the image description, i.e. [](url) versus ](img.jpg), respectively.
If the syntax for image links can be said to be logical and unambiguous (and I might argue it is the former but not the latter) it would certainly be a point for the current syntax, but regardless of that, the memorability argument favors a cleaner syntax, IMO.
I can’t say I’m a big fan of this “simplified” notation; with links and images it’s clear which bit is which: square brackets have the text bit, and parentheses have the src/href bit. With this notation, there’s no way to differentiate the latter two. Quick, what does this do?
(cats-small.jpg)
Is that a big image linking to a small one, or the other way round? Sure, usually it’ll be simpler to parse than that, but what about writing them? I can see people getting them the wrong way round and then wondering why their image isn’t showing up.
Disclaimer: I use a fair few linked images so I’m comfortable with the current syntax. Just trying to think of it from the less technical user’s point of view.
Good point, @karaken12. FWIW, I believe Wikicreole (an attempt at a common markup for various wiki engines, not unline CommonMark) adapted Mediawiki’s transclusion syntax of {{...}} to embed images in a page. If it would be palatable for CommonMark to get inspiration from that convention, perhaps a syntax like ![Cats]{cats-big.jpg}(cats-small.jpg) would be less ambiguous. The only downside is that non-linked images would have to change to ![Cats]{cats-big.jpg}, which isn’t backward-compatible.
(Of course, with such a change, the ! would become redundant, and if we were willing to break compatibility with current image syntax anyway, we might as well remove it.)
An alternative is to change the link part instead, i.e. something like <cats-small.jpg> (this is what @Crissov suggested above).
Actually… why not making the transclusion sign ! valid both outside and inside the link? i.e.,  would be equivalent to [alt](!target-image.jpg). (By following this logic, we could even turn alt text into a visible caption in a simple and consistent manner, i.e. [!caption](!target-image.jpg).)
This would retain compatibility with current markup, and would allow a simplified image link markup that is both simple and unambiguous: [alt](!cats-big.jpg)(cats-small.jpg).
@waldyrious that simplifies things considerably and I’m all for it! It’s got a much better UX since the ordering of image/link isn’t needed anymore.
@jgm any thoughts on this?
Nobody is actually “willing to break compatibility with current image syntax” and ![Cats]{cats-big.jpg} or [alt](!target-image.jpg) would break it seriously. In a new language, there might be something to gain from a more UX-centric approach, but CM has to work with what MD left it.
That being said, overloading the arbitrary alt string could be a viable path for extension, but the URL is a more sensible beast. Please also note that some extended parsers already use curly braces to enclose attributes and metadata in several places including [](){} and [][]{}, but not []{}() or []{}[] as far as I know.
I know, that’s why I said “if we were willing”.
I can see {} breaking syntax, but if the positioning of the ! as a prefix to the url is made optional (which is what I suggested) then current syntax would still work perfectly. I fail to see how that amounts to seriously breaking compatibility.
The exclamation mark will be treated as part of the URL ⇒ 404.
I always assumed that the effort to maintain compatibility was more focused in ensuring that original markdown gets properly parsed by commonmark implementations, than ensuring that commonmark syntax works in old markdown parsers. After all, there are already incompatibilities in implementations, so this problem exists already, we wouldn’t be creating a new one. I for one believe it’s an acceptable compromise to gain a simpler image link syntax, but I understand that this point of view may not be shared by everyone.
There are enough stock contents (think about travis-ci badges and such) that any idea of changing this syntax sound just a gratuitous annoyance.
@lu_zero I’m not sure who you’re responding to, but just to be clear, I’ll quote two passages of my previous comments, emphasising the relevant parts: