gatsby-remark-images nests figure in p

[schwigri]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report directly related to Gatsby. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Description

When using gatsby-remark-images along with the showCaptions feature, it creates a figure element which is nested inside a p, which is not valid HTML.

This issue has been reported before: #16239

The latest comment on that issue said to open a new bug if this still exists in Gatsby 4, so I have created minimal reproduction from gatsby-starter-blog and setting showCaptions to true.

Reproduction Link

https://github.com/schwigri/gatsby-starter-blog

Steps to Reproduce

1. npm run develop or npm run build && npm run serve
2. See the HTML for the post "Hello World"
3. The image with the eggs will be a figure element that is nested inside a p element.
4. Please view the raw HTML itself; modern browser realizes that this is incorrect and moves the figure outside of the paragraph, leaving an empty paragraph so the dev tools will show it like <p></p><figure />

Expected Result

<figure />

Actual Result

<p>
    <figure />
</p>

Environment

System:
    OS: Linux 5.18 Arch Linux
    CPU: (8) x64 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 16.16.0 - ~/.nvm/versions/node/v16.16.0/bin/node
    npm: 8.11.0 - ~/.nvm/versions/node/v16.16.0/bin/npm
  Languages:
    Python: 3.10.5 - /usr/bin/python
  Browsers:
    Firefox: 102.0.1
  npmPackages:
    gatsby: ^4.19.2 => 4.19.2 
    gatsby-plugin-feed: ^4.19.0 => 4.19.0 
    gatsby-plugin-gatsby-cloud: ^4.19.0 => 4.19.0 
    gatsby-plugin-google-analytics: ^4.19.0 => 4.19.0 
    gatsby-plugin-image: ^2.19.0 => 2.19.0 
    gatsby-plugin-manifest: ^4.19.0 => 4.19.0 
    gatsby-plugin-offline: ^5.19.0 => 5.19.0 
    gatsby-plugin-react-helmet: ^5.19.0 => 5.19.0 
    gatsby-plugin-sharp: ^4.19.0 => 4.19.0 
    gatsby-remark-copy-linked-files: ^5.19.0 => 5.19.0 
    gatsby-remark-images: ^6.19.0 => 6.19.0 
    gatsby-remark-prismjs: ^6.19.0 => 6.19.0 
    gatsby-remark-responsive-iframe: ^5.19.0 => 5.19.0 
    gatsby-remark-smartypants: ^5.19.0 => 5.19.0 
    gatsby-source-filesystem: ^4.19.0 => 4.19.0 
    gatsby-transformer-remark: ^5.19.0 => 5.19.0 
    gatsby-transformer-sharp: ^4.19.0 => 4.19.0

Config Flags

No response

[LekoArts]

At the moment this is expected behavior as also the images are wrapped with <p> tags. That's the normal behavior of rehype at the moment. Something like https://github.com/remarkjs/remark-unwrap-images needs to be implemented to gatsby-remark-images to apply both for the normal image and captions.

Since this is a breaking change (as people might rely on the nesting for styling) we can't do this change just yet.

[rdrnt]

Any updates on this?

[LekoArts]

I fixed this for gatsby-plugin-mdx, however with gatsby-transformer-remark I don't see the behavior you're describing (with current next versions). I get:

<div>
<p>Hello World!</p>
<p></p>
<figure class="gatsby-resp-image-figure" style="">
    <span class="gatsby-resp-image-wrapper" style="position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 512px; ">
      <a class="gatsby-resp-image-link" href="/static/53aa06cf17e4239d0dba6ffd09854e02/bc282/icon.png" style="display: block" target="_blank" rel="noopener">
    <span class="gatsby-resp-image-background-image" style="padding-bottom: 100%; position: relative; bottom: 0px; left: 0px; background-image: url(URL); background-size: cover; display: block; transition: opacity 0.5s ease 0.5s; opacity: 0;"></span>
  <img class="gatsby-resp-image-image" alt="This is a lengthy alt description" title="This is a lengthy alt description" src="/static/53aa06cf17e4239d0dba6ffd09854e02/bc282/icon.png" srcset="/static/53aa06cf17e4239d0dba6ffd09854e02/85b06/icon.png 256w,
/static/53aa06cf17e4239d0dba6ffd09854e02/bc282/icon.png 512w" sizes="(max-width: 512px) 100vw, 512px" style="width: 100%; height: 100%; margin: 0px; vertical-align: middle; position: absolute; top: 0px; left: 0px; opacity: 1; transition: opacity 0.5s ease 0s; color: inherit; box-shadow: white 0px 0px 0px 400px inset;" loading="lazy" decoding="async">
  </a>
    </span>
    <figcaption class="gatsby-resp-image-figcaption">This is a lengthy alt description</figcaption>
  </figure>
<p></p>
<p>Some more text.</p>
</div>