With the syntax for images supporting titles in http://jgm.github.io/stmd/spec.html#images it would be great if the image tag would expand to a figure with caption like:
<figure>
<img src="/url" alt="alt text">
<figcaption>My caption</figcaption>
</figure>
This is a departure from what is currently out there but an often requested feature that should find its way into the spec somehow (even with an alternative syntax).
A title (tooltip) is different from a caption (though maybe they shouldnāt be). It would be great if there was a specific āfigure titleā that would convert any element into a figure.
####### My caption
Could produce:
<figure>
<img src="/url" alt="alt text" title="my tooltip">
<figcaption>My caption</figcaption>
</figure>
It could also support blockquotes, code blocks, lists, or whatever, though.
####### Code Example
```
// example call
Some.Example("code");
// return statement
if (isYes) return true;
```
Pandoc pioneered the automatic figure-ization of images that are alone in a paragraph. I have since come to think that it might have been better to have some separate syntax for indicating a figure. After all, itās not uncommon to want an image by itself, and with pandoc you have to do something special (e.g. put a nonbreaking space on the line) to avoid that. Also, some figures contain multiple images. So this is an area that needs some thought. The āfigure titleā idea is clever.
Iām all for the idea as an extension to commonmark, but I wouldnāt expect that behavior by default.
The author could leave off the title attribute in those cases. If no title is defined, no figure caption is rendered.
A worthwhile question to ask is: how common is it to add a title to an image but not also want to give that image a caption? There might be cases where the author wants to provide a tooltip without a caption. But it is discouraged to depend solely on the title attribute because this can cause accessibility concerns. Touch screen devices cannot display the title as a tooltip, for example. Markdown was created in a pre-iPhone world where this was less of an issue.
You could use a post-processing rule to group images together in a single figure if they are next to one another in the document (and contain titles), then generate a combined caption based on the titles of all three. There are multiple ways of doing this, so this would be outside of the spec. One example (based on the example in this HTML Doctor article) is:
produces:
<figure>
<img src="/kookaburra.jpg" alt="Kooaburra" title="Kookburra">
<img src="/pelican.jpg" alt="Pelican stood on the beach" title="Pelican">
<img src="/lorikeet.jpg" alt="Cheeky looking Rainbow Lorikeet" title="Rainbow Lorikeet">
<figcaption>From left to right, Kookburra, Pelican, and Rainbow Lorikeet.</figcaption>
</figure>
If you need a custom caption, a rule like this is not going to be suitable. But for a lot of cases it removes the need to remember additional syntax. It also removes to need to provide yet another way to describe the contents of the image. Do we need a standardised way of producing the shared caption? Iām not sure.
Captions are indeed somewhat like 7th-level headings, but why not simply special-case all-bold lines?
**My caption**
or below
**My caption**
There could be an optional explicit break (ā ā or \) between lines.
I have been prototyping an extension for figures using a block structure similar to fenced code block using the character sequence ^^^:
^^^
This is a text
> With a block quote and an 
^^^ My caption
is generating this:
<figure>
<p>This is a text</p>
<blockquote><p>With a block quote and an <img src="/url" alt="image" title="my title"><p>
</blockquote>
<figcaption>My caption</figcaption>
</figure>
The caption can be put on the opening block (on the first ^^^) or on the closing.
Did anything come out of this with regards to captions?
There is also a related topic discussing the introduction of captions for tables: Tables in pure Markdown It would be nice if a unified caption syntax would emerge from these two topics.
You can add captions with the content block syntax. I think this is the way to go for adding captions to images in CommonMark.
Markdig includes an extension with syntax for figures with captions:
^^^
This is a figure
^^^ This is a *caption*
.
<figure>
<p>This is a figure</p>
<figcaption>This is a <em>caption</em></figcaption>
</figure>