Support autogenerated heading IDs as aliases/fallbacks when explicit IDs are defined

[chideraao]

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:

1. VS Code suggests an autocomplete link that doesn't actually work in the rendered site.
2. 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.

[fresh3nough]

i can take a shot at this one today