Sync your KOReader highlights into Zotero as native annotations.
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.
- How it works
- Status
- Install
- Set up
- Syncing
- Matching
- Duplicates
- Limitations
- Development
- Credits
- Licence
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
- On the device, the
highlightsync.kopluginplugin exports each book's highlights as a.sdr.jsonfile 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. - 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.
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.
| 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.
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 askozosync.zip, rename it back tokozosync.xpibefore installing.
Tools → Plugins → ⚙ → Install Plugin From File…
- Open Zotero and go to Tools → Plugins.
- Click the ⚙ gear icon in the top right, then Install Plugin From File…
- Select the
kozosync.xpiyou downloaded. Make sure the file picker is showing.xpifiles — it filters to them by default. - 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.
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.
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/, notKoofr/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.
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.
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.
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:
- 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. - Filename — the normalized comparison above.
- 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.
A second sync changes nothing. Two independent defences:
- a persistent link map (
kozosync-links.jsonin 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.
- 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.
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 explicitlyReleases 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.
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.
- 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.