fix: dedupe heading slugs to prevent duplicate ids on doc pages

[sanketssc]

Fixes #1281

When a module exposes a class and a type with the same name (e.g. the Spring class and the legacy interface Spring<T> in svelte/motion), the generator emits two ## Spring H2s. The renderer assigned both the same id="Spring", which:

• produced invalid HTML (duplicate ids on the page),
• broke in-page anchors (/docs/svelte/svelte-motion#Spring only ever reached the first heading, the legacy interface section was unreachable),
• broke the "On this page" TOC (clicking either Spring link highlighted both at once).

This PR dedupes heading slugs per page. The first occurrence keeps the bare slug, subsequent occurrences get -1, -2, … suffixes. The same dedupe is applied in two places so they stay in sync:

• packages/site-kit/src/lib/markdown/renderer.ts — heading id + permalink href in rendered HTML.
• packages/site-kit/src/lib/server/content/index.ts — sections/subsections metadata that powers OnThisPage.svelte.

Result on /docs/svelte/svelte-motion: first Spring (class) stays at #Spring, legacy interface section becomes #Spring-1. Each TOC entry now activates independently.

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time.
• Prefix your PR title with feat:, fix:, chore:, or docs:.
• This message body should clearly illustrate what problems it solves.

[vercel]

@sanketssc is attempting to deploy a commit to the Svelte Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

This PR addresses duplicate heading id values on docs pages by de-duplicating generated heading slugs per page, keeping rendered heading anchors and the “On this page” TOC metadata aligned.

Changes:

• Add per-page slug de-duping when generating sections/subsections metadata for the docs TOC.
• Add per-page slug de-duping when rendering heading id attributes and permalink hrefs in markdown output.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/site-kit/src/lib/server/content/index.ts	De-dupes sections and subsections slugs so TOC entries remain unique per page.
packages/site-kit/src/lib/markdown/renderer.ts	De-dupes rendered heading ids / permalinks to avoid duplicate IDs in generated HTML.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
svelte-dev	Ready	Preview	May 26, 2026 7:24pm

[teemingc]

While this works, I wonder if we should be looking for a more deterministic way to create the ids. We wouldn't want it to be order dependent because that makes it brittle to future changes

[sanketssc]

fair point this does make it order dependent and if future changes happen it will point to wrong thing.

few things could be worked on maintaining internal ids for slugs but thats currently not being done
another thing that can be done is slug generation based on content hashing but that also has consequences if content change then ids change as well

If we want automatic slug generations which is present currently i think current one work in most of the cases
it also takes into account parent section so having this collisions is i believe very rare scenarios

additionally i am open to suggestions if there are any regarding this