Falling in love with hypothes.is and Roam

One of the biggest hinderances in reading articles on my iPhone has always been that it is a hassle to capture notes on what I read. This led to a lot of articles read without the knowledge retained which in turn equals a waste of time. Often I found myself thinking "I read something last week about that, what was it exactly again and where did I read it?"

For me this journey has come to an end by using a custom iOS shortcut and an app I created to export my annotations from hypothes.is to Roam Research

And I am very happy with the solution so far! 😎


This post is not about the why of capturing notes while reading, maybe I will write a post about that someday as it is an interesting topic for sure. 

This post is about my workflow on reading articles, capturing notes (using hypothes.is and an iOS shortcut) and keeping them where I can access them context when I need it (using Roam Research) and what I did to build a bridge to bring them together (https://roam.henjohoeksma.nl).

That should give you enough to sort it out yourself, but if you like to know how I got there, keep reading 😄.

Why I use Hypothes.is to capture annotations and highlights

There are a lot of tools to capture notes. A few of them can also do this on your smartphone, of which Instapaper is probably most well-known. 

After a little research I found that for all these tools you are set back with a subscription to their service. Let me state I have absolutely no problem with that. It is - in my opinion - absolutely okay to pay for services you use, that is if the cost and the value it provide you are in harmony. But truth be told: I like to keep the number of subscriptions I have to an absolute minimum, so I will always be looking for either a one-time payment or free alternatives.

This led me to an absolute wonderful service which is amazingly free: hypothes.is. With one downside: they have no iOS app so I can use it on my phone. At least that was what I initially thought. 

After a little search on their website I realised it is perfectly possible to use their service on my iPhone (did I mention it is absolutely free?). Using a shortcut1 you can either share the url to their service or inject their javascript library and start annotating and commenting Medium style on any article you read, even on your phone!

I started to get really excited about this as I now finally had a way I liked and that worked well while reading articles. The ☀️ started to shine!

Roam Research

If you haven't heard from Roam Research yet, you are in for a treat if you are into personal knowledge management and the second brain stuff. 

This is one of the subscriptions I happily pay for as it brings me much value. (I did try some free alternatives but found Roam to be more meeting my needs, but will write about that in another post.)

With Roam you can manage a whole lot more and to be honest I am still expanding my use of the tool almost daily and feel like I am still scratching the surface of all it's possibilities.

I use Roam Research to journal, keep track of my goals, as a personal management tool and for task and project management, reviews and planning. I do this for both my personal and professional stuff. 

And... I have never been more happy with a tool that is this young and seems to be so simple! 😊 I will definitely write another post about Roam soonish - for now: I keep my notes on what I read in there for reference so that's where my hypothes.is annotations have to end up in.

Bridging the gap

Hypothes.is has no default export option for your annotations. But... they do have an api! 

So I set out to investigate on how I could utilise this and create a small application that would allow me to transform it into something I could easily import it into Roam.

It appeared not to be that hard and I sketched up a working mockup while sitting on the couch one evening. 
After some polishing and some tweaking I deployed it to https://roam.henjohoeksma.nl and decided that I would keep it open free for everyone to use.

You will need an apitoken from your hypothes.is account (which you can get by going to your account on the top right of their service and select developer from the dropdown menu).

All the information is stored in your browser's localstorage, so not in the application (so no privacy issues here 😎). 

After setting your apitoken and your username you can customise the template I put in to match it to your own workflow, or go to the home page (you might need a reload the first before the api fetches your articles). Your articles will be loaded and you can process your annotations to be copy-paste ready for Roam.

Personally I copy the title of the article and paste it in Roam's search field (which suggests me to make a new page). I create the page and copy - paste the annotations I made on hypothes.is and press the 'Remove from hypothes.is' button to keep my list in hypothes.is clean.

Then I am ready to start processing my article notes, finetune, scratch or rework them and have my references neatly stored in my second 🧠 - awesome!

Within a matter of a few seconds I can bring my annotations to Roam2.

Some final remarks

After building this app I figured out you can also get your annotations using Roam42's SmartBlocks. I do prefer my little app (but I am biased of course 😉).

If you want to use public shortcuts on your iOS device, you have enable 'Use untrusted shortcuts' in your settings. You can download the 'open in hypothes.is' one here and the one that inserts the hypothes.is javascript here

I use the latter (which I did not personally create) because it doesn't open a new tab on Safari which gives a little smoother user experience.

Give the app I created a try, you can find it at: https://roam.henjohoeksma.nl 

It's free to use and will stay that way (you can always buy me a coffee if you like it). 
I would love to get your feedback on the app if you use it and hope you will enjoy it as much as I do.

If you would like to know more on how you could use Roam feel free to reach out, I am happy to help you get started!

  • 1 Below this article I will reference the 2 shortcuts I used and which one has my preference.
  • 2 Roam doesn't have a public api yet, but once that comes this workflow might become even better 😎.