Special onebox for hypothes.is

Discourse supports hypothes.is oneboxing out of the box, but it is the default onebox:

It puts the annotated text as the title and the annotation as the content. It’s an ok solution but it’s not intuitive. Someone who sees that onebox has no clue that what it’s referring to is actually a web annotation, i.e. a piece of text on the net plus a comment on that piece of text.

It would be great to have a special onebox for this. Perhaps something that looks more like how the annotation is displayed by hypothes.is itself:



I don’t think Discourse Core is going to want to add this, but maybe this could go into Marketplace and make a plugin for it? Is it possible to make a plugin that provides a overridden custom onebox?


I suppose this can be done in a plugin, but let me explain a bit more. I suppose I misframed this topic by describing it as a onebox question. Yes, a better onebox for hypothes.is would be nice. But I think there is much, much more to be gained for discourse from a closer integration of hypothesis (or supporting Open Annotation more generally). Honestly, I think this is huge:

But let’s stay focused and figure out how discourse might use hypothesis. The most obvious use seems to be that it allows for a much smoother quoting of external webpages. Not the url but any specific piece of text on that page.

Concretely: I navigate to some website that I want to refer to in my discourse post, I highlight the snippet I want to quote and save it. Hypothesis gives me a link to that specific annotation and I simply paste it into my post. Currently, it is rendered like this:

(Note the misleading url and image)

But it should be very easy to make it render like this:

From: The Day The Trackbacks Died at https://blog.codinghorror.com:
I want to read your response to my posts, whether it’s on your site, or mine as a comment. So rather than relying on direct peer-to-peer links, I’m exploring the use of external indexing services.

By default, hypothesis only provides public links for annotations, not for highlights, which means you have to write a comment into hypothesis even if you just want to share the text snippet you are commenting on, but nobody forces discourse to display that comment. (The UX problem remains, though, that it doesn’t make sense to type the same comment both into hypothesis and into discourse, but I think a solution could be found here.) So I in my mockup, I have stripped the annotation that is shown in the onebox.

So that would be discourse referring to the world. The other way around would, of course, also be nice. In principle this already works: a discourse post can be annotated just like any other website (or pdf, BTW). The problem is, it only works if you have the Hypothesis Extension for Chrome installed because Discourse doesn’t like being shown in an iframe which means the hypothesis’ proxy solution (called “via”) doesn’t work with discourse forums. Which is a pity.

This can be solved in at least two ways:

  1. Let discourse be iframed by via.hypothes.is
  2. Customize discourse to include this JS snippet: <script src="https://hypothes.is/embed.js" async></script>

The problem with the embedded JS is that you will have the hypothesis sidebar displayed on the right edge of your screen (though perhaps it can be configured so that it is only displayed when some explicitly requests to see a specific annotation, i.e. people following an annotation link.)

So there is some food for thought…

PS: Not only does discourse need hypothesis, hypothesis obviously needs a discourse forum :wink:

1 Like

You can have someone submit a PR to add an engine: https://github.com/discourse/onebox/tree/master/lib/onebox/engine


Do you have some rough indication of how much work/money this would require?

Certainly less than a plugin. I remember when writing a onebox engine that it was fairly straightforward, with only a few confusing parts.

1 Like


I see this discussion is old.
I am a heavy user of hypothesis. Created over 5k annotations over 2 years.

Discourse is one of the few sites out there that I encountered that gave me trouble.

It is strange that a forum dedicated to facilitate discourse is the one that
would not play well with hypothesis.


There are 10 times as many annotations out in the wild now than there were 3 years ago.

I like discourse very much, and really would like to be able to use hypothesis to annotate the bits I find interesting or note worthy, and share links to these annotations.

Currently I rely on a work around: open the page using the “share a link to this post” on the first post at the top of the page. then annotate, and that way it does work.

Hypothesis annotations can greatly increase the viral discover-ability of content and the platforms aggregating them.


Tried to use hypothesis here.

It looks like it is working.
so it may just be some setting? Version?

one of the forums that I had encountered issues is https://forum.openglobalmind.com/

Well, that is not a public forum. Hypothesis can only works on pages that it can access, which excludes private forums, right?

I believe hypothesis can access non public pages as long as the user is logged in.
It is possible to add the annotation but you get the correct path pointing to the page only if you open it first with the ‘share this page with link’ first.

If I do that it creates the right annotation. Otherwise the annotations get orphanned

Like this

From the link like this

if I delete the query parameter first

The link to the annotation then works

I suspect @tophee that you and I are of a similar mind, since I seem to be following your threads around Meta lately. :smiley:

Indeed, and I think this discussion might get some more traction if retitled or posted anew with the focus more directly on the broader and (IMO) more interesting concept(s).

This seems like a potentially needless workaround. Surely there is (or could be) a more general way to do this.

There are at least 3 separate things being discussed here, and I think all three deserve consideration, arguably in separate threads.

First, Discourse being able to better present Onebox content from Hypothesis. This would be nice, but seems of somewhat limited use to my mind, provided you consider the more general case (outlined in point 3 below).

Second, Hypothesis being able to annotate Discourse forums. This may be a solved problem by now judging by some above responses, but if it’s not, it does seem like it would be nice if it worked. Arguably this is more important/useful than Hypothesis Oneboxing that allowed quoting of specific parts of a page, in light of…

Third, the more general idea of being able to quote anything on any page from any site using Discourse, which should not in my view be tied to Hypothesis specifically. I have actually found Discourse to have one of the very best implementations of quoting in any system, from the persistence and ease of quoting from multiple messages, to the optional expansion of context, and the quick jump to source, it’s an elegant implementation. It would really be notable, I think, if Discourse could do this on any site, not just the Discourse forum itself. Interestingly I think the case could be made that this might be especially useful in the context of Discourse for Teams, e.g. in research projects, competitive analysis, etc.

Obviously this would require either a browser plugin, or some kind of embedded page browser, or some other approach I’m not aware of, and it is likely to be non-trivial. But I think it has enough promise to be worth looking into. I think I could make a stronger case for it in its own thread if it seems justified…