Support autogenerated heading IDs as aliases/fallbacks when explicit IDs are defined #11691
Description
Have you read the Contributing Guidelines on issues?
- I have read the Contributing Guidelines on issues.
Motivation
Use Case
Explicit heading IDs in Docusaurus (## Heading Title {#custom-id}) help to ensure link stability even if the heading text changes. However, most Markdown IDE tooling (such as VS Code) generates link suggestions based on the slugified heading text (#heading-title).
Currently, when an explicit ID is provided, the autogenerated ID is discarded. This creates a "broken" experience where:
- VS Code suggests an autocomplete link that doesn't actually work in the rendered site.
- Developers have to manually remember or look up custom IDs instead of relying on fast IDE autocompletion.
Proposed Solution
I propose that Docusaurus allow the autogenerated ID to exist as a fallback or alias for the explicit ID.
Relevant images
The following images show the use of subnet-validator explicit ID and the suggested heading by VSCode:
Self-service
- I'd be willing to do some initial work on this proposal myself.