Guidance for Publishers

Hypothesis is available to “web citizens” in the form of a bookmarklet, browser extension, or by using via.hypothes.is–allowing them to annotate and discuss any page on the Web.

Publishers can bring this capability directly to their content, so that users don’t have to, in the following ways:

Embedding Hypothesis

To add Hypothesis to your web site, simply add the following line to the HTML source of your page:

<script src="https://hypothes.is/embed.js" async></script>

You can configure Hypothesis by including a config tag above the the script tag. For example, the following arrangement will ensure that our yellow highlights are hidden by default:

<script type="application/json" class="js-hypothesis-config">
{"showHighlights": false}
</script>
<script src="https://hypothes.is/embed.js" async></script>

You can find the full list of configuration options in our documentation.

Good Habits

When publishing annotation friendly documents, be sure to:

  • Include a <link rel="canonical" href="..." /> tag on pages that may be available at different URLs (and for which you want to share annotations).
  • Include Open Graph Protocol content in your metadata

More background on good practices and relating documents together can be found in our Guidance for Web Publishers.

Tools, plug-ins and integrations

The Hypothesis community has developed different tools to integrate on their websites, and explore other functionality using the Hypothesis code and API.  You can find different ways to include Hypothesis in your WordPress and Drupal websites on the full list, here.

If you’re working with a Content Management System or web site building software and would like to discuss integrating Hypothesis with your CMS, we’d love to hear about it!

PDF Annotation

You can use our PDF.js + Hypothesis project to add a viewer to provide Hypothesis annotation ability on top of PDFs you host.

This project provides the standard PDF.js viewer (built by Mozilla) and adds the necessary Hypothesis embedding code to display the same familiar Hypothesis sidebar on your PDFs.

Atom & RSS Feeds

The Hypothesis stream is available in the Atom feed format. It can be used with RSS/feed readers such as NewsBlur or integrated with chat and notification systems such as Slack or used to trigger other events in other systems using services like Zapier or IFTTT.

The primary feed lives at

You can filter the stream using various query parameters:

by URL

All annotations on Ta-Nehisi Coates’ Letter to my Son

by Tag

All annotations tagged edu305

by User

Paul Allison’s annotations