87 lines
3.4 KiB
Markdown
87 lines
3.4 KiB
Markdown
# Kindle Zotero Importer
|
|
|
|
Prototype importer for turning Kindle `My Clippings.txt` entries into a JSON import plan that Zotero can later write as native annotations.
|
|
|
|
The project intentionally keeps Zotero writes out of Python. Python parses, matches, and plans. Zotero JavaScript, and eventually a Zotero plugin, will perform annotation creation through Zotero's own APIs.
|
|
|
|
## Current Milestone
|
|
|
|
Parse Kindle clippings and emit a stable JSON preview:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer parse "/path/to/My Clippings.txt" --output clippings.json
|
|
```
|
|
|
|
Index Zotero items and PDF/EPUB attachments read-only:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer index-zotero --output zotero-index.json
|
|
```
|
|
|
|
Match parsed Kindle titles to Zotero items:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer match clippings.json zotero-index.json --overrides match-overrides.json --output matches.json
|
|
```
|
|
|
|
Generate reusable manual overrides for ambiguous/unmatched titles:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer generate-overrides matches.json --output match-overrides.generated.json --pretty
|
|
```
|
|
|
|
Apply reviewed overrides:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer match clippings.json zotero-index.json --overrides match-overrides.json --output matches.json
|
|
```
|
|
|
|
Keep confirmed mappings in `match-overrides.json`. The `match-overrides.generated.json` file is only a disposable review skeleton and can be regenerated from the current `matches.json` at any time.
|
|
|
|
If a matched Zotero item has multiple usable PDF/EPUB attachments, add the selected attachment to the same override entry:
|
|
|
|
```json
|
|
{
|
|
"clipping_title": "Example Kindle Title",
|
|
"resolution": {
|
|
"citation_key": "example2024",
|
|
"attachment_key": "ABC12345"
|
|
}
|
|
}
|
|
```
|
|
|
|
Use either `attachment_key` or `attachment_item_id`. Attachment choices are listed in `docs/mismatch-review.md` when an item is ambiguous.
|
|
|
|
For cumulative Kindle exports, rerun the whole pipeline against the latest `My Clippings.txt`. Previously confirmed overrides in `match-overrides.json` will be applied automatically to old and new clippings.
|
|
|
|
Review unresolved cases in `docs/mismatch-review.md` after each run. Prioritize:
|
|
|
|
1. `matched-title-no-attachment`: add/link the missing PDF or EPUB in Zotero.
|
|
2. `unmatched-title`: add a confirmed title mapping to `match-overrides.json`.
|
|
3. position failures: improve text/position matching or handle manually.
|
|
|
|
Regenerate the copy-friendly review report:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer review-mismatches import-plan.positioned.json matches.json --output docs/mismatch-review.md
|
|
```
|
|
|
|
Each reviewed title includes a YAML-style block with standalone keys such as `clipping_title`, `citation_key`, `zotero_item_id`, `zotero_key`, and `override_entry` for easy copying.
|
|
|
|
Generate a preliminary import plan for matched titles:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer plan clippings.json zotero-index.json matches.json --output import-plan.json --pretty
|
|
```
|
|
|
|
Position annotations and export the Zotero writer plan:
|
|
|
|
```sh
|
|
python -m kindle_zotero_importer position-epub import-plan.json --output import-plan.epub.json --pretty
|
|
python -m kindle_zotero_importer position-pdf import-plan.epub.json --output import-plan.positioned.json --pretty
|
|
python -m kindle_zotero_importer finalize import-plan.positioned.json --output import-plan.final.json --pretty
|
|
```
|
|
|
|
## Safety Rule
|
|
|
|
Do not write directly to `zotero.sqlite`. Use read-only SQLite access for indexing and Zotero's JavaScript API for writes.
|