Syntax for custom id of headings

[danon]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

I like generating dynamic ids for my headings to build tables of content, that's so cool.

I'm missing a valid MDX syntax to include an id for a heading.

Solution

But I miss a feature where I could add a custom id for a heading. Many Markdown parsers support this syntax for custom id:

## Heading hello {#custom-id}

which can be then rendered into

<h2 id="custom-id">Heading hello</h2>

Alternatives

Currently, you could achieve something similar by adding a link to a heading

## [Heading hello](#custom-id)

but that's really an id of a link, not a heading. And it adds a link where it's not actually necessary. It's just a somewhat compliant syntax, to include any id in any form, with the implication of it being parsed with the intention of the link id being turned into the heading id.

Another alternative could be just using HTML all the time, instead of .mdx

<h2 id="custom-id">Heading</h2>

but if I wanted to do that, I would just write React, not .mdx.

[ChristianMurphy]

This isn't part of CommonMark, GFM, or JSX so I'm not sure it really fits in MDX core.
Support can be added through a plugin, there is a plugin (in need of updating to support the latest verion of remark/mdx) which can support the custom heading syntax you are interested in https://github.com/imcuttle/remark-heading-id

[danon]

@ChristianMurphy It doesn't have to be this syntax ## Heading {#id} syntax exactly.

It can be anything that allows to mention the id for a heading. Maybe there already is something like that, but I just don't know it?

[ChristianMurphy]

Without any plugin, JSX can be used

<h2 id="custom-id">Heading hello</h2>

Or if you prefer the custom {#heading} syntax, it looks like there is a newer plugin with better MDX support https://github.com/Eyas/md-heading-id (source: #1953 (comment))

[wooorm]

Or <a name="custom-id"></a> in front of the heading btw. That also works in normal markdown, and on GitHub