# Sergius Kobo Annotations (Calibre Plugin)

**Sergius Kobo Annotations** is a Calibre plugin (fully compatible with both **Calibre Standard / Desktop** and **Calibre Portable** on Windows, macOS, and Linux) designed to intelligently extract notes and highlights from a Kobo e-reader (like Kobo Clara) and archive them in your preferred Calibre library. It enriches EPUB files and populates reading metadata without ever overwriting or altering your original books.

---

## 🏛️ Library Management: No forced names!

The plugin **DOES NOT enforce any fixed library name** and has no hardcoded paths.
Its operation is very simple: **it works directly on the library you currently have open in Calibre**.

### You decide the name and location:
You can name your library whatever you prefer:
- `Books Read`
- `Kobo Archive`
- `Notes Library`
- or any other name.

### Two separate libraries (recommended to avoid confusion):
Calibre allows you to manage multiple independent libraries:
1. **Main Library (Originals):** where you keep all your intact ebooks without modifications.
2. **Dedicated Library (Reads / Annotated):** a second library you create with your preferred name, to contain the files with yellow highlighted text, interactive footnotes, and read dates.

When you want to archive notes from your Kobo:
1. In Calibre, switch to your reading library (Library icon at the top > *Switch/create library*).
2. Click the **Sergius Kobo Annotations** button.
3. The plugin will read the Kobo and deposit the annotated books **exactly in the library you see on screen**.

---

## 🔄 No Overwriting: Incremental and Secure Archive

- **Identical Status:** If you connect the Kobo and a book has exactly the same notes previously archived, the plugin recognizes it via a cryptographic hash (SHA-256) and **skips the operation**, avoiding useless duplicates.
- **New Annotations:** If you continued reading and added new highlights or notes to the same book, the plugin **DOES NOT delete or overwrite the old version**. It creates a separate new entry with the new status and new date, allowing you to keep a history of your readings over time.

---

## 🎯 What the plugin does in detail

1. **Visual highlights in the text:**
   - Inserts real yellow highlights (`<span class="user-highlight">`) inside the EPUB.
   - Full support for both **KEPUB** (native Kobo spans) and **standard EPUB** (resolving UTF-8 byte offsets of Adobe RMSDK/point notation).
   - Perfect handling of overlapping annotations in the same paragraph.

2. **Footnotes with return to text:**
   - Every personal note is associated with a superscript number (e.g., `[1]`). Clicking it opens the note at the end of the chapter, with a *"Back to text"* link to resume reading.

3. **Annotations Index in the Table of Contents:**
   - Creates an `annotations.xhtml` page registered in both NAV (EPUB3) and TOC NCX (EPUB2): opening the book's index allows you to jump directly to each highlight.

4. **Automatic column creation (Zero configuration):**
   - On the first run on the open library, the plugin automatically creates the two necessary custom columns if they do not already exist:
     - `#date_read` (Date, format `dd/MM/yyyy`)
     - `#read_percentage` (Integer, format `{0}%`)
   - If they already exist, it reuses them without duplicating and without errors.

5. **Read date based on the '1 read' collection:**
   - A book is considered completed/archived when you place it in the **`1 read`** collection on your Kobo (even if you stopped halfway and decided not to continue).
   - For these books, the exact date of the last reading (`DateLastRead`) is recorded.
   - The percentage always records the actual progress (e.g., 45% or 100%).

6. **Automatic Kobo database backup:**
   - Every time you connect, it saves a dated copy of `KoboReader.sqlite` in the `.kobo_backup/` folder of the device.

---

## 🛠️ How to create a second Library in Calibre (if you want to separate archives)

On both Calibre Portable and Calibre Standard (desktop):
1. Click the library icon at the top (icon with books) > **Switch/create library...**
2. Select the option **"Create an empty library at the new location"**.
3. Choose where to place it and give it whatever name you want (e.g., `Books Read`, `Calibre annotated library`, etc.).
4. Click **OK**. From now on you can switch between libraries with a click.

---

## 🚀 Plugin Installation

1. Download `sergius.kobo-en-v1.zip` (**do not extract it**).
2. In Calibre go to **Preferences** (or `Ctrl + P`) > **Advanced** section > **Plugins**.
3. Click **"Load plugin from file"**, select the zip and confirm with **Yes**.
4. Restart Calibre.

---

## 📖 Daily Use

1. On your Kobo, move the books you consider read into the **`1 read`** collection.
2. Connect the Kobo to the PC with the USB cable and tap **"Connect"** on the e-reader screen.
3. Open Calibre in the library where you wish to save the annotated ebooks.
4. Click the **Sergius Kobo Annotations** button in the toolbar.
5. The plugin will read the Kobo and archive the annotated copies with notes, index, date, and percentage in the active library!

---
*Author: Sergio*  
*License: GPL v3*
