Figure and Table Captions

[tompkins-ct]

Problem

mdbook currently does not support captioning objects (listings, tables, figures, etc.) and captioning provides a mechanisms to cross-reference text and objects.

Proposed Solution

Provide some syntax for captioning items in markdown.

Pandoc markdown provides the following solutions

• implicit_figures
• table_captions

pandoc table caption uses the following:

any line starting with : or table: immediately proceeding or following a table

the table caption style could potentially be used to wrap code blocks (listings) as well or extend to be the common method for all captions (as long as the to-be-captioned item immediately proceeds or follows it).

HTML supports <caption> and <figcaption> tags which can be used to translate whatever markdown syntax into HTML.

Notes

<figcaption> can be added in the markdown files manually without much more effort than normal images by wrapping the block in <figure> tags. The markdown image syntax does not simplify overall document very much.

<figure>
<img src="image.png" alt="Architecture Breakdown Viewpoint"/>
<figcaption> This is an image </figcaption>
</figure>

Table captions have to be embedded in the <table> tags:

<table>
<caption> Table caption </caption>
---lots of HTML table syntax>---
</table>

[hiSandog]

The scope would be easier to review if the first version defined a small acceptance contract for Figure and Table Captions. I would call out the default behavior, the migration/backwards-compatibility story, and one or two cases that are intentionally out of scope so the implementation does not grow beyond the original request.