Ability to use images with captions in Markdown

[arun-mani-j]

Body

Summary

The images in Markdown ![alt](src "title") are converted to <img> in HTML. However, converting them to <figure> with <figcaption> without manually setting up plugins pipeline would be useful.

Background & Motivation

I'm migrating my website from Hugo to Astro thanks to Astro's simplicity and web native ecosystem. Hugo has a shortcode called figure.

As an example, with this in Markdown:

{{< figure
  src="/images/examples/zion-national-park.jpg"
  alt="A photograph of Zion National Park"
  link="https://www.nps.gov/zion/index.htm"
  caption="Zion National Park"
  class="ma0 w-75"
>}}

Hugo renders this HTML:

<figure class="ma0 w-75">
  <a href="https://www.nps.gov/zion/index.htm">
    <img 
      src="/images/examples/zion-national-park.jpg" 
      alt="A photograph of Zion National Park"
    >
  </a>
  <figcaption>
    <p>Zion National Park</p>
  </figcaption>
</figure>

Though I do not like using framework specific workarounds, this feature was indeed useful.

To achieve a similar result in Astro, we have to use either MDX with a custom Figure component or modify the AST through plugins or use surrounding text.

1. The problem with MDX is that the file no longer stays as a normal Markdown file. The usage of component based solution would make the file more tied to Astro.
2. AST modification with external plugins like https://github.com/Microflash/rehype-figure would need adequate care to ensure that Asto's image processing pipeline is not disturbed.
3. Surrounding text is the least resistive workaround but it does not provide us with a figure element.

Providing a built-in feature in Astro to convert Markdown images to figure could provide a middle ground for users who don't want to move to MDX or tweak AST.

Goals

• An optional configuration element that enables this feature.
• When enabled, it converts ![alt](src "title") to figure than img.

Problems

The solution is obviously not straight forward. We need to choose which property (alt or title) would be used as caption. The rehype-figure (which also acknowledges this escape-hatch) uses alt as caption.

May be, with such problems, it may not be easy for Astro to provide a clean solution. In that case, I think the RFC discussion can be used to provide workarounds and make it easy for others in future to learn why this request was turned down.

Thanks for Astro.

[delucis]

Hi @arun-mani-j! I think it’s unlikely we’d add this is a built-in option. Especially given solutions like rehype-figure exist and can be used within Astro. In general we aim to make sure the APIs are available to provide extensions (for example by supporting Markdown extensions via plugins like rehype-figure) and only build in extremely common requirements.

[arun-mani-j]

I see, thanks for the reply. That stance is reasonable :).