Figures

[jgm]

We need a general way of producing a figure with a caption and label.

Pandoc's "implicit figures" are too limiting. Figures can include multiple images, and also non-image content like code.

[uvtc]

Do you mean supporting a feature where you can write something like, "see figure 4", and that will render as a link to an image (as in ![figure 4](figure-4.png)?

[jgm]

No, this is about creating the figure itself: an environment that may contain one or more images, or perhaps other things, plus a caption and a label that can be the target of references.

[uvtc]

Would the current way to get something similar to this be to add the figure as an image, like this:

![figure 4](figure-4.png){#fig-4}

and then link to it with "[see figure 4](#fig-4)"?

[jgm]

In pandoc's markdown that will produce a figure (implicit_figures extension), but we haven't implemented that here. I think I'd prefer to have something more explicit for generating figures.

[bpj]

What about

!!!label
![alt text](path/to/image.png)
![other alt text](path/to/other.png)

:: Short caption on one line

Long caption which may have multiple lines/paragraphs.
!!!

And if you need a grid you simply use table structure (pipe or list).

[uvtc]

Ok, I understand. Thanks.

I wonder if there's a way to re-use the div syntax for this, like

::: figure
foo ...
:::

Similar to the list tables idea #27 .

[uvtc]

Actually, if I were "delimiter-shopping" for a punctuation character to use for figures, it would be hard to beat & --- I mean, it looks just like a figure that a figure skater might make. Stealing @bpj 's example:

&&& label
![alt text](path/to/image.png)
![other alt text](path/to/other.png)

Short caption on one line

Long caption which may have multiple
lines/paragraphs.
&&&

[bpj]

The point of using the exclamation point is that it is already used to differentiate inline images from links.

[uvtc]

Yeah, I see that, though I don't think the !!! looks good.

[uvtc]

If --- is free, this looks good:

--- figure 4
![alt text](path/to/image.png)
![other alt text](path/to/other.png)

Short caption on one line

Long caption which may have multiple
lines/paragraphs.
---

I don't know how you could enhance that to support figures containing subfigures, as in "figure 4(a), 4(b), etc." Maybe using a definition list inside the figure block, e.g.:

--- figure 4
: figure 4(a)

  ![alt text](path/to/figure-4-a.png)

  Short caption for fig 4(a), on one line

  Long caption which may have multiple
lines/paragraphs.

: figure 4(b)

  ![alt text](path/to/figure-4-b.png)

  Short caption for fig 4(b), on one line

  Long caption which may have multiple
lines/paragraphs.
---

[Omikhleia]

Whatever solution is considered for figures and subfigures, captions should probably be generalized with a consistent syntax across blocks where they are appropriate:

• Tables (we do have the ^ caption syntax currently...)
• Code blocks (-> captioned listings)
• Figures (-> captioned blocks of images or whatnots)
• Quotes (-> captioned quotes)
• Others?

See also #28