🔗Annotations

The annotations sync feature uploads highlights and notes you make in KOReader to your BookLore library. Annotations are deduplicated - the same highlight is never uploaded twice.

🔗Prerequisites

Annotation sync requires:

• The BookLore account credentials configured for Bearer token authentication. See Authentication.
• Sync highlights and notes toggled on in Settings → Annotations.

🔗What gets synced

🔗Notes destination

🔗In book

Notes are stored as in-book annotations directly attached to the highlighted passage. This makes them visible when reading the book in BookLore's built-in reader.

This mode requires the plugin to convert KOReader's internal position format (xpointer) to a standard EPUB CFI (Canonical Fragment Identifier) string, which BookLore uses to anchor the annotation to the correct location in the document.

API endpoint used:

POST /api/v1/annotations

EPUB CFI generation is only supported for EPUB files. For PDF and comic formats, use "In BookLore" mode. PDF files receive a mock CFI placeholder that allows BookLore to accept the annotation without crashing, but precise in-reader positioning is not available.

🔗In BookLore

Notes are stored as standalone book notes visible on the BookLore book page (the web UI book detail view), not inside the reader. The chapter title is used as the note title.

API endpoints used:

POST /api/v2/book-notes   (in-book notes with position)
POST /api/v1/book-notes   (standalone BookLore notes)

This mode works for all file formats.

🔗Both

Sends annotations to both destinations simultaneously - stored as in-book annotations (EPUB CFI) and as standalone BookLore notes. Use this if you want your highlights accessible from both the reader view and the book detail page.

When using "Both" with PDF files, the in-book copy uses the mock CFI placeholder, while the BookLore note is stored normally.

🔗EPUB CFI generation

For EPUB files, the plugin generates a Canonical Fragment Identifier (CFI) for each highlight, allowing BookLore to display the annotation at the precise location in the document.

flowchart TD
    A["EPUB file opened"]
    B["Read OPF spine and build spine item map"]
    C["Parse KOReader xpointer position"]
    D["Combine spine index, element path, char offset"]
    E["Output EPUB CFI string"]

    A --> B --> C --> D --> E

This happens entirely on-device - no server-side processing required.

🔗Highlight colours

KOReader supports named highlight colours. The plugin maps these to the nearest hex colour used by BookLore's annotation system:

🔗Upload strategy

🔗Upload on session end

Annotations are checked and uploaded after every valid reading session. Only annotations not yet recorded in the synced_annotations deduplication table are sent.

This is the recommended strategy for most users - your annotations are always up to date on the server without any manual action.

🔗Upload on suspend (sleep)

In addition to the normal session-end trigger, annotations and bookmarks are also queued when the device suspends (goes to sleep), regardless of the upload strategy setting. This ensures that any highlights or notes added just before the screen turns off are not lost if the book is not explicitly closed.

The plugin captures annotations at suspend time by reading directly from KOReader's in-memory ReaderAnnotation module. Because KOReader only flushes annotation data to the .sdr sidecar after the document is closed - not on suspend - reading from disk at that point would return stale or incomplete data. The in-memory read avoids this race condition entirely.

Note: The suspend path only queues annotations; it does not attempt a network upload on its own. If Force push on suspend is enabled (see Sync Settings), the pending queue will be uploaded at the same time.

🔗Upload on read complete

Annotations are only uploaded when reading progress reaches 99% or more. This sends all annotations for the book in one batch when you finish it, rather than incrementally throughout reading.

Use this if you prefer not to sync partial highlights (e.g., you frequently highlight and then delete).

Note: Even with this strategy selected, annotations are still captured and queued at suspend time to prevent data loss. They are held locally until the 99% threshold is reached or a manual sync is triggered.

🔗Bookmark sync

In addition to highlights and notes, the plugin can sync bookmarks - position markers you add in KOReader without selecting text.

When bookmark sync is enabled, the plugin:

1. Reads KOReader's bookmark list for the current book.
2. Calculates a CFI position for each bookmark.
3. Uploads new bookmarks to BookLore via:

   POST /api/v1/bookmarks
   

4. Records the uploaded bookmarks in the synced_bookmarks deduplication table.

Bookmark sync is triggered at the same time as annotation sync (after a qualifying reading session, at read complete, or when the device suspends - whichever applies to your upload strategy setting).

To enable bookmark sync, toggle on Sync bookmarks in:

Tools → BookLore Sync → Sync Settings → Annotations Sync → Sync bookmarks

🔗Deduplication

The synced_annotations table records every annotation that has been successfully uploaded:

• A unique identifier derived from the book ID, annotation position, and text content.
• The timestamp of the upload.

On each sync, only annotations not found in this table are uploaded. This prevents duplicate annotations from appearing in BookLore if you sync the same book on multiple occasions.

🔗Pending annotations

If an annotation upload fails, it is stored in the pending_annotations table and retried on the next sync trigger. You can see the count of pending annotations in:

Tools → BookLore Sync → Manage Sessions → View Details