Skip to content

fix: give repeated headings unique ids - #2609

Merged
vtushar06 merged 2 commits into
json-schema-org:mainfrom
drishtyraghav0001:fix/duplicate-heading-ids
Nov 13, 2026
Merged

vtushar06 merged 2 commits into
json-schema-org:mainfrom
drishtyraghav0001:fix/duplicate-heading-ids

Conversation

@drishtyraghav0001

@drishtyraghav0001 drishtyraghav0001 commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What kind of change does this PR introduce?

Bugfix

Issue Number:

Screenshots/videos:

n/a, ids only. on the built non_json_data page the two Example headings are now #example and #example-1, clicking the second one goes to the second one and only that one gets the ¶

If relevant, did you update the documentation?

no

Summary

when a page has the same heading twice they both got the same id, so the second Example on non_json_data jumped back to the first one and both lit up. now repeated headings get -1, -2 ... ids like GitHub does. the first one keeps its id so existing links don't move.

it's done in a small lib/dedupeHeadingIds.ts that runs on the markdown before rendering and adds a [#id] fragment to the repeats, so the headings and the table of contents pick up the same id. it reuses slugifyMarkdownHeadline for the base slug, so it doesn't touch that file and doesn't clash with #2579. it skips code blocks, headings that already have a [#id], h5/h6, and headings that slug to nothing. the TOC also stops showing the raw [#id] text now.

compared every heading id and TOC link in the static build before and after. only 5 ids changed, all of them the second copy of a repeated heading (non_json_data example, glossary see-also, and 3 on the lexical/dynamic scopes blog post). no visible text changed on any page and nothing in the repo linked to those.

added cypress/components/dedupeHeadingIds.cy.tsx (18 tests, 14 of them fail on main). lint, typecheck, format check, build and test:coverage:all pass locally.

Does this PR introduce a breaking change?

no

Checklist

Pages with the same heading twice (like the two Example sections on
non_json_data) rendered the same id, so clicking the second one jumped to
the first and both got highlighted. Repeated headings now get -1, -2 ...
ids, the first one keeps its id so existing links still work.

Fixes json-schema-org#2343
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
website ✅ Ready (View Log) Visit Preview 03a934a

@codecov

codecov Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (25be3b2) to head (03a934a).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff            @@
##              main     #2609   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           31        31           
  Lines          737       737           
  Branches       229       229           
=========================================
  Hits           737       737           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@kunalverma2512

Copy link
Copy Markdown
Contributor

Hi @drishtyraghav0001 👋

Nice work on #2343! The way you handled the duplicate IDs is really clean.

I was checking the red Codecov check. Your actual code is 100% covered, but it looks like <StyledMarkdown /> is pulling in other existing files like StyledMarkdownBlock that don't have tests yet.

Do you think mocking those extra components or testing with a small custom wrapper would keep them out and make the check green? What do you think?

… coverage

Render the repeated-heading tests with markdown-to-jsx and the Headline components instead of mounting StyledMarkdown and TableOfContentMarkdown, which brought StyledMarkdownBlock, TabsGroup and the rest of the TOC into coverage without tests. The tab group case is checked on dedupeHeadingIds directly, and the TOC fragment stripping moves to lib/dedupeHeadingIds as stripHeadingFragments.

Signed-off-by: Drishty Raghav <273601396+drishtyraghav0001@users.noreply.github.com>
@drishtyraghav0001

Copy link
Copy Markdown
Contributor Author

thanks @kunalverma2512, good catch! switched the tests to a small wrapper so they don't pull in StyledMarkdownBlock, coverage is back to 100% in 03a934a. @jagpreetrahi could you take a look when you get a chance?

@vtushar06 vtushar06 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vtushar06
vtushar06 merged commit 7b7b58b into json-schema-org:main Nov 13, 2026
9 checks passed
@github-project-automation github-project-automation Bot moved this from Ready to review to Done in PR - Triage Group Nov 13, 2026

This branch was successfully deployed

1 active deployment
Preview — 03a934a3 Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

🐛 Bug: HClicking on Example section header scrolls to the first Example section and highlights multiple headers

3 participants