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

3.8 KiB
Raw Blame History

Caution

This project has been heavily vibecoded.

Kindle Zotero Importer

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

please give me money+

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 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.

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.