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 https://github.com/jgm/djot/issues/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

[rauschma]

FWIW: Given how flexible Djot’s syntax already is, it may not be necessary to introduce new syntax – e.g.:

[Figure](#fig:diagram){!float} visualizes how everything is connected.

{!float for="Figure" #fig:diagram}
:::
![](img/venn-diagram.svg){width="277.164" height="176.5"}
---
Visual explanation.
:::

[Table](#tbl:summary){!float} contains a summary.

{!float for="Table" #tbl:summary}
:::
| Output | Vector | Bitmap |
|--------|--------|--------|
| HTML   | `.svg` | `.jpg` |
| LaTeX  | `.pdf` | `.jpg` |
---
Brief summary.
:::

Notes:

• !float is a command (which I use in my Markdown dialect), it could also be the class .float. Commands work much like classes but have a separate namespace and don’t produce output – unless there is a plugin/filter.