Skip to content
aknahinPublic

About

Sync KOReader highlights into Zotero as native annotations, via WebDAV.

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

KoZoSync

KoZoSync

Sync your KOReader highlights into Zotero as native annotations.

Zotero 7+ License: MIT Release Changelog

Highlight a paper on your e-reader — the highlights appear on the matching PDF in Zotero, with their notes, colours, and correct position on the page.


Contents


How it works

KOReader stores annotations in a sidecar file next to each book. A WebDAV server sits between the e-reader and the desktop, and KoZoSync reads from the server side:

┌──────────────┐        ┌────────────────────┐        ┌──────────────┐
│   KOReader   │  push  │   WebDAV server    │  pull  │    Zotero    │
│  (e-reader)  │ ─────► │  (Koofr / other)   │ ─────► │  + KoZoSync  │
└──────────────┘        └────────────────────┘        └──────────────┘
  highlightsync            *.sdr.json files             native Zotero
  .koplugin                                              annotations
  1. On the device, the highlightsync.koplugin plugin exports each book's highlights as a .sdr.json file and uploads it to your WebDAV server. KoZoSync does not talk to the e-reader itself — that plugin is what gets the data off the device.
  2. On the desktop, KoZoSync finds the sidecar that belongs to a PDF in your Zotero library, converts each highlight into a real Zotero annotation, and merges it in without creating duplicates.

KoZoSync only ever reads from your server. There is no upload path anywhere in the code, so it cannot alter or damage your sidecar files.

About the WebDAV server

Development and testing were done against Koofr, and Koofr is what we recommend. Any standards-compliant WebDAV server should work — Nextcloud, ownCloud, a plain Apache mod_dav — but we have not tested against them, so treat those as unverified. If you get one working, a report in Issues is very welcome.


Status

Direction State
KOReader → Zotero ✅ Working — this is what the plugin does today
Zotero → KOReader 🚧 In development — not implemented yet

Right now KoZoSync is strictly one way: annotations you make in Zotero stay in Zotero, and nothing is ever written back to the device or the server.

Write-back is being worked on — it is what the Ko↔Zo in the name is for — but it is deliberately not shipped yet. KOReader highlights carry pos0/pos1 fields, internal document positions that encode zoom and rotation, and these cannot be reconstructed from Zotero's rectangles. Writing a sidecar without them risks corrupting a file that holds reading you cannot easily redo. Until that format is confirmed against a real device, the safe design is to have no upload path at all.


Install

1. Download the plugin

Grab the latest .xpi from the Releases page — that is the only place official builds are published. Do not download the .xpi from the source tree; it is not committed to the repository.

Each release contains:

Asset What it is
kozosync.xpi The plugin — this is the file you want
kozosync-<version>.xpi The same build, version-stamped
updates.json Update manifest Zotero polls; you never download this manually

Or from the command line:

# latest release
curl -LO https://github.com/aknahin/kozosync/releases/latest/download/kozosync.xpi

# or a specific version
curl -LO https://github.com/aknahin/kozosync/releases/download/v0.1.3/kozosync-0.1.3.xpi

# or with the GitHub CLI
gh release download --repo aknahin/kozosync --pattern 'kozosync.xpi'

Do not unzip the .xpi. Zotero installs it as-is. If your browser saved it as kozosync.zip, rename it back to kozosync.xpi before installing.

2. Install it in Zotero

Tools → Plugins → ⚙ → Install Plugin From File…

  1. Open Zotero and go to Tools → Plugins.
  2. Click the ⚙ gear icon in the top right, then Install Plugin From File…
  3. Select the kozosync.xpi you downloaded. Make sure the file picker is showing .xpi files — it filters to them by default.
  4. Restart Zotero.

Requires Zotero 7 or newer. After restarting you should see KoZoSync in Settings and a KoZoSync entry under Tools.

Once installed, Zotero checks for new versions automatically, so you only do this once.

3. Install the e-reader plugin

KoZoSync reads what highlightsync.koplugin puts on your server, so install it on your e-reader too and point it at the same WebDAV folder. Follow the install instructions in that repository — KoZoSync has nothing to read until sidecars are landing on the server.


Set up

Zotero → Settings → KoZoSync

Fill in the Server section, then press Test connection:

Field Example
Server URL https://app.koofr.net/dav/Koofr/
Username your account email
Password a WebDAV app password
Highlights folder Kindle/Highlights/

Two things that commonly trip people up:

  • Use an app password, not your account password. Koofr issues these under Preferences → Password → App passwords.
  • Koofr's WebDAV URL already includes your account root. The folder path is relative to it — Kindle/Highlights/, not Koofr/Kindle/Highlights/.

Test connection reports how many sidecar files it can see. If it finds zero, the folder path is usually the culprit — see the second note above.

Below that, When to sync controls the automatic modes. All of them are optional: Sync entire library (Tools menu) and the right-click command on an item always work regardless of what you set here.

Where your password is stored

In your operating system's keychain, via Zotero's login manager — the same place Zotero keeps its own WebDAV sync password. It is never written to prefs.js, so it will not leak into a settings export or a pasted bug report.


Syncing

Every automatic mode is optional and off by default; the manual commands always work.

Mode Where
Sync now for selected items Right-click an item or attachment
Sync entire library Tools → KoZoSync
On opening a PDF in the reader Settings → KoZoSync
Periodically Settings → KoZoSync

Syncing on reader-open runs in the background after the PDF is on screen, with a short network timeout and a cached file listing. An unreachable server never delays opening a file.


How a sidecar is matched to a PDF

Filenames are normalized on both sides and compared, rather than one being rewritten into the other:

Zhang_et_al._-_2025_-_Cypress_VLSI-Inspired_PCB_Placement….sdr.json   (KOReader)
Zhang et al. - 2025 - Cypress VLSI-Inspired PCB Placement….pdf        (Zotero)
                              ↓  both normalize to  ↓
zhang et al 2025 cypress vlsi inspired pcb placement with gpu acceleration

Example paper: Zhang et al., Cypress: VLSI-Inspired PCB Placement with GPU Acceleration, ASPDAC '25.

Underscores and spaces fold to the same token, so files whose names contain real underscores (DAC85_509.pdf) still match. Unicode is NFKD-normalized, so a fi ligature in a Zotero filename matches the plain fi KOReader wrote.

Three lookups are tried in order:

  1. Citation key — if the sidecar is named after a Better BibTeX key (zhangCypressVLSIInspiredPCB2025.sdr.json — the key for Cypress: VLSI-Inspired PCB Placement with GPU Acceleration), that resolves directly.
  2. Filename — the normalized comparison above.
  3. Metadata — a name rebuilt from the item's creator, year and title, which catches PDFs renamed since they left for the device.

If two different items match, KoZoSync reports it and writes nothing. It never picks one for you.

The full derivation, with the measurements behind it, is in MATCHING.md.


Duplicates

A second sync changes nothing. Two independent defences:

  • a persistent link map (kozosync-links.json in your Zotero data directory) recording which highlight became which annotation, and
  • inspection of the annotations already on the item — if you highlighted the same passage in both Zotero and KOReader, the existing Zotero annotation is adopted rather than buried under a copy.

Annotations KoZoSync creates are tagged kozosync, so you can find or bulk-remove them.


Limitations

  • Rotated pages are skipped. Page geometry is read from the PDF's /MediaBox; when a document contains /Rotate 90, the page-to-box mapping is ambiguous and KoZoSync skips rather than risk misplacing a highlight. Such files are listed in the report.
  • PDFs with a compressed page tree may be skipped for the same reason, unless the file is open in the reader (which supplies exact geometry).
  • Sidebar ordering of imported annotations can differ slightly from natively-made ones. Zotero's sort index embeds a character offset into the page's text layer that cannot be reproduced outside Zotero's own extraction; position on the page is exact, only the sidebar order among same-line annotations may vary.
  • Deletions are not propagated. Removing a highlight in KOReader leaves the Zotero annotation in place.
  • Only Koofr is tested. See About the WebDAV server.

Development

node test/run.js                  # unit tests, no dependencies
node test/integration-library.js  # runs the matcher against your real library
./build.sh                        # produces dist/kozosync-<version>.xpi + updates.json
./bump.sh                         # patch bump + a new CHANGELOG section
./bump.sh 0.2.0                   # or set the version explicitly

Releases are versioned per change, however small — see CHANGELOG.md. build.sh refuses to package when the manifest version and the newest changelog heading disagree, so a build cannot claim to be a version it has not documented.

The unit fixtures are real data: a genuine sidecar, a genuine Koofr PROPFIND response, and coordinate pairs taken from a PDF carrying both KOReader and Zotero annotations of the same line. That PDF is Zhang et al., Cypress: VLSI-Inspired PCB Placement with GPU Acceleration — a published, openly citable paper, so the fixtures can be read against the original.

To run from source, put a file named kozosync@aknahin in <your Zotero profile>/extensions/ containing the absolute path to your clone of this repository, then restart Zotero.

Contributing

Issues and pull requests are welcome — particularly:

  • reports of KoZoSync working (or not) against a non-Koofr WebDAV server,
  • sidecars that fail to match a PDF (attach the two filenames, not the file),
  • anything you know about how KOReader reconstructs pos0/pos1, which is the piece blocking Zotero → KOReader write-back.

Credits

  • highlightsync.koplugin by @gitalexcampos — the KOReader-side plugin that exports highlights to a WebDAV server. KoZoSync consumes what it produces; without it there is nothing on the server to sync.
  • KOReader — the e-reader document viewer.
  • Zotero — the reference manager this plugin extends.
  • Koofr — the WebDAV provider used throughout development.

Licence

MIT

About

Sync KOReader highlights into Zotero as native annotations, via WebDAV.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages