A fragmention is an extension to URL syntax that links and cites a phrase within a document by using a URL fragment consisting of the phrase itself, including whitespace.
- This is a Living Specification yet mature enough to encourage implementations and feedback.
- Latest Published Version
- discussion on #indieweb-dev (on Libera IRC)
- Kevin Marks
- Other contributors: revision history
- Per CC0, to the extent possible under law, the editor(s) have waived all copyright and related or neighboring rights to this work. In addition, as of 2022-07-01, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.
- 1 Behavior
- 2 Use Cases
- 3 Syntax
- 4 Processing Model
- 5 Open Source
- 6 IndieWeb Examples
- 7 Silo Examples
- 8 UI for Fragmention-generation
- 9 Challenges
- 9.1 rejected double-hash URL style
- 9.2 Sensitivity
- 9.3 Icon proposals
- 9.4 Using Fragmentions in a TOC
- 9.5 What if the linked-to text occurs more than once?
- 9.6 What if the desired fragment isn't text?
- 9.7 Generating fragmention from a selection across multiple elements
- 9.8 Should an element selected by fragmentioned URL be focussed?
- 10 Related work
- 11 Brainstorming
- 12 Articles
- 13 See Also
Fragmentions find the first matching phrase in a document and focus its closest surrounding element. The match is determined by the case-sensitive string following the # The closest surrounding element may be a span, paragraph, heading, button, input, or any other container.
If you click on a link to read a specific part of a web page, finding the right part of the document can be fiddly, especially on a phone. You end up scrolling aimlessly, or trying to use the hidden "find in page" feature.
To scroll stright to the right bit of a web page, we need to link to any text on the page, not just places where the author put in an
name. The simplest way to do this is make the browser try a bit harder when given a fragment to follow your intent.
While you can use
<blockquote> to quote a text directly, linking to it in context is important too, and being able to link to the mentioned text directly is a big advantage.
Linking to a passage robustly
Web pages do get reformatted and relaid out. By linking to the actual text of the page, rather than the structural elements, the link is more robust, and the linked-to text is available in the fragment itself.
By combining a fragment link with webmention you can direct your comment to be alongside part of the linked-to page, rather than the whole of it.
As an HTML id must not contain any whitespace, we can be sure that a fragment that includes space characters will not conflict with any existing element ID's. A fragmention MUST include at least one space character.
- Use %20 (instead of + ) for space characters in your fragmention.
- Fragmentions are decoded before search, which means + plus signs can be interpreted as spaces and thus MUST be escaped (%2B) if you mean to refer to a literal "+" character like "a+b" (a%2Bb).
- If your fragmention text contains a literal "#" e.g. "Use my #hashtag", you MUST URL-escape it, e.g. "Use+my+%23hashtag".
To find a potential indicated element given a string fragment, run these steps:
We propose amending this to add a 3rd step after the existing id and name searching so it reads as follows:
To find a potential indicated element given a string fragment, run these steps:
- tree order.
Search through the plain text content of the document tree for contiguous text that matches the fragment with white space collapsing. If there is a match, return the outer element that contains the text completely.
- client-side script and
- Chrome extension
- idno adds support thanks to Ben Werdmüller
- A wordpress plugin to add fragmentions by Christiaan Conover
- A drupal plugin by Drew Robinson
- another wordpress plugin by Luís R.
- Disquotational is a web service (and bookmarklet) for making fragmention links by Darryl McAdams
- fragmention-target is a Web Component for displaying fragmention links - the paragraph and the highlighted text.
Implementations on IndieWeb sites.
- initial discussion and follow-up explaining the idea more generally
- Jonathan's example page
- Kevin's original page with Jonathan's script added
- Aaron's site - note the custom CSS for the highlighted paragraph
- sayit.mysociety.org, thanks to Matthew Somerville. Shakespeare, government inquiries, and any other transcripts - more information
- Panayotis Vryonis' personal blog
- this wiki itself! Thanks Aaron
- Styled with a tiny CSS animation by Vasilis van Gemert
- Kartik Prabhu supports fragmention on all pages on kartikprabhu.com using CSS to highlight the referred paragraph in gray. Also, selecting text gives a popup link with the corresponding fragmention using fragmentioner.
- Tantek Çelik supports fragmentions on all tantek.com post permalinks since 2014-07-26 using the
fragmention.min.jsopen source polyfill, and CSS that highlights the element containing the fragmention in yellow and fades to very light yellow.
- Ben's Site - simple use of the open source polyfill, included on every page.
- Bret Comnes supports fragmentions and animated background highlighting on the upcoming base jekyll boilerplate site. example
- Chris Aldrich supports fragmentions on http://boffosocko.com since 7/21/15. For comparison it also supports Hypothes.is annotations and highlights as of 4/3/16. On 2018-01-23 he also added support for Kartik Prabhu's fragmentioner to make highlighting portions of his site simpler for users.
- Kevin's blogger blog by adding the fragmention JS to the template
- Instapaper Support(original post is unavailable as of 2016-12-21; Archived link at archive.org)
- creates fragmention URLs for highlights and POSSEs them to twitter, tumblr, facebook etc.
- Adds fragmention support to the Instapaper browser plugins for Chrome and Safari
- Google's "Open Source" website supports fragmentions as of 2017-03-30
UI for Fragmention-generation
Examples of user-interfaces for generating a fragmention from some selected text
While most find the idea of fragmentions delightful, there are differing ideas on how they should work. We ask contributors to justify feature requests with concrete real world examples, as tests in the wild may reveal best practices. Otherwise, any of these challenges could be appended with, “So, uh, what do you think?”
rejected double-hash URL style
The first draft of this used double hash anchors
## and escaped the spaces in the fragment with
+ signs. Experimentation shows that this causes problems with URL parsing in some cases as double-hash is an invalid URL, and plus signs in fragments are not escaped as spaces, only in the query string.
As id's and anchors are not able to contain spaces, this extra markup is unnecessary.
The URL spec doesn't define fragments to contain hash signs, so links like <a href="##foo"> may fail validation, or be misparsed by strict URL parsers. if this is an issue, we may need to switch to #*
- For future reference. Valid characters as per URL spec are: ALPHA / DIGIT / "-" / "." / "_" / "~" / "%" HEXDIG HEXDIG / "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" / ":" / "@" / "/" / "?" -Sandeep.io 20:58, 23 April 2014 (PDT)
On the other hand, HTML5 id's can contain #. So browsers may interpret links like <a href="##foo"> with two meanings - the question is if IDs starting with # occur on the web.
The initial feedback is that few people concern themselves with hash fragment validation, and even less would (at least, knowingly) use them in this way.
Further thought: as HTML5 ids can contain any text except a space character, any fragment with a space in CANNOT refer to an id, so could be treated as a fragmention. So any fragmention of more than one word may not even need the ##.
- The problem with this approach is that auto-linkers and URLs in other context (like plain text) don't know where the URL ends. -Sandeep.io 20:56, 23 April 2014 (PDT)
Firefox drops the first # on redirect: For instance http://kartikprabhu.com/static/demo/fragmention.html##was+still redirects to an https version which should be https://kartikprabhu.com/static/demo/fragmention.html##was+still but Firefox drops one of the # to give https://kartikprabhu.com/static/demo/fragmention.html#was+still . Strangely enough http://kartikprabhu.com/static/demo/fragmention.html###was+still fixes this (Firefox only drops one #) and http://kartikprabhu.com/static/demo/fragmention.html#%23was+still also seems to work.
After trying it both ways, collapsing white space works better, as it is very hard to generate invisible escaped characters accurately.
Matching case is strict, but makes it easier to target specific text. Ignoring case is cavalier, but makes it easier to target anything.
The initial feedback is conflicting. Some expected fuzzy matching. Others expected specific matching. Most agreed that it depends on your specific use-cases, which are sorely lacking in most of the annotations discussions. Fuzzy matching could be seen as a further fallback strategy if direct matching fails.
(Todo: upload images instead of linking.)
- This proposed icon combines highlighting with linking and is thus a classic over-literal design by an engineer. Graphic designers very much encouraged to come up with something better.
- Part-highlighted link icon
- Quotation mark + link icon (rough draft - may try fusing per suggestion)
Using Fragmentions in a TOC
Because Fragmentions by default link to the first occurrence of a phrase, it's not possible to use them in a table of contents on the same page if the table of contents appears above the things you're linking to. This is because the fragmentions would then link to themselves.
Proposed solution to reference the nth occurrence of a phrase:
What if the desired fragment isn't text?
Say you wanted to link to a particular photo on an album page, or a video inside a blog post.
While they fail the "human-readable" test, CSS selectors and XPath work for targeting arbitrary elements on a page, and browser devtools already generate them by right-clicking an element inside the Inspect view.
document.evaluate(), then apply highlighting.
The problem is they look like this:
ids does shorten the chain tremendously, but even in the best circumstances you're going to have 'some' naked syntax if the straight
id isn't what you're selecting.
The other problem is that selectors are fragile, but then so are normal fragments.
CSS selectors have deeper browser support and more widespread dev knowledge, but it's easy to support both; just check for
// at the start. Supporting CSS selectors along with the plaintext fragment quotes is more difficult; some short English snippets could very well be valid CSS selectors, even if they aren't likely to match anything real.
SVG allows arbitrary fragments with a
#viewBox(x1,y1,x2,y2) syntax, so a sister
#select() method could be an option.
Generating fragmention from a selection across multiple elements
What is the expectation from a fragmention-generating UI when the selected text is across mulitple elements? Examples:
- this fragmention https://kartikprabhu.com/static/demo/fragmention.html#he%20looked.%20%22What%27s%20happened%20to%20me?%22 across the first 2 paragraphs is clearly useless as it picks the whole document
- this fragmention https://kartikprabhu.com/static/demo/fragmention.html#UTF%20non-breaking%20space%20in which crosses across a
<strong>element is clearly useful
Sven Knebel: The first example would work better if the algorithm selected not the closest surrounding element, but only those children of the closest surrounding element that contain parts of the selected text (=the first two paragraphs). I think the second would behave the same. [via IRC]
Kartik Prabhu: The current implementation only selects one element similar to URL fragments. Whether it should be more flexible about this is a good question.
Should an element selected by fragmentioned URL be focussed?
Kartik Prabhu: AFAIK for usual fragment URLs the browser will put the focus on the element selected so that tabbing works nicely. Should fragmention implementations do the same?
A related idea is currently implemented as an experimental feature in Chrome 74.0.3706.0. Github issue.
There is a w3c spec for addressing Media Fragments but it explicitly excludes HTML.
Pullquote generates images to embed longer quotes in twitter. Getting it to generate fragmentions would be an excellent enhancement.
"Purple numbers" (per paragraph anchor tags) have been a feature of many blogs, for example Dave Winer's and Tim Bray's Ongoing but they do need to be added by the authoring software. (See also: http://www.eekim.com/software/purple/purple.html, http://www.burningchrome.com/~cdent/mt/archives/000388.html, http://www.burningchrome.com/~cdent/mt/archives/000387.html, http://www.tbray.org/ongoing/When/200x/2004/05/29/PurpleNumbers) Fragmentions can be chosen independently of authorship. Or a client-side script could generate them per-paragraph.
SuperFeedr allows subscribing to HTML fragments - enhancing this with fragmentions could be interesting.
Text-Search Fragment Identifiers E.g., http://example.com/index.html#:words:(distinguish) and http://example.com/index.html#:words:serve-as-context-to-(distinguish) and http://example.com/index.html#:words:context-to-(distinguish)-multiple-occurrences
Fragment Identiﬁers for Plain Text Files E.g., http://example.com/text.txt#line=10,20 and http://example.com/text.txt#match=[rR][fF][cC]
Using URLs to pass parameters to web applications, widgets and gadgets proposes #meta(). E.g., http://www.google.com/reader#meta(width=900,height=500,autohide,position=top)
Addrable E.g., table1.csv#where:city=Berlin,person=Richard
Hypothes.is fuzzy anchors and robust anchors have some good discussion of the broader area, and some code too. In April 2016, Hypothes.is also provided the ability to create direct links either with their browser extension enabled or via a proxy.
RapGenius now offers a highlight and annotate plugin as seen here on Business Insider. They highlight phrases, not paragraphs
The Guardian has a way to tweet the selection
W3C annotations selectors have proposed ways of being encoded in fragments
User friendly name
tl;dr: we need a user friendly name for fragmentions (which sounds like a jargon term).
The term "fragmention" is great for describing the plumbing of the extension of URL fragment syntax to handle space separated text to link to the first instance of that text, however a typical web user will be unlikely to understand what it refers to.
This brainstorm is for coming up with more user-friendly names/phrases to consider using for a URL that includes a fragmention
- "annotation link" - annotation is a typical use-case of a fragmention, yet even the term annotation is both overloaded, and a bit abstract.
- The abstraction here is fine, imo. Annotations are general-purpose enough of a concept for this to be fine. -- Jacky Alciné, 2018-05-08
- "quote link" or "quotation link" - linking to a specific quotation of text by including it in a fragmention is another good use-case and possibly another way to refer to it in a way that makes sense, e.g.: It's a link that quotes some text from the page.
- "highlight link" (verb: highlight linking), "highlighting link" or "highlighting URL" abstracts a level further than quote link, as the snippet featured may not always be a "traditional" quote. These also come closer to the simplest version of what is actually being implemented from a user's visual perspective. (Compare also with older implementations of anchor links, which are infrequently used in practice and generally not in the vernacular from a broad web user's perspective and would most often simply be called "links" instead.)
- ... others?
- Alternative proposal: use quoted string literals. Example: http://example.com/index.html#"string to search". —Sandeep.io 20:11, 23 April 2014 (PDT)
- On thinking about this a little, it doesn't sound like a good idea (for various reasons including the fact that the href attribute is quote delimited), but I like conveying the idea of "search for string literal" —Sandeep.io 20:30, 23 April 2014 (PDT)
- Betterlink is a proprietary alternative that doesn't like not highlighting the selection and a bug report about browser variations
- 2018-03-28 Kaushal Modi Fragmentions
- 2018-01-23 Chris Aldrich Fragmentions for Better Highlighting and Direct References on the Web
- 2015-07-21 Chris Aldrich BoffoSocko.com Now Supports Fragmentions!
- 2014-04-17 Kevin Marks Fragmentions - linking to any text
- ... add more
- An alternative to fragmentions are part of the Web Annotation spec, these have a browser add-on implementation, for Firefox in particular
- 2011 prior related proposal and implementation for linking to text in paragraphs: https://open.blogs.nytimes.com/2011/01/11/emphasis-update-and-source/
- Google Featured snippets and your website help page https://support.google.com/webmasters/answer/6229325
- Hypothes.is compiled a list of related reading, prior art, and examples for robust anchoring https://web.hypothes.is/robust-anchoring/#reading