Today I learned that Markdown images support a title attribute that creates hover tooltips—and with a rehype plugin, you can transform these titles into captions.

Most people are familiar with the standard Markdown image syntax:

![Alt Text](/path/to/image.jpg)

Here, Alt Text serves as alternative text for accessibility—it appears when images fail to load and helps screen readers describe the image.

The path can be:

• A relative path to a local file: ./images/photo.jpg
• An absolute path: /assets/photo.jpg
• A remote URL: https://example.com/photo.jpg

You can add a title attribute as a second parameter:

![Alt Text](/path/to/img.jpg "image title")

This creates a tooltip that appears when users hover over the image. You can also transform these titles into captions.

Markdown doesn’t natively support image captions, which leaves you with some awkward workarounds:

Option 1: Add text below the image using HTML tags:

![](image.png)
<sub><em>This is a caption for the image.</em></sub>

Option 2: Use raw HTML with <figure> elements:

<figure>
  <img src="image.png" alt="Example Image" width="200" height="200">
  <figcaption>This is a caption for the image.</figcaption>
</figure>

Both approaches work, but they break the flow of writing in plain Markdown.

If you’re writing a blog with a static site generator (like Astro, Next.js, or Gatsby), you can use a rehype plugin ¹ that transforms your image titles into captions.

With this plugin, you write clean Markdown:

![A descriptive alt text](./img.jpg "The caption")

And it becomes:

<figure class="rehype-figure-title">
  <img src="./img.jpg" alt="A descriptive alt text" />
  <figcaption>The caption</figcaption>
</figure>