microformats | Chris Aldrich

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

Render the annotation on the first URL example in full HTML instead of JavaScript;
Add the appropriate microformats classes on those pages;
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:

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.
Highlights of particular passages: In IndieWeb parlance, these are roughly equivalent to quotations of content.
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.

📺 Micro.blog custom themes | YouTube

Watched Micro.blog custom themes from YouTube

Importing and editing custom templates on Micro.blog.

I do sort of wonder if Micro.blog functionality would break if new themes don’t have the correct microformats 2 markup? I suspect it runs in conjunction with various common parsers and thus may have issues. It’s a cool thing though that this sort of customization is available now on the platform which is quickly becoming more and more flexible.

👓 4 Reasons @GetClassicPress Should Add Native Microformats Support | Greg McVerry

Read 4 Reasons @GetClassicPress Should Add Native Microformats Support by

Greg McVerry (quickthoughts.jgregorymcverry.com)

Now that phase one of Gutenberg has dropped the interest in #ClassicPress grows by the day. So many WordPress developers fear the loss of control they will face under the new regime of 5.0. Many just don't want to do the work of all that refactoring. #IndieWeb and #ClassicPress should join forces. w...

👓 twenty eighteen | Matthias Pfefferle

Read zwanzigachtzehn by

Matthias Pfefferle (notiz.Blog)

2018 war ein durchwachsenes Jahr!

Mein privates „Ich“ hat letztes Jahr sehr viel Raum eingenommen und auch beruflich hat sich viel verändert.

Das heißt ich hatte generell wenig Zeit für mein online „Ich“ und wenn ich doch etwas Zeit hatte, war das Ergebnis meistens eher frustrierend.

My German is atrocious, but it’s well worth stumbling through to see what Matthias is up to lately, particularly with regard to his work on the IndieWeb.

I’ll have to revisit some of his work on OStatus and ActivityPub with respect to WordPress. It would be nice to be able to follow @chrisaldrich on Mastodon wouldn’t it?

Thanks, as always Pfefferle, for keeping the web open!

👓 Everything Old is New Again: Adventures in the IndieWeb | Desert of My Real Life

Replied to Everything Old is New Again: Adventures in the IndieWeb by

Cathie LeBlanc (Desert of My Real Life)

I’ve written about my forays into the IndieWeb movement before. I have even written about how I feel like I’m moving to a philosophy of sharing my work that is kind of old school. Last week, I had the occasion to see a perfect example of how the “new” ways that I’m working are actually the old ways.

Kudos Cathie for rolling up your sleeves and delving in like this! You’re getting some fairly solid results and have far stronger grasp of what is going on than I certainly did in my first year–not to say that I’m much better off now to be honest.

The tougher part is that some of your post seems a bit misleading to me.

The couple of microformats related lines you’re adding in your child theme like add_theme_support( ‘microformats2’ ); are in fact declaring that your theme properly supports microformats v1, v2, and microdata which it doesn’t quite. Those lines don’t actually add support (as the hook might indicate), but tell other WordPress plugins that your theme is microformats compatible which may prevent them from adding particular pieces of redundant microformats related code.

While you’ve got an h-entry in your header file, you’re closing the related </div> just after the title so that if the body of your post includes a p-summary or an e-content microformat, parsers are likely to have problems. Instead you might want to do something similar in either your content.php (or other file that adds the body of your post) or your footer.php files where you close that div in one of those two files instead of in your header.php file. If you need it the article page on the wiki has a simple example of what the final result should look like.

My favorite template for how to add microformats to a WordPress theme is David Shanske’s fork of the TwentySixteen theme. Because of GitHub’s interface and the fact that he made changes in relatively small increments, you can look at the history of his changes (start with the oldest ones and move forward) and see the highlights of what he added and removed in individual files to effect the necessary changes. (He made some other drastic changes like removing Post Formats in preference to Post Kinds as well as some other non-microformats changes, so you’ll necessarily want to skip those particular changes.) I think I learned more about WordPress Themes by going through this one example a change at a time than any of the books or tutorials I’ve ever seen.

Another tool in addition to indiewebify.me is the Pin13 parser which will parse your page and give you some indication about what it is finding (or not) and how things are being nested (or not).

If you need some help, feel free to catch one of the WordPress folks in the IndieWeb chat. I suspect that since you’ve got the fortitude to dive into the code the way you have, that you’ll be able to puzzle it out.

🎧 IndieWebCamp Berlin 2018 Session Summaries | Marty McGuire

Listened to IndieWebCamp Berlin 2018 Session Summaries by

Marty McGuire from martymcgui.re

Listen to a summary of all the sessions at IndieWebCamp Berlin 2018!

Session notes: https://indieweb.org/2018/Berlin/Sessions

Narration by Marty McGuire
Edited by Aaron Parecki

This is a repost of https://aaronparecki.com/2018/11/18/7/indiewebcamp-berlin.

Interesting to see this served from Aaron’s domain when it looks and sounds just like another of Marty’s podcast. I’m guessing they collaborated at camp to put it together. I love the idea of not only having this as a quick audio summary of all the sessions, which I’ll now have to go back and watch a few, but of having this as a simple section at the end of day one at IndieWebCamps.

The sessions on Microformats, Displaying Responses, Data Ethics, Making your website work offline, and Location sound like interesting things to take deeper looks into. I particularly like the idea of separating the legal and the ethical portions completely away from each other and doing the ethical portion first and then secondly filtering that through any legal loopholes. Ideally the legal filter won’t actually be filtering anything out if the ethical is done properly, and if it does, then perhaps the legal has some issues.

🔖 JSON-LD And You – Google Slides | Aram Zucker-Scharff

Bookmarked JSON-LD And You: A Guide to Structured Metadata for Journalism by

Aram Zucker-Scharff (docs.google.com)

A presentation on Google Docs.

Hi, I’m Aram Zucker-Scharff and now that we’re settled in, I’ll take a minute to introduce myself. I’m the Director of Ad Tech Engineering at The Washington Post, where I work with teams across the organization to help the Post make money and, through our Arc platform, help other publications make money as well. But I’ve taken a long road to this point, I started off as a journalist, then an editor, a social media manager, a product manager, a freelance strategy consultant and developer and last a full stack developer. I even spent some time being very bad at selling ads.

Aram Zucker-Scharff is about as sharp as it gets when it comes to journalism, adtech, and technology. I do wish he’d spent some additional time on Microformats (or even the v2 implementation) as they’re still broadly supported and much less likely to be treated as the flavor-of-the-month that JSON-LD and schema.org are currently.

I dug around a bit and didn’t see any video from this session.

📺 Jeremy Keith on Taking Back The Web (Opening Keynote) at Voxxed Thessaloniki 2018

Watched Taking Back The Web - Opening Keynote by

Jeremy Keith from Voxxed Thessaloniki 2018 | YouTube

In these times of centralised services like Facebook, Twitter, and Medium, having your own website is downright disruptive. If you care about the longevity of your online presence, independent publishing is the way to go. But how can you get all the benefits of those third-party services while still owning your own data? By using the building blocks of the Indie Web, that’s how!

Great overview of the building blocks of the IndieWeb from Voxxed Thessaloniki 2018.

Hat tip: Jeremy Keith