Readwise Sync for Joplin

A Joplin plugin that syncs your Readwise highlights to Joplin.

Features

• One-way sync from Readwise to Joplin
• Two sync modes: one note per book, or one note per highlight (with sub-notebooks per book)
• Automatic background sync at configurable intervals
• Incremental updates - only fetches new/updated highlights
• Note updates - existing notes are updated when highlights change
• Tag sync - optionally create Joplin tags from Readwise highlight tags
• Safe setting changes - changing structural settings (sync mode, notebook name, API token, tag sync) archives the old notebook and triggers a full re-sync

Installation

1. In Joplin, go to Tools → Options → Plugins
2. Search for "Readwise Sync"
3. Click Install
4. Restart Joplin

Configuration

Go to Tools → Options → Readwise Sync to configure:

| Setting | Description | Default | |---------|-------------|---------| | Readwise API Token | Your API token from readwise.io/access_token | (required) | | Notebook Name | Name of the notebook where highlights will be saved | Readwise Highlights | | Sync Mode | How to organize highlights (see below) | One note per book | | Sync Tags | Create Joplin tags from Readwise highlight tags and assign them to notes | Off | | Sync Interval | How often to sync (in minutes). Set to 0 to disable automatic sync | 60 |

Sync Modes

• One note per book (default) - Creates a single notebook ("Readwise Highlights") with one note per book. Each note contains all highlights for that book, along with book metadata.
• One note per highlight - Creates a single notebook ("Readwise Highlights") with a sub-notebook per book (named "Book Title - Author"). Each highlight becomes its own minimal note containing just the highlight text and your note.

Changing Settings

Changing the Sync Mode, Notebook Name, API Token, or Sync Tags will:

1. Rename the existing notebook to "Readwise Highlights (old)" (or "old 2", "old 3", etc. if that name is taken)
2. Reset the sync timestamp so all highlights are re-imported
3. Create a fresh notebook with the new structure on the next sync

This ensures you never lose your existing notes while getting a clean re-sync with the new settings.

Usage

Automatic Sync

Once configured with your API token, the plugin will automatically sync your highlights in the background at the configured interval.

Manual Sync

To sync immediately, go to Tools → Sync Readwise Highlights Now.

Note Format

One note per book

Each note is created with the book title and contains:

• Cover image
• Book metadata (author, category, source)
• ISBN and link to Readwise
• Your personal notes about the book
• All highlights sorted by location
• Highlight metadata (color, date, source link, tags)

Example:

![Cover](https://images-na.ssl-images-amazon.com/images/I/...)

**Author:** James Clear
**Category:** books
**Source:** kindle
**ISBN:** B07D23CFGR
[View in Readwise](https://readwise.io/bookreview/...)

## My Notes

This book changed how I think about habits and systems.

## Highlights

You do not rise to the level of your goals. You fall to the level of your systems.

*yellow · Jan 15, 2024*

---

Habits are the compound interest of self-improvement.

**Note:** This is a key concept

*blue · Jan 16, 2024 · #favorite #keyidea*

---

One note per highlight

In this mode, each book gets its own sub-notebook named "Book Title - Author" (e.g. "Atomic Habits - James Clear"). Each highlight becomes a separate note titled with the first 80 characters of the highlight text.

Notes are kept minimal — just the highlight text and your note (if any). All book context is in the sub-notebook name.

Building from Source

npm install
npm run dist

The plugin will be built to publish/org.joplinapp.plugins.ReadwiseSync.jpl.

Testing

npm test

License

MIT