Ideas for IndieWeb-ifying Hypothes.is

I use Hypothes.is regularly as part of my daily workflow. I’m also very interested in being able to “own” the data I generate with the tool and being able to keep it on my own digital commonplace book (aka website). As part of this, I’d like to be able to receive notifications from people publicly annotating, highlighting, and replying to my content and potentially display those directly on either my website in the comments section or as marginalia.

I’d promised to do a quick outline for the kind gang at Hypothes.is to outline how to make their product could be a bit more open and support some additional web standards to make it more IndieWeb friendly as well as to work toward supporting the Webmention protocol to send notifications of annotations on a page. A few weeks ago at IndieWebCamp New Haven I decided to finally sketch out some of the pieces which should be relatively easy for them to implement into the product. Below are some of the recommendations and some examples of what needs to be done to implement them into their platform to allow it to better interact with other content on the web. This post is in reply to a few prior conversations about Webmention, but primarily pertains to Microformats which will help in creating those. [1] [2] [3] [4]

Overview

To my knowledge Hypothes.is generates a hash for each annotation it has in the system and generates two separate, but related URLs for them. As an example, here are the two URLs for a response Jon Udell made on my website recently:

The first URL is where a stand-alone copy of the annotation lives on the web, separate from the content it is related to. screen capture of the content at URL https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow The second URL resolves to the page on which the annotation was made and both will automatically open up Hypothesis’ side drawer UI to the annotation in question and will–on most browsers–auto-scroll down the page to show the point at which the annotation was made. Essentially this second URL shows the annotation in-situ in conjunction with the Hypothes.is user interface. I’ll note that they can also have some human readable trailing data in the URL that indicates the site on which the annotation was made like so: https://hyp.is/_tLJyA-cEemE-qPndyfQow/boffosocko.com/?p=55708991. However, in practice, one could remove or replace the boffosocko.com and trailing portion with any other URL and the correct page will still resolve.

It is great that they make the first URL available with the relevant data. This in itself is very IndieWeb friendly to have each annotation in the system have its own stand-alone URL. Sadly all the data on this particular page seems to be rendered using JavaScript rather than being raw HTML. (See also js;dr.) This makes the page human readable, but makes it much more difficult for machines to read or parse these pages. I’d recommend three simple things to make Hypothes.is more (Indie)Web friendly:

  1. Render the annotation on the first URL example in full HTML instead of JavaScript;
  2. Add the appropriate microformats classes on those pages;
  3. Add the canonical URL for the page on which the annotation is in reference to either instead of or in addition to the Hypothes.is prefixed URL which already appears on these pages. Webmention functioning properly will require this canonical URL to exist on the page to be able to send notifications and have them be received properly.

These things would make these pages more easily and usefully parseable on the open web. If/when Hypothes.is may support Webmention (aka web notifications) then all of these prerequisite pieces will already be in place. In the erstwhile, even without Hypothes.is running code to support sending Webmentions, users could force manual Webmentions using services like Telegraph, mention-tech.appspot, or even personal endpoints generated on individual posts (see the one below) or on custom endpoint pages like mine on WordPress. Aaron Parecki’s article Sending your First Webmention from Scratch is a useful tutorial for those with little experience with Microformats or Webmention.

Types of Annotations and Microformats Markup

To my knowledge there are three distinct types of annotations that might occur which may need slightly different microformats mark up depending on the type. These are:

  1. Unassigned page notes (or sometimes orphaned page notes): For all intents and purposes are the equivalent of bookmarks (and are used this way by many) though they go by a different name within the service.
  2. Highlights of particular passages: In IndieWeb parlance, these are roughly equivalent to quotations of content.
  3. Highlights and annotations of particular passages: In IndieWeb terms these again are quotes of content which also have what might be considered a reply or comment to that segment of quoted text. Alternately the annotation itself might be considered a note related to what was highlighted, but I suspect from a UI and semantic viewpoint, treating these as replies is probably more apropos in the majority of cases.

Each of these can obviously have one or more potential tags as well. Some of the examples below include the p-category microformats for how these would logically appear. Using the example URL above and several others for the other cases, I’ll provide some example HTML with proper microformats classes to make doing the mark up easier. I’ve created some minimal versions of text and mark up, though Hypothes.is obviously includes much more HTML (and a variety of divs for CSS purposes. While some of the mark up is a bit wonky, particularly with respect to adding the hyp.is and the original posts’ canonical URLs, it could be somewhat better with some additional reworking of the presentation, but I wanted to change as little as possible of their present UI. For the minimal examples, I’ve stripped out the native Hypothes.is classes and only included the semantic microformats. Because microformats are only meant for semantic mark up, the developers should keep in mind it is good practice NOT to use these classes for CSS styling.

Page note with no annotations (bookmarks)

Example from https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow (but without the annotation portion)


<div class="h-entry">
    <a class="p-author h-card" href="https://hypothes.is/users/judell">judell</a>
    Public on <https://hyp.is/_tLJyA-cEemE-qPndyfQow/boffosocko.com/?p=55708991>"Chris Aldrich on the IndieWeb"</a> (<a class="u-bookmark-of" href="https://boffosocko.com/?p=55708991">boffosocko.com</a>)
    <time class="dt-published" datetime="2019-01-11 18:052:00" title="Friday, Jan 11, 2019, 6:52 PM"><a href="https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow" target="_blank" rel="noopener">Jan 11</a></time>
    
<div class="p-category">tag-name1</div>
 
<div class="p-category">tag-name2</div>
 
<div class="p-category">tag-name3</div>
</div>

Page note with an annotation

(aka a reply, but could alternately be marked up as above as a bookmark) Example from https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow


<div class="h-entry">
    <a class="p-author h-card" href="https://hypothes.is/users/judell">judell</a>
    Public on <https://hyp.is/_tLJyA-cEemE-qPndyfQow/boffosocko.com/?p=55708991>"Chris Aldrich on the IndieWeb"</a> (<a class="u-in-reply-to" href="https://boffosocko.com/?p=55708991">boffosocko.com</a>)
    <time class="dt-published" datetime="2019-01-11 18:052:00" title="Friday, Jan 11, 2019, 6:52 PM"><a href="https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow" target="_blank" rel="noopener">Jan 11</a></time>
    
<div class="e-content">
        
<p>This is web thinking in action.</p>
<p>https://blog.jonudell.net/2011/01/24/seven-ways-to-think-like-the-web/</p>
<p>Well done!</p>

    </div>

    
<div class="p-category">tag-name</div>
</div>

Highlights (aka quotes)

Example from https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow


<div class="h-entry">
    <a class="p-author h-card" href="https://hypothes.is/users/judell">judell</a>
    Public on <a href="https://hyp.is/gBZPQucmEeaPBQvYzSRo-Q/www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/">"As We May Think"</a> (<a class="u-quotation-of h-cite" href="https://www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/">www.theatlantic.com</a>)
    <time class="dt-published" datetime="2017-04-30 08:40:00" title="Sunday, Apr 30, 2017, 08:40 AM"><a href="https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow" target="_blank" rel="noopener">Apr 30, 2017</a></time>
    
<blockquote>First he runs through an encyclopedia, finds an interesting but sketchy article, leaves it projected. Next, in a history, he finds another pertinent item, and ties the two together.</blockquote>

    
<div class="p-category">IAnnotate2017</div>
</div>

Annotations (replies)

Example from https://hypothes.is/a/9JrX5lf9RraeLKKn9WwmMQ


<div class="h-entry">
    <a class="p-author h-card" href="https://hypothes.is/users/jeremydean">jeremydean</a>
    Public on <a href="https://hyp.is/9JrX5lf9RraeLKKn9WwmMQ/www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/">"As We May Think"</a> (<a class="u-in-reply-to" href="https://www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/">www.theatlantic.com</a>)
    <time class="dt-published" datetime="2015-09-02 15:11:00" title="Wednesday, Sep 2, 2015, 03:11 PM"><a href="https://hypothes.is/a/_tLJyA-cEemE-qPndyfQow" target="_blank" rel="noopener">Sep 2, 2015</a></time>
    
<blockquote class="p-in-reply-to h-cite">This has not been a scientist's war; it has been a war in which all have had a part.
<blockquote>
    
   
<div class="e-content">
        
<p>It kind of blows me mind that the end of WWII is the context for these early dreams of the Internet. Is it the hope experienced in patriotic collaboration toward technological innovation? That's what Bush seems to acknowledge explicitly. It's a techno-militaristic union that haunts us to this day (#prism). But I wonder too if it's the precarious of knowledge, or perhaps the destructiveness of knowledge, that also inspires Bush…</p>

    </div>

    
<div class="p-category">tag-name</div>
</div>

I’ll also note that there’s the potential of a reply on Hypothes.is to a prior reply to a canonical URL source. In that case it could be either marked up as a reply to the “parent” on Hypothesis and/or a reply to the canonical source URL, or even both so that webmentions could be sent further upstream. (My experience in this is more limited, not having dealt with it personally in the past.) Once these pieces are implemented, they can be tested against a variety of microformats parsers to ensure they’re outputting the correct (and properly nested) information. I often find that pin13 is a pretty solid modern and up-to-date choice for this.

Additional resources with examples

I’ll also leave the caveat here, that while I’ve got a stronger grasp of Microformats than the average bear, that the above examples may have some subtle quirks that others may catch or which could be improved upon. I find that the Microformats web chat can be a good source for helps from some of the world’s best experts in the area. (Other methods for engaging in chat via IRC, Slack, etc. can be utilized as well.)

If Dan, Jon, or any of the gang has questions about any of this, I’m happy to chat via phone, video conference, or other to help get them going.

Allowing arbitrary HTML in the Summary/Quote field in the Post Kinds Plugin

Now you can have richer reply contexts on your posts in WordPress

Reply contexts

One of my favorite parts of the Post Kinds plugin isn’t just that it provides me the flexibility to add a huge variety of post types to my website or the semantic HTML and microformats it provides to help my site dovetail into the IndieWeb. It’s that it allows me to quickly and easily provide very rich reply contexts to my posts so that I more easily know what I’ve bookmarked, liked, favorited, read, or replied to online. In some sense it helps guard against some of the problem of context collapse found in many social media sites on the internet. As my friend and foodie extraordinaire Jeremy Cherfas has said, “a reply without context is like an egg without salt.”

For a long time I had been wanting a bit more control of how the Post Kinds plugin presented some of the data it allows.1,2 After one inputs a URL, the plugin uses several methods to scrape the related web page and returns a lot of metadata about it including the title, a summary, the site name, tags, a featured image, publication date and time, the author and author’s website among others. The data returned depends on how the page is marked up and is generally based on available microformats or open graph protocol data when they’re provided.

The plugin has a setting to “Embed Sites into your Response” on its settings page, and this is generally okay, but it relies on sites to have some sort of oEmbed set up predefined. For bigger sites like YouTube and WordPress, this is generally alright, but it’s not always the case that any data is provided by the external site. Even in YouTube’s case you’ll only display the video with no other meta-data about it. As a result I leave it turned off.

Let’s take a quick look at what some of these default outputs for the reply context with a short comment underneath them look like.

This is the default  Post Kinds output for an automatically parsed YouTube video with the embed function off. While it’s a good start, it’s not necessarily inspiring or a good reminder of the content you watched. One could manually change or add some of the fields for additional data, but we would still be a bit limited.
This is what Post Kinds outputs for an automatically parsed YouTube video with the embed function turned on. It’s nice to have an embedded copy of the video, but where did it come from? What is it about? Why should we care? Is there any other metadata we can display?

With the embed option turned off the plugin will return a “Summary” of the parsed website page. This too is generally well supported in 90% of websites in my experience. But the data it returns is (smartly) filtered using wp_kses for security so that a malicious page couldn’t inject random html or code into your page. This means that useful functionality is often being stripped out of the “Summary/Quote” field in the reply context. I’d prefer to have the ability to have text with links, video, and audio to appear in-line in these contexts so that there’s a better representation of the actual post I’m reacting to.

The question then, is how can I make this happen?

In older versions of the plugin there was a setting for this feature, but it wasn’t well documented and most people didn’t know what the setting was or what it meant. For simpler UI and support it was ultimately stripped out although the raw code for it was left in. In fact, it’s literally the first short block of code within the plugin’s main code! It looks like this:

if ( ! defined( 'POST_KINDS_KSES' ) ) {
	define( 'POST_KINDS_KSES', false );
}

To enable the ability to manually add arbitrary html, links, audio, video, etc. you can go to your main administrative user interface in WordPress and go to Plugins >> Edit and then choose the Post Kinds option in the drop down selector in the top right hand corner and click select. Search for the code listed above (it should be right at the top, underneath the title and details for the plugin) and change the single word false to true. Next scroll down the page and click the Update File button.

Now you should be able to manually change any of the fields within the Response Properties metabox and they’d display in full HTML as you’d expect them to. (Caveat: because you’ve disabled a small layer of security, you should keep a close eye on what data appears in your “Summary/Quote” field and make sure you’re not allowing your site or your readers to be led astray or hacked. In my case, I’m almost always modifying it by hand, so it’s not a big issue. Your mileage may vary depending on what you’re posting.)

This is what Post Kinds outputs for a parsed YouTube video with the embed function off. We’ve gone in and manually tweaked the author name, URL, and photo and added manual HTML to render a sysnopsis with links and an in-line playable  iframed embed of the video. This is a much richer reply context! It doesn’t get much better than this. Thanks Post Kinds!!

Updates

But wait… What happens when I update the plugin? Won’t the update overwrite the change? Yes, you’re absolutely correct. You’ll have to remember to go back and make this change any time the plugin updates. To prevent this, you could instead modify your wp-config.php file in the root folder of your WordPress install. To do this add the following lines of code to the bottom of this file:

/** Sets up initial variable for the Post Kinds plugin to not filter the Summary/Quote field  */
if ( ! defined( 'POST_KINDS_KSES' ) ) 
	define(' POST_KIND_KSES', true );

Next save the file and upload it to your WordPress install. Now you should be all set.

References

1.
Aldrich C. Post Kinds Plugin for WordPress. BoffoSocko. https://boffosocko.com/2017/08/11/post-kinds-plugin-for-wordpress/. Published August 11, 2017. Accessed June 9, 2018.
2.
Aldrich C. Manually adding a new post kind to the Post Kinds Plugin for WordPress. BoffoSocko. https://boffosocko.com/2018/06/06/manually-adding-a-new-post-kind-to-the-post-kinds-plugin-for-wordpress/. Published June 7, 2018. Accessed June 9, 2018.