kindle-zotero_importer/README.md
Utku Bilen Demir 935bc049ce Kanzi 0.6.7: bracket colours [r]=grey + editable Settings
- 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
2026-09-22 15:19:27 +02:00

4.3 KiB
Raw Permalink Blame History

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.

please give me money+

Install (30 seconds)

  1. Download kindle-zotero-importer.xpi from Releases (latest 0.6.7, or 0.6.6-beta for preview).
  2. In Zotero: Tools → Plugins → gear → Install Plugin From File… → pick the .xpi → restart Zotero.
  3. Tools → Kanzi… (or Kindle 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

  1. Choose your file; click Choose My Clippings.txt and pick your cumulative My Clippings.txt from Kindle (/Documents/My Clippings.txt); keep the window open; you will see live progress.
  2. Check Integrated; after the run, Integrated shows what was imported (Highlight Text; Citekey; Added On; Integrated; Page); filter to find anything.
  3. Fix Conflicts; if a Kindle title did not match a Zotero item, Conflicts shows it with up to 3 suggestions citekey · title (score%); click Use on the right one; or type any citation key / Zotero key / Item ID under Use Custom; or Ignore Title to skip it forever; if you map chabot2013 for one Simondon variant, it will offer to apply the same mapping to the other variants with that candidate.
  4. 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; check Full re-import from scratch only if you want to rebuild everything.
  5. Mappings; see all titles you have approved or ignored, newest first, with date; Delete any entry to send it back to Conflicts for re-matching.
  6. Settings / Artifacts; change Python/Zotero DB paths and Save Settings; or Open/Reveal any 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.txt cumulative (do not clear it on the Kindle); the importer remembers what is already integrated via kindle-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-attachment in Conflicts means that.
  • Full re-import is 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 in Settings → 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.