Skip to content

fix(markdown): footnote ids are unique per answer - #159

Merged
aayushbtw merged 1 commit into
ui-sdkfrom
fix/markdown-footnote-ids
Nov 21, 2026
Merged

aayushbtw merged 1 commit into
ui-sdkfrom
fix/markdown-footnote-ids

Conversation

@aayushbtw

Copy link
Copy Markdown
Owner

Why

Goal: fix every bug on ui-sdk that can be fixed on our side before it lands on main.

When two answers on one page both use [^1], every footnote link and back-link jumps into the first answer. @tanstack/markdown 1.0.0 hardcodes the ids user-content-fn-*, user-content-fnref-* and footnote-label (dist/react.js:57-60, 142, 167). It has no prefix option. A document transform could rename the footnote ids, but footnote-label is a fixed string, so it can't reach that one.

What

  • Markdown takes a useId prefix and passes it down through context. The a, h2 and li overrides add it to the footnote ref, the backref, the Footnotes heading and the footnote items. useId gives the same value on the server and the client, so the prerendered HTML hydrates as is.
  • In-page links stay in the tab, and the Footnotes heading stays visually hidden. That keeps fix(markdown): footnote links stay in the tab and the Footnotes heading stays hidden #141's behavior.
  • The docs demo answer gets a footnote, so the Markdown page shows two blocks that both use [^1].

Verification

  • New test two answers that both use [^1] keep their footnotes apart. It checks that the 6 ids are unique, that each ref's href resolves to an li inside its own block, that the backref returns to that ref, and that aria-describedby names its own block's heading. It fails on the start SHA (1 failed, 5 passed) and passes with the fix.
  • vpr check, vpr build and vpr test pass on the head (67 files, 544 passed, 1 expected fail).
  • Playwright ran on the static build at /docs/components/markdown, light and dark, with no console errors. Clicking ref 1 in block 2 goes to #_R_5eb6aq_user-content-fn-1. That target is inside block 2, not block 1, and the page scrolls it to the top. The backref goes back to block 2's ref. The page stays in the tab, and the heading is still 1px wide. The ids in the server HTML match the ids after hydration.

Tradeoffs

  • A consumer who replaces a, h2 or li through components also replaces the prefixing. That's the same contract as the existing overrides.
  • Ids now read _R_xxx_user-content-fn-1, so an outside link to #user-content-fn-1 stops working. There are no users yet.

Tracker

  • C-footnotes: footnote ids are prefixed per Markdown root with useId. Fixed here.
  • Open, not fixed here: heading slug ids (such as monthly-active-users) still repeat across blocks. It's the same bug class, but in heading ids.
  • Open, site-level: there is no scroll-padding-top, so any hash target, footnotes in block 1 included, lands under the 64px sticky header.

…its own footnote

@tanstack/markdown 1.0.0 hardcodes user-content-fn-*, user-content-fnref-*
and footnote-label, so two answers using [^1] on one page share ids and
every ref and backref jumps into the first. Each Markdown root now
prefixes those ids with useId, which matches between server and client.
The docs demo gains a footnote so the page shows two blocks using [^1].
@aayushbtw

Copy link
Copy Markdown
Owner Author

Verifier: PASS+NOTES at 3608755. check, build, test (544 pass) re-run on an export; browser lane on static build: block 2 ref and backref stay in block 2, server ids match hydrated, 1 of 84 prerendered pages changed (footnote ids only). Notes, not blocking: heading slug ids still repeat across blocks; no scroll-padding-top under the sticky header; markdown.md 'Links open in a new tab' is stale since #141. Queued as a follow-up.

@aayushbtw
aayushbtw merged commit c7d3b3f into ui-sdk Nov 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant