[v2] Heading custom ID extended syntax support

Hey there 👋 . First off, thanks so much for all the hard work on v2! I’m really excited to start using it.

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 our old docs site written in drupal over to Gatsby/MDX. We have lots and lots of pages within our docs site (5000+) and many of them link to each other. Because we want to maintain backwards compatibility with the existing site, we want to maintain the existing id attributes on headings so that our links don’t break.

Problem

In v1, it appears that the extended syntax for custom heading IDs worked correctly when using the gatsby-remark-autolink-headers. I suspect this was a result of how the AST was parsed in v1.

Take the following example:

# A heading {#custom-id}

This would result in the AST 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 v2 (which is AWESOME), the same node is parsed into the following:

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

Because of this, unfortunately it causes issues when compiling to into JSX because it results in an expression like the following:

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

Alternatives

I’m not really sure what I expect the behavior to be here. I can understand why the parser would parse this heading expression as it does. Writing the heading as a regular JSX header works as intended:

// Works
<h1 id="custom-id">A heading</h1> 

However this is a bit of a bummer as we lose some readability because of this.

Would it be possible to support the custom ID syntax on headings to support this use case?

[wooorm]

I don’t think it should be changed here, as it’s by design: {...} is an expression here. For example, {1 + 1} could output 2.

[wooorm]

I’m going to close this as it is an intended change: to move closer to JSX.

I don’t see why that gatsby plugin does work that isn‘t in its readme, anyway: MDX has remark and rehype plugins, where you can do custom IDs in code, and if you want them in content, well, there are other remark plugins that allow that. Or you can use JSX in MDX?