From e0a26649d67833b4b3c2be1fe2788f37c59381f5 Mon Sep 17 00:00:00 2001 From: Utku Bilen Demir <84389167+UtkuBilenDemir@users.noreply.github.com> Date: Wed, 16 Sep 2026 22:44:18 +0200 Subject: [PATCH] docs: add vibecoded disclaimer box, replace em dashes with ; --- README.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index cae57be..d524723 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,35 @@ # Kindle Zotero Importer -Import Kindle `My Clippings.txt` highlights into Zotero as native annotations — directly inside Zotero, no terminal needed. +> [!CAUTION] +> **Disclaimer: This project has been heavily vibecoded.** [please give me money+](https://github.com/sponsors/UtkuBilenDemir) +Import Kindle `My Clippings.txt` highlights into Zotero as native annotations; directly inside Zotero, no terminal needed. + ## Install (30 seconds) 1. Download `kindle-zotero-importer.xpi` from [Releases](../../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. +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`, …). +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. +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:` 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. +- Keep `My Clippings.txt` cumulative (do not clear it on the Kindle); the importer remembers what is already integrated via `kindle-id:` 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 @@ -34,10 +37,10 @@ Your choices are saved in `match-overrides.json` in the project folder — back ```sh 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 +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. +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