fragmention

From IndieWeb

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.

Example Fragmention:


Status
This is a Living Specification yet mature enough to encourage implementations and feedback.
Latest Published Version
https://indieweb.org/fragmention
Participate
issues
discussion on #indieweb-dev (on Libera IRC)
Editor
Kevin Marks
Authors
Other contributors: revision history
License
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 2024-12-22, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Behavior

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.

Use Cases

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 id or name. The simplest way to do this is make the browser try a bit harder when given a fragment to follow your intent.

Citation

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.

Annotation

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.

Syntax

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.

(space)
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".

Processing Model

To process a fragmention, we don't need a big change to the HTML spec. The HTML 5 §7.8.9 Navigating to a fragment section has a subsection find a potential indicated element as follows:

To find a potential indicated element given a string fragment, run these steps:

  1. If there is an element in the document tree that has an ID equal to fragment, then return the first such element in tree order.

  2. If there is an a element in the document

    tree that has a name attribute whose value is equal to

    fragment, then return the first such element in tree order.

  3. Return null.

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:

  1. If there is an element in the document tree that has an ID equal to fragment, then return the first such element in tree order.

  2. If there is an a element in the document

    tree that has a name attribute whose value is equal to

    fragment, then return the first such element in tree order.

  3. 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.

  4. Return null.

Open Source


IndieWeb Examples

Implementations on IndieWeb sites.

  • Tantek Çelik supports fragmentions on all tantek.com post permalinks since 2014-07-26 using the fragmention.min.js open 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

Silo Examples

UI for Fragmention-generation

Examples of user-interfaces for generating a fragmention from some selected text

  • Rogue Amoeba shared a bookmarklet to generate a fragmentation with highlighting and copy it to the clipboard.

Challenges

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.

Sensitivity

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.


Icon proposals

(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)

Check out the NounProject searches for link and text for some ideas.

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.

What if the linked-to text occurs more than once?

In Kevin Marks' follow-up post, he suggests using more words to create a unique reference, rather than trying to find a technical solution to the problem.

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.

JavaScript can easily slurp up the selectors and run document.querySelector()/document.evaluate(), then apply highlighting.

The problem is they look like this:

  • #post>article:nth-child(7)>div.caption>blockquote>blockquote>p:nth-child(3) (CSS)
  • //*[@id="post"]/article[4]/div[2]/blockquote/blockquote/p[2] (XPath)

Use of 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:

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?

Related work

A related idea is currently implemented as an experimental feature in Chrome 74.0.3706.0. Github issue.

The NY Times has a tool for annotating articles, but it makes a very complex anchor and requires a very specific algorithm. source here

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.

Save Publishing a bookmarklet by Paul Ford that highlights tweetable sentences, could be enhanced by fragmentions.

SuperFeedr allows subscribing to HTML fragments - enhancing this with fragmentions could be interesting.

Fragment Search by Gervase Markham in 2007 is the same idea, with a more complex syntax #!s!search%20term and #!s3!search%20term for 3rd occurrence.

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 Identifiers 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.

Bowerbird proposed # for words in december 2013

See also: http://en.wikipedia.org/wiki/Fragment_identifier#Proposals

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

Brainstorming

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?

Alternatives

Articles

See Also

Retrieved from "https://indieweb.org/wiki/index.php?title=fragmention&oldid=96463"