Skip to content

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

Open

Description

@victrvondoom

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.

Activity

  1. added
    bugAn error in the Docusaurus core causing instability or issues with its execution
    status: needs triageThis issue has not been triaged by maintainers
    on Nov 15, 2026
  2. TbhVishal commented on Nov 19, 2026

    @TbhVishal

    In writeMarkdownHeadingId, code detection only checks if the line starts with three backticks, so tildes get skipped and shorter backticks inside longer fences exit early. Tracking the opening fence character and length across both passes fixes this without breaking existing heading IDs. I tested this locally with cases covering tildes and nested fences on fix/write-heading-ids-fenced-code if you want a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugAn error in the Docusaurus core causing instability or issues with its executionstatus: needs triageThis issue has not been triaged by maintainers

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions