facebook / facebook/docusaurus

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

Open
#11,691 1 comment 1 reaction 0 assignees View on GitHub
proposal status: needs triage
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:
Image

---

Image

### Self-service

- [ ] I'd be willing to do some initial work on this proposal myself.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.