Support custom header IDs in Markdown

[sindresorhus]

Many Markdown parsers support an extension that allows explicitly setting the header ID using the {#faq} syntax:

### Frequently Asked Questions {#faq}

It would be useful if Astro could support this too. It's common to need to set stable IDs that will not change even if the text changes.

Currently, we have to do this, which is ugly:

<a id="faq"></a>
### Frequently Asked Questions

More info:

• https://www.markdownguide.org/extended-syntax/#heading-ids
• https://kramdown.gettalong.org/syntax.html#specifying-a-header-id

---

Update: I made my own plugin for this as one of the existing ones did too much and the other one stopped working. https://github.com/sindresorhus/remark-custom-header-id

[delucis]

This is possible to enable using https://github.com/imcuttle/remark-heading-id

Here’s a minimal example project using this remark plugin: https://stackblitz.com/edit/github-b6cdfq?file=astro.config.mjs

[thdoan]

FYI this topic is now covered in the docs:

https://docs.astro.build/en/guides/markdown-content/#markdown-plugins

[okadurin]

Unfortunately adding custom rehype plugins won't change the getHeadings() output since the array is filled out only once when rehypeHeadingIds from @astrojs/markdown-remark is run

[fwextensions]

Ignore thdoan's link above. I followed it, thinking the docs would have the latest way of doing things, but instead got sent on a wild goose chase. What the docs mention isn't relevant to what @sindresorhus was asking about, but @delucis's link is.

In my case, the remark-custom-heading-id library crashed on the the Markdown document I tried, but remark-heading-id worked just fine (even if it doesn't provide any type info).

[rkyoku]

remark-custom-heading-id crashes for me too, but with remark-heading-id I also get an error:

[ERROR] Could not parse expression with acorn || unexpected token

My Markdown:

## Test {#test}

Not sure what I did wrong. How did you include/setup the plugin?

I went with:

remarkPlugins: [remarkHeaderId],

Will update here if I can get it to work.

Best,

[stereobooster]

try this ## Test \{#test\}

[sindresorhus]

FYI, I ended up making my own plugin for this: https://github.com/sindresorhus/remark-custom-header-id

[rkyoku]

@stereobooster it works by escaping the curly braces, weird! Still, thank you kindly :)