Skip to content

Add new fragment directive guidance - #621

Open
tabatkins wants to merge 6 commits into
w3ctag:mainfrom
tabatkins:fragments
Open

tabatkins wants to merge 6 commits into
w3ctag:mainfrom
tabatkins:fragments

Conversation

@tabatkins

@tabatkins tabatkins commented Aug 19, 2026 •

Copy link
Copy Markdown
Contributor

I'm proposing a new guidance, to always use "fragment directives" when defining new things that go in the fragment of a URL.

In CSS Link Params I initally copied SVG's fragment directives when defining how to pass link Params directly in a URL, but it was pointed out in w3c/csswg-drafts#14235 that I should instead be relying on fragment directives, as defined by the Scroll To Text Fragment spec.

The fragment directive concept was designed with careful attention to compat and how it should be exposed to various DOM APIs, and is generally a much better structure than the general fragment, which is unstructured and heavily used by authors, which makes it hard to impose any structure.

Text fragments are the only currently-shipping feature using fragment directives, but link params will be the second, and we should encourage further use of this feature instead of letting people unknowingly repeat the legacy mistakes of SVG and Media Fragments.


Preview | Diff

Comment thread index.bs Resolved
@marcoscaceres

Copy link
Copy Markdown
Contributor

@tabatkins, do you know what the plan is to move this stuff to, presumedly, the URL spec and HTML?

Comment thread index.bs Resolved
Comment thread index.bs Resolved
Comment thread index.bs Resolved

@marcoscaceres marcoscaceres left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is great, @tabatkins! Thank you. Some suggestions.

tabatkins and others added 3 commits September 14, 2026 13:41
Co-authored-by: Dan Clark <daniec@microsoft.com>
Co-authored-by: Marcos Cáceres <marcos@marcosc.com>
@jyasskin

Copy link
Copy Markdown
Member

@tabatkins, do you know what the plan is to move this stuff to, presumedly, the URL spec and HTML?

whatwg/html#8282 has the plan to merge into HTML and links to a PR.

Comment thread index.bs Resolved

@jyasskin jyasskin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@tabatkins Having looked into this, I'm not sure that CSS link params are actually doing the right thing for SVG, whose MIME type says it uses the XPointer style for fragments. We ought to be consistent for params-in-links, so maybe we need to say that SVG also allows its XPointer stuff to live after the fragment-directive :~: introduction...

Comment thread index.bs Resolved
Comment thread index.bs Resolved
Comment thread index.bs Resolved
Comment thread index.bs Resolved
dandclark and others added 3 commits November 16, 2026 14:37
Co-authored-by: Jeffrey Yasskin <jyasskin@gmail.com>
Co-authored-by: Jeffrey Yasskin <jyasskin@gmail.com>
Co-authored-by: Jeffrey Yasskin <jyasskin@gmail.com>

@jyasskin jyasskin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I've filed w3c/csswg-drafts#14830 to get (the CSS folks to file a bug to get) SVG to recognize fragment directives. I think the advice here is good to go.

Comment thread index.bs Resolved
Comment thread index.bs Resolved
@tabatkins

Copy link
Copy Markdown
Contributor Author

This looks great to me!

@jyasskin jyasskin self-assigned this Nov 19, 2026

This branch has not been deployed

No deployments
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.

6 participants