utku/kindle-zotero_importer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kindle-zotero_importer/README.md

3.7 KiB
Raw Blame History

Kindle Zotero Importer

Import Kindle My Clippings.txt highlights into Zotero as native annotations — directly inside Zotero, no terminal needed.

If this saves you time, please consider a small donation — please give me money ♥ (also PayPal · Ko-fi)

Install (30 seconds)

  1. Download kindle-zotero-importer.xpi from Releases (latest 0.6.4, or 0.6.4-beta for preview).
  2. In Zotero: Tools → Plugins → gear → Install Plugin From File… → pick the .xpi → restart Zotero.
  3. Tools → Kindle Zotero Importer… to open the manager.

Works with Zotero 7–10, macOS/Windows/Linux, PDF and EPUB.

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’ll 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 didn’t 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’ve 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’ve 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 (don’t clear it on the Kindle). The importer remembers what’s 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.

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.

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

If it helps your research, a small donation keeps the time for maintenance: please give me money ♥. Issues and pull requests welcome at Issues.