No description
Find a file
2026-09-24 00:21:17 +02:00
.github donations: humble 'please give me money' link (FUNDING.yml + README + manager infobox) 2026-09-16 15:33:47 +02:00
docs Initial Kindle Zotero importer baseline 2026-05-27 10:49:04 +02:00
plugin Kanzi 0.6.18: fix double bracket comment + missing text/DOI 2026-09-24 00:00:52 +02:00
scripts 0.6.4: incremental id-based import, Mappings/Integrated, black iA Duo, resizable tables 2026-09-16 14:44:31 +02:00
src/kindle_zotero_importer Kanzi 0.6.16: one bar per colour (b, blue, bl) + robust scanned PDF handling 2026-09-23 21:41:20 +02:00
tests feat: add anonymized sharing prompt and fuzzy tests 2026-09-18 18:54:25 +02:00
.gitignore gitignore MEMORY.md — not for public 2026-09-24 00:21:17 +02:00
main.py Initial Kindle Zotero importer baseline 2026-05-27 10:49:04 +02:00
plugin_runner.py 0.6.4: incremental id-based import, Mappings/Integrated, black iA Duo, resizable tables 2026-09-16 14:44:31 +02:00
pyproject.toml Initial Kindle Zotero importer baseline 2026-05-27 10:49:04 +02:00
README.md Kanzi 0.6.18: fix double bracket comment + missing text/DOI 2026-09-24 00:00:52 +02:00
updates.json Kanzi 0.6.18: fix double bracket comment + missing text/DOI 2026-09-24 00:00:52 +02:00
zotero-writer.js Initial Kindle Zotero importer baseline 2026-05-27 10:49:04 +02:00

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

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

Works with Zotero 7 to 10, macOS, Windows and 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. Columns are Highlight Text, Citekey, Added On, Integrated and Page. Use the filter to find anything.
  3. Fix Conflicts. If a Kindle title did not match a Zotero item, Conflicts shows it with up to three suggestions citekey · title (score%). Click Use on the right one. Or type any citation key, Zotero key or 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. It reuses the last file, or asks for it. Only new or changed highlights are repositioned. Already integrated ones are skipped, so the second run is fast. Tick 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. Use Delete to send any entry back to Conflicts for rematching.
  6. Settings and Artifacts. Change Python or Zotero DB paths and Save Settings. Or use Open or Reveal for any generated file, such as mismatch-review.md or 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.

Coloured highlights

You can specify the colour of your highlights while writing the note by adding a bracket at the start.

Write [o] This is orange on Kindle, either as the highlight itself or as the note attached to it. Kanzi strips the bracket and imports the highlight in that colour. For example, [o] This is orange becomes orange highlight with text This is orange. If the note is [r] important, the highlight turns red and the note becomes important.

All codes are single letters and unique:

Code Full name Hex Colour
y yellow #ffd400 yellow
o orange #ff8c00 orange
r red #ff6666 red
e grey / gray #8a8a8a grey
g green #5fb236 green
b blue #2ea8e5 blue
p purple #a28ae5 purple
m magenta / pink #e56eee magenta

Both [o] and [orange] work, case is not sensitive, and space after the bracket is ignored. Change any mapping in Settings → Highlight colours using the hex picker and preview. Use + Add mapping or Reset to defaults. British spelling is used throughout.

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 in the wrong place, check that the Zotero item has the correct PDF or 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.
  • Past highlights will recolour incrementally when you add a bracket code to them, or when you change the colour map in Settings. Otherwise use Full re-import to recolour everything.

Detailed Guide

Tools → Kanzi… opens the manager.

Summary. Shows clippings, unique titles, final annotations and conflicts. Also Match Statuses and Plan Statuses. The run panel shows Choose My Clippings.txt, progress, stage and detail, and the Full re-import checkbox.

Integrated. The last import-plan.final.json annotations. Columns are Kindle Title, Citekey, Highlight Text, Added On, Integrated and Page with colour swatch. Filter at the top right, 400 shown, sortable and resizable.

Conflicts. Unresolved titles. Type is Title match, Override suggestion or Attachment/position. Candidates shows N suggestion(s) — top: citekey (score%). Each candidate has a Use button. Below that is Use Custom and Ignore Title. Saving shows the Re-import bar. If you use chabot2013 for one Simondon variant, it offers to apply to other variants with the same candidate.

Mappings. Persistent match-overrides.json. Columns are Kindle Title, Resolution, Status, Count and Updated. Use Delete to send it back to Conflicts. Filterable.

Settings. Project directory, Python, Zotero DB, Zotero storage, Share anonymised annotations (on by default, private, hashed only), and Highlight colours as above. Save Settings writes plugin-config.json and colour-map.json for the pipeline. No restart is needed.

Artifacts. Mismatch review, Persistent overrides, Generated suggestions, Positioned plan, Final writer plan and Plugin summary. Each has Open and Reveal.

Incremental is default. Only new, changed or colour-changed highlights are repositioned.

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 and reprocess all

PDF positioning uses Poppler (pdftotext, pdftohtml, pdfinfo) plus qpdf fallback. EPUB uses CFI. Zotero writes are only via Zotero.Annotations. It never writes zotero.sqlite directly.

Releases

Stable releases are on Releases with kindle-zotero-importer.xpi and 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.

Anonymised sharing is on by default to help future development. It sends only citation key, hashed highlight, colour, has comment and note, added on and integrated at. It never sends raw highlight text. Opt out any time in Manager → Settings → uncheck Share anonymised annotations.