Markdown tables with captions

[bryanwweber]

Is it possible to add Markdown tables with captions? I see several pages of documentation for figures that can be referenced, but those seem to require images. There is also a way to glue tabular output from code into Markdown, but I have a table already formatted in Markdown, and I want to add a caption. Thanks!

[choldgraf]

Hmmm - can you try wrapping your table in a ```{table} block like so:

```{table} my caption
<table here>
```

[chrisjsewell]

I'm happy to add a "best practice" if we get a consensus here, but personally I think they all have their use cases and the pros/cons are already outlined in the documentation 😬.

[bryanwweber]

So there's three cases where I can't tell what the difference is from reading the docs, other than personal preference about styling:

```{image} ../images/fun-fish.png
:alt: fishy
:class: bg-primary
:width: 200px
:align: center
```

```{figure} ../images/C-3PO_droid.png
---
height: 150px
name: directive-fig
---
Here is my figure caption!
```

and

:::{figure,myclass} markdown-fig
<img src="../images/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">

This is a caption in **Markdown**!
:::

My guess at the difference is that the first syntax is only allowed for images, since images don't have captions. The third may be preferable for Jupyter Notebooks, since the Notebook will display the <img> tag while you're working. But that's more-or-less a guess and reading between the lines in the docs, since there's no direct comparison of those three formats.

For code blocks, you can also use the :tag: syntax, so I'm not sure if that's also allowed for figures?

Maybe what I'm looking for is a "cheat sheet" or something - if I'm in the middle of writing my book, I just want a quick reference to remind myself "oh, right, that's how I add and reference a figure".

[bryanwweber]

By the way, I'm happy to help put something like what I'm suggesting together, if you think it makes sense!

[chrisjsewell]

yeh no thanks, I don't want to come across too negative, but I do want to impress that there can be distinct use cases for all of these, and can also depend on the users background; coming from restructedtext or Markdown.
The "markdown-friendly" syntaxes are also quite new functionality (in response to user requests) and so required a bit of time to get feedback before imposing them as "best paractice".

There is already a https://jupyterbook.org/reference/cheatsheet.html, so happy to accept PRs to improve it 👍

[bryanwweber]

Ah! That cheat sheet is exactly what I was looking for! Thank you for the link, it helps to read the TOC 🤦