org-roam-readwise

org-roam-readwise let’s you export your readwise highlights into org-roam. Each book becomes it’s own note and the goal is to have a similar experience as with the Obsidian Readwise plugin.

The package will create a new directory in your org-roam-directory called readwise. In there you will find different subdirectories for articles, books etc. A typical synced book will look like this:

Installation & Configuration

To install org-roam-readwise you can use the new :vc attribute in use-package:

(use-package org-readwise
   :vc (:url "https://github.com/snowiow/org-roam-readwise"
             :branch "main")
  :after org-roam
  :custom
  (org-roam-readwise-output-location (concat org-roam-directory "/pages/readwise")) ;; This is the default and it can be changed
  (org-readwise-auth-source 'auth-source-pass) ;; Use either auth-source or auth-source-pass
  (org-readwise-debug t)) ;; In case you want to see more detailed debugging messages during synchronization

Authorization

Using auth-source

To use org-roam-readwise, you need to configure it with your Readwise API token. The token should be stored in one of the files defined in `auth-sources`.

Example configuration:

;; Ensure auth-source is configured to find your Readwise token
(setq auth-sources '("~/.authinfo.gpg"))

Authinfo Configuration

org-roam-readwise requires an access token for Readwise, which should be stored in your `authinfo.pgp` file.

Example `authinfo.pgp` entry:

machine readwise.io login <your-email> password <your-readwise-token>

Here’s the syntax breakdown:

• `machine readwise.io`: The host for Readwise API.
• `login <your-email>`: Your Readwise login email.
• `password <your-readwise-token>`: Your Readwise access token.

Using auth-source-pass

Alternatively when you pass, you can use auth-source-pass:

(use-package auth-source-pass
  :ensure nil
  :config
  (auth-source-pass-enable)
  :custom
  (auth-sources '(password-store)))

In the org-roam-readwise definition you specify 'auth-source-pass as your auth source:

(org-readwise-auth-source 'auth-source-pass)

org-roam-readwise expects a root level entry called readwise.io in your pass directory. As the password the API key is stored

Usage

To sync your Readwise highlights, run:

M-x org-roam-readwise-sync

This will fetch your highlights and insert each book into a note under the specified output location.

The first time you run this command it will sync all your readwise highlights and write a timestamp file under org-roam-readwise-output-location. Subsequent runs will only sync from this time forward to sync faster and more efficient. If you however need a full resync of all your highlights you can execute:

C-u M-x org-roam-readwise-sync

Features

Markdown to Org-mode conversion

Readwise content (highlight text, notes, and book summaries) often contains Markdown formatting. org-roam-readwise automatically converts this to the equivalent Org-mode syntax on import, including links, bold, italic, inline code and strikethrough.

One way reproducible sync

This Readwise sync package is a one way sync tool from Readwise to your notes, similar to the official Obsidian Readwise plugin. Therefore this package makes use of readwise id’s for org id’s. This means, if you create links from other nodes to a readwise book node or a headline within them, they are durable. You can delete all your synced books, recreate them and links should still work.

This is also the intended usecase for this package. Don’t further enrich the synced nodes with your own content, rather link from your content to the readwise nodes and think of the readwise nodes as. When used in this way, Readwise becomes the single source of truth for your highlights and you gain durable referencing to your highlights and you can utilize links back to Readwise itself.

To read more about this concept, have a look at this link.

Limitations

• No real-time sync: Manual trigger required for syncing.
• Single user setup: Designed for single user configurations.
• Performance: Syncing a large number of highlights can be slow.
• Customization needed: Advanced configurations might require code adjustments.
• Currently everything will be synced regardless of if it was stored already. This can be very slow, but will optimize this with later changes
• No mapping for the different readwise categories possible. Books go into a books subdirectory, articles go into an articles subdirectory bucket, etc.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on the GitHub repository.

Thank you

A big thank you to CountGreven for creating org-readwise. I took his code base as a foundation and build this package from there.