: Caption for All: A Unified Syntax for Captions and figCaptions

[anasram]

Usually, after a table in a markdown file, pandoc converts a line like this:

: Foo bar

to <caption>.

I wonder if it's a good idea to use this syntax as a unified syntax to generate <caption> and <figcaption> too, not only for images, but also for video, audio, and even <pre> elements.

![Image alt](path/to/image.png "Image title")

: Image caption

![Video link title](path/to/video.mp4 "Video title")

: Video caption

![Audio link title](path/to/audio.mp3 "Audio title")

: Audio caption

\```
some code...
\```

: Code caption

The HTML result:

<figure>
<img src="path/to/image.png" title="Image title" alt="Image alt" />
<figcaption>Image caption</figcaption>
</figure>

<figure>
<video src="path/to/video.mp4" title="Video title" controls="">
<a href="path/to/video.mp4">Video link title</a></video>
<figcaption>Video caption</figcaption>
</figure>

<figure>
<audio src="path/to/audio.mp3" title="Audio title" controls="">
<a href="path/to/audio.mp3">Audio link title</a></audio>
<figcaption>Audio caption</figcaption>
</figure>

<figure>
<pre><code>some code...</code></pre>
<figcaption>Code caption</figcaption>
</figure>

In this case, the meaning of the text before the URL will be changed. It will mean an alt="" attribute, not a <figcaption> element.

This could be a dramatic development for markdown syntax, but I think it's worth it.

[jgm]

Indeed, now that the Figure element has been added to the AST, we might explore a new Markdown syntax for figures to replace or supplement implicit_figures. See #3177 for some ideas. This caption syntax could be part of that, perhaps.

Since the Figure element can now contain arbitrary block-level content, a Figure could contain a code block, a video, or anything else.

This would also help with #8752.

[anasram]

I also wonder now if there's a way to mention figures, tables, and even headings, dynamically like [@some-cite]:

See [#foo-bar-table] and [#foo-bar-figure] in [#foo-bar] section.

instead of:

See Table 2 and Figure 3 in section 2.1.

where the foo-bar-figure looks as follows:

![Image alt](path/to/image.png "Image title")

: Image caption {#foo-bar-figure}

In HTML:

<figure id="foo-bar-figure">
<img src="path/to/image.png" title="Image title" alt="Image alt" />
<figcaption>Image caption</figcaption>
</figure>

i.e., the id attribute should be for the <figure>/<table> elements, not for the <figcaption>/<caption> elements.

[gavinsimpson]

Just to add my tuppence to the discussion; I feel it is a mistake to use the alt text as a caption with implicit_figures as alt text and captions serve two entirely different purposes (at least in a HTML context). Having a way to specify a caption and alt text (for accessibility reasons) without breaking everyone else's documents that relied on the alt-text-as-caption behaviour would be very much appreciated.