Next.js Hydration error with inline tags

[mfix-stripe]

Discussed in #185

^{Originally posted by khash August 26, 2022}
Using NextJS

I'm trying to build a "hint" tag, similar to this from https://stripe.com/docs/connect/collect-then-transfer-guide

This component, should be usable within any text (like in code) and accept anything as the content of the popover (links, images, etc).

I think this is a simple use case and below is how I've reproduced it. I've removed all code that does that for simplicity in the question:

// hint.markdoc.js
export default {
  attributes: {
    caption: { type: String },
  },
  render: ({ caption, children }) => <div><span>{caption}</span><span>{children}</span></div>,
};

// test.md
This is a {% hint caption="hint"%}generated by the tag{% /hint %} as an example

This throws a NextJS Hydration error https://nextjs.org/docs/messages/react-hydration-error.

However the same code with the following works fine:

This is a 
{% hint caption="hint"%}
generated by the tag
{% /hint %}
as an example

[mfix-stripe]

@khash just dug into this more, and this issue isn't specific to Markdoc or Next.js, but is actually just this generic React issue: https://stackoverflow.com/questions/41928567/div-cannot-appear-as-a-descendant-of-p, which stems from the W3 HTML spec: https://www.w3.org/TR/html401/struct/text.html#h-9.3.1

The P element represents a paragraph. It cannot contain block-level elements (including P itself).

This is why when you return a div, the warning shows up, but when you return a span, everything is fine.

I think we can close this issue, but let me know if you agree.

[khash]

Thank you very much @mfix-stripe for looking into this and your answer.

For anyone who lands here, trying to use React Tooltip, you can avoid this problem by setting the tag property to span:

<Tooltip
      tag="span"      
      html={(
        <span>
          {children}
        </span>
      )}>
      <span>
        {caption}
      </span>
</Tooltip>

[mfix-stripe]

@khash going to close out this issue—if we run into other similar problems, let's open up a new issue. Thanks for sharing!