- src/kindle_zotero_importer/import_plan.py: add DEFAULT_COLOUR_MAP with grey->[r] per request (y/o/r/grey/gray/red/g/b/p/m etc.), _extract_colour() strips leading [code] and maps to hex, _annotation_stub() uses it, build_import_plan() accepts colour_map - src/kindle_zotero_importer/cli.py: _load_colour_map() from workdir/colour-map.json or plugin-config.json colourMap, passed to build_import_plan (incremental + full) - plugin/bootstrap.js: saveSettingsFromManager() persists colourMap to plugin-config.json + colour-map.json, getRuntimeSettings() loads it, loadColourMap() helper, label Kanzi - plugin/manager.html: Settings → Highlight colours editor (table bracket→hex with colour picker, preview, +Add, Reset, grey=[r] note, example [o] orange), saveSettings() collects colourMap, init uses F tokens - plugin/manifest.json: name Kanzi, 0.6.6→0.6.7, description Kindle annotations to Zotero - README.md: Kanzi title, Tools → Kanzi…, colours tip with British spelling - updates.json: add 0.6.7 on top
4.3 KiB
Caution
This project has been heavily vibecoded.
Kanzi — Kindle annotations to Zotero
Import Kindle My Clippings.txt highlights into Zotero as native annotations; directly inside Zotero, no terminal needed. Formerly Kindle Zotero Importer.
Install (30 seconds)
- Download
kindle-zotero-importer.xpifrom Releases (latest0.6.7, or0.6.6-betafor preview). - In Zotero:
Tools → Plugins → gear → Install Plugin From File…→ pick the.xpi→ restart Zotero. Tools → Kanzi…(orKindle Zotero Importer…) to open the manager.
Works with Zotero 7–10; macOS/Windows/Linux; PDF and EPUB. Colours via bracket: [o] orange, [r] grey (per request), [red] red, [y] yellow, etc. — editable in Settings → Highlight colours.
Use
- Choose your file; click
Choose My Clippings.txtand pick your cumulativeMy Clippings.txtfrom Kindle (/Documents/My Clippings.txt); keep the window open; you will see live progress. - Check Integrated; after the run,
Integratedshows what was imported (Highlight Text;Citekey;Added On;Integrated;Page); filter to find anything. - Fix Conflicts; if a Kindle title did not match a Zotero item,
Conflictsshows it with up to 3 suggestionscitekey · title (score%); clickUseon the right one; or type anycitation key/Zotero key/Item IDunderUse Custom; orIgnore Titleto skip it forever; if you mapchabot2013for oneSimondonvariant, it will offer to apply the same mapping to the other variants with that candidate. - Re-import; after you have fixed one or more titles, click
↻ Re-import with saved overrides(re-uses the last file; or asks for it); only new/changed highlights are re-positioned; already integrated ones are skipped, so the second run is fast; checkFull re-import from scratchonly if you want to rebuild everything. - Mappings; see all titles you have approved or ignored, newest first, with date;
Deleteany entry to send it back toConflictsfor re-matching. - Settings / Artifacts; change
Python/Zotero DBpaths andSave Settings; orOpen/Revealany generated file (mismatch-review.md;match-overrides.json; …).
Your choices are saved in match-overrides.json in the project folder; back it up, share it, or delete an entry to undo a mapping.
Tips
- Keep
My Clippings.txtcumulative (do not clear it on the Kindle); the importer remembers what is already integrated viakindle-id:<hash>tags, so re-imports are incremental. - If a highlight is positioned in the wrong place, check that the Zotero item has the correct PDF/EPUB attached (not a link);
Matched-title-no-attachmentinConflictsmeans that. Full re-importis only needed if you changed many mappings at once or want to rebuild from scratch.- Colours: start a highlight with
[o],[r](grey, per request),[red],[y],[g],[b],[p],[m]— e.g.[o] This is orange→ orange. Full names ([orange],[grey]etc.) also work. Change mappings inSettings → Highlight colours(British spelling).
For developers / CLI
python scripts/build_plugin.py # → dist/kindle-zotero-importer.xpi
python -m kindle_zotero_importer run "/path/to/My Clippings.txt" --workdir . --pretty
python -m kindle_zotero_importer run ... --full # ignore incremental; re-process all
PDF positioning uses Poppler (pdftotext; pdftohtml; pdfinfo) + qpdf fallback; EPUB uses CFI. Zotero writes are only via Zotero.Annotations; never direct zotero.sqlite writes.
Anonymized sharing is on by default to help future development (only citation key; hashed highlight; color; has comment + note; added_on; integrated_at; never raw highlight text); opt out anytime in Manager → Settings → uncheck Share anonymized annotations (also annotation.utkubilen.de, private, no AI).
Releases
Stable releases are on Releases with kindle-zotero-importer.xpi + updates.json attached. Pre-releases (beta) are marked Pre-release on GitHub. Zotero auto-updates from releases/latest/download/updates.json.
Support
Issues and pull requests welcome at Issues.