facebook / facebook/docusaurus
Support autogenerated heading IDs as aliases/fallbacks when explicit IDs are defined
- Dominant language
- TypeScript
- Stars
- 66.2k
- Forks
- 10k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 52
Description
### Have you read the Contributing Guidelines on issues?
- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#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.
Contributor guide
Assessment
This issue has not been assessed yet.