Use image alt text as a caption

[eschalkargans]

Context

I was reading the documentation regarding images because I wanted to add captions to my images: Image captions (documentation)

In order to add a caption to an image, one has to use HTML.

Description

Use the Alt text of the image, already available in the markdown syntax, to generate automatically the caption.

A feature flag could be set up so that users can choose whether or not they want the caption to be displayed.

Here is a concrete example:

![My awesome image](../assets/images/awesome.png)

The image would be rendered, wrapped with a <figure> and a <figcaption>My awesome image </figcaption> describing it.

Related links

• Requesting a change
• Image captions (documentation)

Use Cases

Use case from an author's perspective: It is a very common thing to want to name figures we use in a document

Use case from an user's perspective: An inserted image would be described once, without having to describe both an alt text and a caption (DRY)

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting. This functionality is already provided by markdown_captions. Configure mkdocs.yml as follows:

markdown_extensions:
  - markdown_captions

[joapuiib]

I think this configuration could be mentioned in Image Captions Section.

[squidfunk]

Thanks for the suggestion! We're only linking Markdown extensions for which we provide official support – we can't provide support for all of them. I hope that's understandable from a maintainer's perspective.

[joapuiib]

From Image Captions Section in the docs:

Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to use the Markdown in HTML extension with literal figure and figcaption tags.

PyMdown Extensions has just launched Caption extension, that allows to easily write captions.

Since this extension is supported by default, maybe the documentation could show a basic example on how to write captions:

![Image title](https://dummyimage.com/600x400/){ width="300" }
/// caption
Image caption
///

[squidfunk]

Sure, PR welcome. If you plan to go ahead, please also add the respective section in our configuration guide.