write heading ids modifies headings inside tilde and longer fenced code blocks

Aperta Adatta ai principianti
#13,061 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

@VaibhavBajpaij ci sta già lavorando.

Dal 15/11/2026.

  • #13062 di @VaibhavBajpaij — aperta
  • #13068 di @iwang-1 — aperta

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

bug status: needs triage
Have you read the Contributing Guidelines on issues?
Prerequisites
  • I'm using the latest version of Docusaurus.
  • I have tried the npm run clear or yarn clear command.
  • I have tried rm -rf node_modules yarn.lock package-lock.json and 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

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di facebook/docusaurus

Tutte le issue di facebook/docusaurus

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.