write heading ids modifies headings inside tilde and longer fenced code blocks
@VaibhavBajpaij ci sta già lavorando.
Dal 15/11/2026.
Valutazione
- Difficoltà
- 2/5
- Tempo stimato
- 1-3 ore
- Idoneità per principianti
- 78/100
- Tipo di issue
- Bug
- Chiarezza
- Specificata chiaramente
- Stato di attività
- Attiva
- Stack tecnologico
- typescript
- Ambito
- documentation
Direzione di ricerca
Inizia da packages/docusaurus-utils/src/markdownHeadingIdUtils.ts ed esamina writeMarkdownHeadingId() e il passaggio iniziale di prenotazione degli ID. Riproduci il problema con l’esempio dell’issue delimitato da tilde, quindi esegui il comando documentato pnpm exec docusaurus write-heading-ids --syntax classic. Il lavoro è completato quando le intestazioni all’interno dei blocchi delimitati restano invariate e non influiscono sugli ID assegnati alle intestazioni effettive.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Have you read the Contributing Guidelines on issues?
- I have read the Contributing Guidelines on issues.
Prerequisites
- I'm using the latest version of Docusaurus.
- I have tried the
npm run clearoryarn clearcommand. - I have tried
rm -rf node_modules yarn.lock package-lock.jsonand re-installing packages. - I have tried creating a repro with https://new.docusaurus.io.
- I have read the console error message carefully (if applicable).
Description
The docusaurus write-heading-ids command incorrectly processes Markdown headings inside certain fenced code blocks.
In packages/docusaurus-utils/src/markdownHeadingIdUtils.ts, the writeMarkdownHeadingId() function currently detects code blocks using:
if (line.startsWith('```')) {
inCode = !inCode;
return line;
}
This only recognizes backtick fences and does not track their opening length.
As a result:
Tilde fences (~~~) are not recognized.
A shorter backtick sequence inside a longer fenced block can incorrectly terminate code block detection.
Headings inside these examples can receive generated IDs.
Existing IDs inside code examples can also affect slug generation because the initial reservation pass examines every line.
Reproducible demo
No response
Steps to reproduce
Create a Markdown file inside the docs directory:
Fenced code reproduction
## Reusable API
Reusable API
Run:
pnpm exec docusaurus write-heading-ids --syntax classic
Expected behavior
Only actual Markdown headings outside fenced code blocks should receive IDs.
Expected output:
Fenced code reproduction
## Reusable API
Reusable API {#reusable-api}
Actual behavior
The current implementation can also modify the heading inside the tilde fenced block:
Fenced code reproduction
## Reusable API {#reusable-api}
Reusable API {#reusable-api-1}
The code example should remain unchanged and should not affect the slug generated for the real heading.
The same issue can occur with longer backtick fences containing shorter backtick sequences.
Your environment
Operating System: Microsoft Windows 11, version 26H2, OS Build 26300.9974
Browser: Google Chrome 157.0.0.0
Node.js: v26.13.1 LTS
Package Manager: pnpm 12.21.0
Self-service
- I'd be willing to fix this bug myself.
- Lingua principale
- TypeScript
- Stelle
- 66.6k
- Fork
- 10.1k
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di facebook/docusaurus
-
Auto-generated description drops the text between two colons in the first paragraphForse già presa @0z5a l’ha presa 6 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
facebook/docusaurus#13059 ·
-
Playground cards have inconsistent heightsForse già presa @anishagrawal25 l’ha presa 31 giorni fa. Apertabug status: needs triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
facebook/docusaurus#12739 · 1 commento ·
-
Page title drops a trailing # from the heading, e.g. # Learn C# becomes "Learn C" (AI-assisted)Forse già presa @saiyam-jain-dev l’ha presa 19 giorni fa. Apertabug status: needs triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
facebook/docusaurus#12644 · 1 commento ·
-
Firefox clips descenders in documentation sidebar labels on WindowsForse già presa @xusnitdinov l’ha presa 126 giorni fa. Apertabug status: needs triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
facebook/docusaurus#12299 ·
-
domain: dependencies proposal
Difficoltà 5/5 Più di una settimana Idoneità per principianti 25/100
facebook/docusaurus#13080 ·
Tutte le issue di facebook/docusaurus
Issue simili
-
The manager preset saves launch definitions without the required file and digest pairForse già presa Una pull request collegata a questa issue è aperta o già unita. Apertabug
Difficoltà 2/5 1-3 ore Idoneità per principianti 80/100
I maintainer di solito rispondono entro 1 giorno