Readwise is an awesome power-user tool for reading web articles, newsletters, and even e-books. DEVONthink is an amazing tool for building connected knowledge bases. Today I’m releasing a script that saves Readwise highlights to DEVONthink as annotated Markdown files, bringing the two together. It’s pretty handy.

I started trying out Readwise shortly after I started really getting into DEVONthink. DEVONthink can function as a Read Later type of tool, but I found Readwise Reader and associated browser extensions to be a lot more pleasurable for the actual act of reading. I weighed the options for a while, and then decided to go ahead and start paying for Readwise. But I was doing all of this highlighting as I was reading, which is really great for comprehension and retention, but those articles and highlights weren’t accessible from my larger knowledge base in DEVONthink.

What it does

This script bridges the gap. It’s designed to run at intervals, finding new highlights as you create them, and imports highlighted documents as Markdown files if the document is a web page. If it’s something else, like a forwarded email or a PDF/E-book, it will just create a bookmark linking to the Reader URL. The Markdown file/bookmark is then annotated with a list of the highlights and all of their associated notes and tags, as well as the Readwise document summary and any document notes/tags. The annotations are stored as both Finder comments and as separate annotation files.

If the document is saved as Markdown, the script also highlights paragraphs containing Readwise highlights. It does this using CriticMarkup ({==.*==}), which shows up as highlighted in both the Markdown editor and in the preview. It can only highlight by paragraph (not by sentence), which is fine for me because I typically just highlight by hitting h in Reader to highlight the current paragraph. The attached annotations show just the highlighted text, so more intricate highlights aren’t lost in this process. This highlighting makes it really easy to jump to pertinent portions of the text from the Document->Annotations inspector.

The Readwise API can return new highlights added to a document that already had highlights in it. This script handles this by merging new highlights into the annotations and updating the existing highlights in the Markdown. It can’t handle deletions of existing highlights via the API (yet), but will merge new and changed highlights.

The other minor caveat is that Readwise allows highlighting of images, but the script doesn’t highlight images in the text. However, the annotations will contain the image in Markdown, which will display in the annotations viewer.

How to use it

This script is written in Ruby, so you’ll need Ruby installed to run it. If your system doesn’t have Ruby (I believe it’s still installed by default, for now), you’ll need to install a copy using the Xcode Command Line tools, or with Homebrew, asdf, mise, rvm, rbenv… there are lots of options. I recommend running at least version 3.0.

To use the script you’ll need your Readwise API token. To get the token, log into your Readwise account and then go to https://readwise.io/access_token. Copy the token from that page and hang on to it for a second.

Next, download the gist and save it to your drive as readwise_to_devonthink.rb. It can be saved anywhere, as long as you know the path to it. Open it in your favorite text editor and paste the API key from above into the options hash near the top of the script. In that hash you can also configure the database and group to save to, if you don’t want to use the global inbox.

Next, make the script executable with chmod a+x /path/to/readwise_to_devonthink.rb. You can now run it once to get all existing highlights. Run /path/to/readwise_to_devonthink.rb and it will ping the API and get all highlights from the beginning of your history. The date of the most recent run is stored in ~/.local/share/devonthink/readwise_last_update. Future runs will only get new highlights since the date stored there. If you want to rerun it from the beginning for any reason, just delete that file.

Lastly, you’ll want this to run at intervals. macOS provides a perfect tool for this: launchd. Setting up a job with launchd is a little complex, and I’ll probably write a how-to eventually, but for now trust me when I say that using LaunchControl makes it so much easier than editing PLIST files. If you really want to do this by hand, here’s a good article. If this is the only launchd job you ever plan to set up, LaunchControl is probably not worth the price, but if you foresee ever needing to run custom jobs in the background or want a detailed look at what apps are doing so, it’s worth every penny.

Have fun

I know there’s probably a pretty small sliver of my readers who use both Readwise and DEVONthink, but hopefully this helps someone out. I built it for my own needs, obviously, but I made it as portable as possible so others might benefit. Enjoy!