Support MDX v2's new AST for custom heading IDs

[jerelmiller]

Hey there 👋

I have an interesting situation where we need to be able to define custom IDs for headings generated from markdown. I am part of a team in the process of moving an old docs site written in drupal over to Gatsby/MDX. We have lots and lots of pages within the docs site (5000+) and many of them link to each other. Because we want to maintain backwards compatibility with the existing site, we need to maintain the existing id attribute on headings so that our links don't break between pages.

Problem

In MDX v1, the extended syntax for custom heading IDs works correctly with the gatsby-remark-autolink-headers plugin due to how the AST was generated.

Take the following example:

## A heading {#custom-id}

This would result in the MDXAST looking something like the following:

{
  type: 'heading',
  depth: 2,
  children: [
    {
      type: 'text',
      value: 'A heading {#custom-id}',
    }
  ],
}

Note here how the custom ID was part of the value of the text child. It appears the gatsby-remark-autolink-headers plugin expects this as part of the AST so that it can update the h tag with the custom ID.

With the much more robust parsing in the upcoming changes to MDX v2, the same node is parsed into the following MDXAST:

{
  type: 'heading',
  depth: 2,
  children: [
    {
      type: 'text',
      value:
        'A heading',
    },
    {
      type: 'mdxSpanExpression',
      value: '#custom-id',
    },
  ],
}

Because of this, it unfortunately causes issues with the gatsby-remark-autolink-headers plugin when compiling to into JSX because it results in an expression like the following:

<h1>{`A heading`}
{#test}</h1>

My question is: Is there a plan to continue to support custom IDs on headers within the plugin for MDX v2?

I've also cross-posted this issue over in mdx-js/mdx#1279. I'm not sure whether this behavior belongs best in the parsing/AST generation phase, or whether this is something the gatsby-remark-autolink-headers plugin should handle itself. At the very least, I wanted to throw this information out there to see what makes the most sense and get a discussion going.

Thanks so much for the excellent work on Gatsby and the ecosystem. Our team has been HUGELY successful because of it and absolutely love working daily in the ecosystem. Thanks for all the hard work!

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 60 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here.
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[jerelmiller]

Is this something being considered for the upcoming updates to MDX v2?

[LekoArts]

To keep things organized I'll close this in favor of an umbrella issue. Please repost your findings here: #25068

Thanks!