From IndieWeb
Jump to: navigation, search

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.

Kevin Marks
Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2017-01-15, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.




Fragmentions find the first matching word or phrase in a document and focus its closest surrounding element. The match is determined by the case-sensitive string following the # (or ## double-hash). The closest surrounding element may be a span, paragraph, heading, button, input, or any other container.

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

Open Source

IndieWeb Examples

Implementations on IndieWeb sites.

  • Tantek Çelik supports fragmentions on all 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

  • 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
    • 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

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?”

Double-hashes in the wild

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 / "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" / ":" / "@" / "/" / "?" 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. 20:56, 23 April 2014 (PDT)

Firefox drops the first # on redirect: For instance redirects to an https version which should be but Firefox drops one of the # to give . Strangely enough fixes this (Firefox only drops one #) and 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.

URL encoding

Use + (instead of %20) for space characters in your fragmention. Fragmentions are decoded before search, which means + plus signs are interpreted as spaces. This makes for more readable conforming URLs.
Fragmentions are decoded before search, which means + plus signs are interpreted as spaces and thus must be escaped (%2B) if you mean to refer to a literal "+" character like "a+b" (a%2Bb).
More #-signs may be used as an extension point and thus if your fragmention text contains a literal "#" e.g. "Use my #hashtag", you MUST URL-escape it, e.g. "Use+my+%23hashtag".

Icon proposals

(Todo: upload images instead of linking.)

  • highlink.svg 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:

sknebel: 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

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. 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., and and

Fragment Identifiers for Plain Text Files E.g.,,20 and[rR][fF][cC]

Using URLs to pass parameters to web applications, widgets and gadgets proposes #meta(). E.g.,,height=500,autohide,position=top)

Addrable E.g., table1.csv#where:city=Berlin,person=Richard fuzzy anchors and robust anchors have some good discussion of the broader area, and some code too. In April 2016, 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:

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


See Also

Personal tools
Recent & Upcoming