Automatically generated ID's in mdx generate ID's that start with numbers, making them invalid

[st3phhays]

Astro Info

Astro                    v4.8.2
Node                     v20.11.1
System                   macOS (x64)
Package Manager          yarn
Output                   static
Adapter                  none
Integrations             @astrojs/mdx
                         @astrojs/sitemap

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

If an ID exist in an .mdx file that starts with a number, the ID is generated with that number. It is known though, that ID's that start with numbers are invalid. This causes problems when navigating to those ID's and also with other front end libraries that use ID's to do things, like navigate through a TOC and highlight the active ID.

Take this heading:

6.1.2 (January 31, 2024)

This will generate an ID of #612-january-31-2024, which is invalid.

If you then try to use this ID in any form with JavaScript, you'll get an error like this:

Uncaught DOMException: Failed to execute 'querySelector' on 'Document': '#612-january-31-2024' is not a valid selector.

What's the expected result?

If a heading starts with a number, the ID should be generated by the first valid character instead. For example:

The heading 6.1.2 (January 31, 2024) should generate the ID january-31-2024.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/withastro-astro-bfhvze?file=src%2Fpages%2Fheadings.mdx

Participation

• I am willing to submit a pull request for this issue.

[martrapp]

Hi @st3phhays, yes this is annoying.

Astro uses github-slugger to generate ids for headings, nothing special there.
Actually, "612-..." is a valid id.

The error you see does not come from a malformed id, but from a malformed query.
It is quite uncomfortable to correctly escape an id that starts with a digit.

I see a couple of routes you can go:

1. You could escape manually by replacing the "6" with "\36 ": document.querySelector("#\\36 12-january-31-2024").
2. Or you can use a library like cssesc: document.querySelector(cssesc("612-january-31-2024"))
3. maybe a regex will do in your case: document.querySelector(id.replace(/^([0-9])/,"\\3$1 "))
4. Or you write a rehype/remark plugin that sets the ids of headings to your preferred value.
   Astro's mdx integration will then respect your choice and will not override it.

Edit: As you might have guessed from the above, changing the way Astro generates the ids is not an option here as it might break existing sites.

[st3phhays]

Hi @martrapp thanks a lot for the reply! Just want to add, I do absolutely love Astro. It has/will significantly improve our development experience.

On this...

Hi @st3phhays, yes this is annoying.

Astro uses github-slugger to generate ids for headings, nothing special there. Actually, "612-..." is a valid id.

An ID that starts with a number is invalid according to W3Schools.

I do understand though that changing this would probably break a lot of people. That's actually the reason I submitted this. I'm converting one of my sites over to use Astro and ran into this problem because my old ID's were changed to this instead of the way they were previously being generated. For reference, the processor we were using was Markdig.

It might be worth a note in the documentation on this as a simple heads up note perhaps. I can see this becoming a problem for users that are migrating over to Astro. I would be able to submit a PR for that if it sounds like a good idea.

For now, I have found a plugin to override the auto generated ID's to the ones they were at previously.

[martrapp]

Hi @st3phhays glad to hear that you have found a solution for your issue!
What plugin do you use now? That information might be helpful for others finding this thread!

[st3phhays]

I am using remark-custom-header-id.

I use it like this:

## 6.1.2 (January 31, 2024) \{#january-31-2024}

By adding this plugin, I was able to revert my IDs back to how Markdig was converting them.

[martrapp]

Thank you for sharing!

[martrapp]

After some further digging, I found this comment from delucis: withastro/roadmap#329 (comment)
Further down the page is also an entry for the plugin st3phhays was sharing.