Kobo Highlight Sync

Sync highlights from a Kobo e-reader into your Obsidian vault without ever rewriting your notes.

Other Kobo importers regenerate the whole note on every import, so anything you add to it can be lost. This plugin only creates new notes and appends new highlights to the end of existing ones. Edit, move, rename, or annotate the notes however you like; the next sync still recognises what it already imported.

Usage

1. Connect the Kobo to your computer over USB.
2. Click the Kobo ribbon icon, or run Kobo Highlight Sync: Sync highlights from the command palette.
3. A report lists every book that received new highlights, with links to the notes.

Each book becomes one note in the output folder, with title, author, isbn, kobo_id, created, read, and tags in its frontmatter. Highlights appear in reading order, grouped under chapter headings, each followed by its position in the book:

## Chapter 1

> The highlighted passage. · 12% %%kobo:6bd03990-6d16-4b48-8cb3-421cf25a8432%%

The %%kobo:…%% marker is an Obsidian comment, so it is hidden in reading view and live preview. It is how the plugin knows a highlight has already been imported. Keep it when you edit a highlight.

What the plugin never does

• It never writes to the Kobo. It copies the device database to a temporary file and reads the copy.
• It never syncs while the device has unsaved changes. If the database has a non-empty -wal file, the sync stops and asks you to eject the reader properly.
• It never rewrites an existing note. New highlights are appended to the end, and existing frontmatter is left alone, so fields like read stay as you set them.
• It never writes into protected folders. By default these are Readwise/ and wiki/*/raw/. When every note for a book sits in a protected folder, new highlights go to a separate continuation note that links back to the original.
• It never deletes a file in your vault.

Before every sync the plugin backs up the Kobo database outside the vault and keeps the 10 most recent backups.

Files outside your vault

This plugin reads and writes a few files outside your vault. It makes no network requests.

• It reads the Kobo database, by default /Volumes/KOBOeReader/.kobo/KoboReader.sqlite, because that is the only place Kobo stores your highlights. It never writes to the Kobo.
• It writes a temporary copy of that database to the system temp folder and deletes it after reading, so the database on the device is never opened directly.
• It writes a backup of the database to ~/Library/Application Support/kobo-highlight-sync/backups/ before every sync and deletes older backups so only the 10 most recent remain. It only deletes backups it created. You can change this folder in the settings.

Settings

The interface follows Obsidian's language: Chinese when Obsidian is set to Chinese, English otherwise.

Limitations

• The default paths are for macOS. On Windows or Linux, set the database path to where your Kobo mounts.
• Positions are a chapter heading and a percentage of the book. Kobo does not store page numbers, and the book files are DRM-protected, so exact pages cannot be recovered.
• Only highlights are imported. Highlights with an attached note may not be imported yet (see the roadmap).
• Desktop only, because the plugin reads the database from the file system.

Roadmap

• Import highlights that carry an attached note.
• Default database and backup paths for Windows and Linux.

Development

bun install
bun run typecheck
bun test
bun run build

bun run build writes dist/main.js and dist/manifest.json. Tests that need a real Kobo database look for fixtures/KoboReader.sqlite (or the path in KOBO_FIXTURE) and are skipped when it is absent. The fixture is personal reading data and is never committed.

License

MIT