Document that fig-scap inside a figure div

[roaldarbol]

Description

I was trying for a while to figure out how to use a short caption inside a figure div, and it's not entirely obvious from the documentation, so I thought I'd outline it here, and maybe it can be added to the docs.

Short captions for figures are supported for basic Markdown figures and from codeblocks, but that they're supported is not obvious from inside a figure div.

So according to the documentation, these work:

```{python}
#| fig-cap: "Long caption"
#| fig-scap: "Short caption"

```

![Long Caption](figure.png){fig-scap='Short caption'}

And this is how it works for a figure div:

:::{#fig-myfig fig-scap="Short caption"}
![](figure.png)

Long caption goes here.
:::

What's not obvious is that inserting a fig-cap too breaks it (correctly! Presumably as it's being provided inside the div. Just for reference, this it what then breaks:

:::{#fig-myfig fig-cap="Long caption" fig-scap="Short caption"}
![](figure.png)

Description goes here.
:::

End of the tale. 😊

[cscheid]

Thanks for getting this discussion started. We need to:

• issue errors (or linting warnings) when there's conflicting caption configurations
• design a syntax for short captions that allows them to be specified in the same way as long captions. This is necessary so that shortcodes and Markdown are supported in short captions.
• document/implement short caption behavior across formats

I'm tracking this on #11304.

[roaldarbol]

Brilliant! It did make me wonder about whether short captions for tables was a thing, but I guess they’re still on the drawing board ☺️

[cscheid]

They are, kind of. Short captions currently exist only in that they are used by LaTeX in the "list of figures" "list of tables" feature, and are not easy/uniform to create or access.

[roaldarbol]

Ah, I see.😊
As far as I can tell, they do not seem to work for table divs like so (discussed in #11067):

:::{#tbl-mytable tbl-scap="Short caption"}
```{=html}
{{< include "Tables/my_table.html" >}}
```

Long caption
:::

EDIT: This is in a LaTeX rendered PDF where the above fig-scap works.