How do I stop Gatsby from wrapping Markdown images in <p> tags and hiding image captions?

Question

I’ve set up my site with the Gatsby starter blog template.

In my Markdown files, I use normal Markdown notation for inserting images with captions. For some reason—I assume it’s because of the gatsby-remark-images plugin et. al.—my images are automatically wrapped in <p> tags along with a bunch of other things I don’t understand.

This is the source in Safari:

<p>
<span class="gatsby-resp-image-wrapper" style="position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 630px; ">
<span class="gatsby-resp-image-background-image" style="padding-bottom: 75.31645569620254%; position: relative; bottom: 0px; left: 0px; background-image: url(&quot;data:image/jpeg;base64,/9j/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2P/wgARCAAPABQDASIAAhEBAxEB/8QAGAAAAgMAAAAAAAAAAAAAAAAAAAQBAgP/xAAVAQEBAAAAAAAAAAAAAAAAAAAAAf/aAAwDAQACEAMQAAABrpLFiI6H/8QAGRAAAwEBAQAAAAAAAAAAAAAAAAIDEwES/9oACAEBAAEFApUZV9NwWlEXChgYH//EABQRAQAAAAAAAAAAAAAAAAAAABD/2gAIAQMBAT8BP//EABQRAQAAAAAAAAAAAAAAAAAAABD/2gAIAQIBAT8BP//EAB4QAAIBAwUAAAAAAAAAAAAAAAABIQISMREiMlFh/9oACAEBAAY/AraXA92ey3VR6Q0cjJ//xAAfEAACAQIHAAAAAAAAAAAAAAAAAREhMUFRYXGBkaH/2gAIAQEAAT8hRKV2NBJU8xWRKzQFhvcc7+DXM//aAAwDAQACAAMAAAAQeP8A/8QAFhEBAQEAAAAAAAAAAAAAAAAAABEB/9oACAEDAQE/EKuP/8QAFhEBAQEAAAAAAAAAAAAAAAAAAQAR/9oACAECAQE/EAsb/8QAHBABAQACAgMAAAAAAAAAAAAAAREAITFRYXHB/9oACAEBAAE/ELQqcxD8xRBQRCaSnWANCBRPWIa6O6WmNO5Cb9fPjJeJ9on3P//Z&quot;); background-size: cover; display: block; transition: opacity 0.5s 0.5s; opacity: 0;"></span><img class="gatsby-resp-image-image" alt="Tøyen barnehage er en av fem kommunale barnehager i Nittedal. <cite>Nittedal kommune</cite>" title="Tøyen barnehage er en av fem kommunale barnehager i Nittedal. <cite>Nittedal kommune</cite>" src="/static/6c4a2d09ef212e5058dc411fbe918fb9/828fb/toyen-barnehage-2.jpg" srcset="/static/6c4a2d09ef212e5058dc411fbe918fb9/ff44c/toyen-barnehage-2.jpg 158w,
/static/6c4a2d09ef212e5058dc411fbe918fb9/a6688/toyen-barnehage-2.jpg 315w,
/static/6c4a2d09ef212e5058dc411fbe918fb9/828fb/toyen-barnehage-2.jpg 630w,
/static/6c4a2d09ef212e5058dc411fbe918fb9/0ede0/toyen-barnehage-2.jpg 945w,
/static/6c4a2d09ef212e5058dc411fbe918fb9/6a068/toyen-barnehage-2.jpg 960w" sizes="(max-width: 630px) 100vw, 630px" style="width: 100%; height: 100%; margin: 0px; vertical-align: middle; position: absolute; top: 0px; left: 0px; opacity: 1; transition: opacity 0.5s; color: inherit; box-shadow: white 0px 0px 0px 400px inset;" loading="lazy" decoding="async">
</span>
</p>

I’ve tried researching this. I understand it’s a bunch of features for loading images more efficiently and hence better and so on.

The fancy features are fine, but I need my image to be wrapped in a figure with a figcaption—not a <p> tag. (A div with a p for caption would of course also be fine.)

How do I achieve this?

Answer 1

Since it's a default configuration and there's no options in the gatsby-remark-images that to customize the output, you'll need to add a custom component rendering. Luckily, there's a plugin that makes this configuration far easy: gatsby-remark-figure-caption. Just add it inside the gatsby-transformer-remark:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-figure-caption`,
        },
      ],
    },
  },
]

And will output:

<figure>
  <img src="path-to-image.jpg">
  <figcaption>image with description</figcaption>
</figure>