What I intend to do and why

I’ve been using h. in the past weeks, and I like the tool. It created/uses a W3C protocol and has an API I can use with a token connected to my account.
I want to integrate annotations I make with my notes I keep locally better. This points towards using h. ‘headless’ in the sense I push things to and pull things from the API, rather than do my annotations in browser. This would reduce friction in my note making flow.

There are several things I can think of, at different levels of difficulty to achieve.

  • Being able to submit urls with a page wide annotation, tied to how I save webpages and a motivation for saving with a markdown clipper.
  • Being able to annotate a page saved in my notes, and send the annotations to the right url in h.
  • Being able to update annotations.

The first is the most straightforward, and the first I will try to achieve.

Steps taken

Save new page annotations

  • Envisioned path:
    • Use markdownload to save a page in markdown in an Obsidian folder. Alter the template to have the relevant info in a predictable spot (h post status, URL, web archive url and motivation for saving)
    • Run a script that checks for new files in that folder and filters those with a status of not yet posted to h.
    • Run API calls to submit the selected notes to h.
    • Change the status of the notes in Obsidian to published to h.
  • Steps taken
  • Steps to take
    • Try out the minimal JSON / POST structure in Postman to get it right
    • Try out the same JSON / POST re-using an earlier micropub script to post from PHP to h.
    • Find out how to evaluate the response and then set the status in the Obsidian note, re-using the script I use to blog from my notes to WP.

I find discovery in Hypothes.is of users that are more than sporadically sharing annotations around topics interesting to me very difficult. To aid discovery for others I’ve listed below the Hypothes.is users I’ve encountered. Split in two lists, those frequently or moderately active or of higher interest to me, and those sparingly active or inactive.



Inactive or less active


Do you use h.? You’re welcome to let me know in the comments.

Third party services usually make it very easy to add something to your digital life online. At the same time it always means a loss of control over the material you share through, store in, collect with such third party services. If one such third party shuts down, decides to pivot, pulls up new pay walls and restrictions, blocks or deletes your account, you have no

The IndieWeb, basically an open web approach, starts with the notion that you have control over your own material. It’s your creative expression, your data. For that it’s useful to have your own domain. As long you have that, you can move whatever material you share there to other servers, services etc. Second, whatever material you share outside your domain on third party services, should originate on your domain, or end-up there as a copy. For instance I share messages to Twitter that I write here. I used to share check-ins made in Swarm/Foursquare to check-in entries on my site. In both cases whatever happens to Twitter or Foursquare, I have my own online original or copy to which I can link. When I want to link to something in a conversation I share the link to my own domain.

I treat my domain name as ‘the mothership‘ of all my online traces. It is how my blog keeps being my avatar.

These are the ways my domain(s) is / are my mothership:

  • My articles, here on my blog
  • My messages to Twitter and Mastodon written on my blog
  • My slide decks hosted and sharable on my own domains, not using slideshare/scribd
  • My photos, here, linked to my off-site copy Flickr
  • My shortened URLs using Yourls on my own domain tzyl.eu
  • My code repositories on Github have their own URL redirect from a domain I control, so I can move to another code hoster or my own and keep the same links I shared with others
  • My check-ins when I used Foursquare, copied into my blog

This page was created using my personal Micropub client. This allows me to post not only posts but also pages to my various WordPress websites. And to do so along several paths, such as directly from my local notes. This page is merely a proof of concept. My intention is to use this way of posting to better extend my publicly shared notes in my Digital Garden. For now it is just about creating new pages. A next step would be to also apply this to updating of pages.

Current status:

  • Created a working way to submit JSON formatted blogposts to this site, code on GitHub
  • Included that in my earlier scripts to create posts from my feed reading, that I now no longer then have to post by hand.
  • Created a Microsub client to replace my feed reader, in which I can respond directly from within the page I am reading.
  • Combined the same basic script with a local webform so I can very quickly post something. I don’t think I will be using this possibility much but it was a good way to add a front-end to the micropub script first and fast.
  • Can take a local markdown file written in Obsidian and post it as html to my site. This is by far the most useful to me
    • I write my blogposts in Obsidian, drafts live in a specific writing folder. They have two inline data fields, status and tags. While writing a note has status ‘writing’, when it is ready to publish I set the status to ‘draft’.
    • Within Obsidian I use the same status field to create a dynamic overview of posts being written, ready to publish, and previously published (using the DataView plugin).
    • When I’m ready to post, I hit a hotkey which launches my PHP script. It looks at all files in the specific writing folder and checks for files that changed within the last few hours and if those contain a status field ‘draft’. For those that do it transforms the markdown in those files to html, and then posts that to my site, using the tags in the other data field to tag and categorise the post. It also sets the status field in my notes from ‘draft’ to ‘posted’.
    • I could also run the script every hour or so using a cron job, so that anything posts automatically, while I go on with my other work.


Local first, personal, narrow band
See blogpost.

Narrow band means:
my preferences can be treated as default inputs
my tasks are predictable to me
together they are functions with parameters, aka code.


Micropub standard
IndieWeb wiki on Micropub
Tips from Jan Boddez (in Dutch)
Jamie Tanna’s work on his personal micropub client
Jamie Tanna’s tool to get authorisation tokens manually, great for testing/development.
Parsedown, which I use to translate markdown files written in Obsidian, to HTML for my site.

I want to make it easy to publish lists of books I am reading and have read, or any other list. And do so without using centralised platforms like e.g. Goodreads (Amazon). A book list is a small library.
The route I am currently on, is publishing a machine readable list others can easily incorporate. These lists are in OPML, an exchange format for outlines. It’s the same format generally used to share lists of RSS feed subscriptions.

Current situation and usage: automated lists
Currently I am able to directly automatically create the lists in OPML from my individual book notes in Obsidian.md (which I use for PKM).
In Q1 2022 I experienced that creating lists and posting them works nicely and smoothly, with no friction. I do currently only create a few lists (fiction and non-fiction in the running year, antilibrary). I’m also working through the books I’ve read in the last decade or so, and gradually creating those lists. I’m not generating those as OPML however, they currently are just a list in my own notes.

Next steps: consuming other lists
Next steps will look at how to do the federating itself: how can I ‘consume’, or even include in my own lists, the OPML, ActivityPub or JSON lists of others in a meaningful way? I think a first step is consuming one list published by someone else, treating it as a recommendation list perhaps or some other form of input, much like I’m reading feeds. It might be useful to be able to pick out mentions about books I’ve already read, are in my anti-library, match an author I like, or match my interests while being unknown to me. I suspect a slightly tweaked parser for every new list might be needed, as using a list depends both on format and on content fields.

Ealier steps: proof of concept and data model
In 2020 I came across a posting by Tom Critchlow on this topic, and a year later I started looking into using OPML to create the lists.

I created a proof of concept, with a data format.
Using that I created a webform to update a book list by hand with a new entry.
Then I automated generating the lists (code on GitHub).
All as proofs of concept.