# Kobo Note Sync

[繁體中文](https://github.com/KennKyou/obsidian-kobo-note-sync/blob/main/README.zh-TW.md)

An Obsidian plugin that imports highlights and annotations from your Kobo e-reader into Obsidian notes.

## Features

- Import highlights and annotations from Kobo Desktop App's SQLite database or a custom Kobo SQLite file
- Customizable note and highlight templates using [Eta.js](https://eta.js.org/) syntax
- Append-only sync — existing highlights in Obsidian are preserved even if deleted on Kobo
- Rich metadata support (23 book variables + 5 highlight variables)
- Cross-platform: macOS and Windows
- i18n: English and Traditional Chinese (follows Obsidian language setting)

## How It Works

```
Kobo Device / App → Kobo Cloud → Kobo Desktop App → Kobo.sqlite → This Plugin → Obsidian Notes
Kobo Device → copied KoboReader.sqlite → This Plugin → Obsidian Notes
```

The plugin can read the local `Kobo.sqlite` database created by the Kobo Desktop App, or a Kobo SQLite database file you copied to a path of your choice, and generates Markdown notes in your vault.

## Installation

### Manual Installation

1. Download `main.js` and `manifest.json` from the [latest release](https://github.com/KennKyou/obsidian-kobo-note-sync/releases)
2. Create a folder `kobo-note-sync` in your vault's `.obsidian/plugins/` directory
3. Copy the downloaded files into that folder
4. Restart Obsidian and enable the plugin in Settings → Community Plugins

### Prerequisites

- For Desktop App sync: [Kobo Desktop App](https://www.kobo.com/desktop) installed and signed in with your Kobo account
- For custom SQLite sync: copy the Kobo SQLite database file from your device, such as `.kobo/KoboReader.sqlite`, to a stable local path

## Usage

1. In plugin settings, choose a sync source: **Kobo Desktop App** or **Custom SQLite file**
2. Confirm the database path for that source. In **Custom SQLite file** mode on macOS or Windows, you can use **Detect Kobo reader** to fill the path automatically.
3. Open Command Palette (`Cmd/Ctrl + P`) and run **Kobo Note Sync**
4. Or click the book icon in the left sidebar

Highlights will be created as Markdown files in the configured output folder (default: `Kobo Note Sync/`).

## Privacy

This plugin reads the local Kobo SQLite database selected in settings and creates or updates notes in your Obsidian vault. It does not send your reading data to any external server.

## Third Party Notices

This plugin includes `sql.js`, which is licensed under the MIT License. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Settings

| Setting | Description |
|---------|-------------|
| **Sync source** | Choose Kobo Desktop App or a custom SQLite file |
| **Kobo Desktop database path** | Path to `Kobo.sqlite`. Auto-detected based on your OS. |
| **Custom database file path** | Path to a copied Kobo SQLite database, such as `.kobo/KoboReader.sqlite` |
| **Detect Kobo reader** | Finds `/Volumes/*/.kobo/KoboReader.sqlite` on macOS or `?:\.kobo\KoboReader.sqlite` on Windows and fills the custom database path |
| **Output folder** | Folder in your vault for highlight notes |
| **Note template** | Eta.js template for each book note |
| **Highlight template** | Eta.js template for each highlight |

### Default Database Paths

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Kobo/Kobo Desktop Edition/Kobo.sqlite` |
| Windows | `%LOCALAPPDATA%\Kobo\Kobo Desktop Edition\Kobo.sqlite` |

## Templates

Templates use [Eta.js](https://eta.js.org/) syntax: `<%= it.variableName %>` for output, `<% if (it.condition) { %>` for logic.

### Note Template Variables

| Variable | Description |
|----------|-------------|
| `it.bookTitle` | Book title |
| `it.bookAuthor` | Author |
| `it.publisher` | Publisher |
| `it.isbn` | ISBN |
| `it.series` | Series name |
| `it.seriesNumber` | Series number |
| `it.subtitle` | Subtitle |
| `it.language` | Language |
| `it.description` | Book description (HTML stripped) |
| `it.progress` | Reading progress % |
| `it.status` | Reading status (`unread` / `reading` / `finished`) |
| `it.numPages` | Number of pages |
| `it.wordCount` | Word count |
| `it.averageRating` | Average rating on Kobo |
| `it.ratingCount` | Rating count |
| `it.timeSpentReading` | Time spent reading (seconds) |
| `it.timesStartedReading` | Times started reading |
| `it.dateAdded` | Date added to library |
| `it.dateCreated` | Book creation date |
| `it.lastRead` | Last read date |
| `it.lastFinished` | Finished reading date |
| `it.highlightCount` | Number of highlights |
| `it.highlights` | Rendered highlights content |

### Highlight Template Variables

| Variable | Description |
|----------|-------------|
| `it.highlightText` | Highlighted text |
| `it.annotation` | Your note/annotation |
| `it.dateCreated` | Highlight date |
| `it.chapter` | Chapter title |
| `it.chapterProgress` | Progress within chapter (0-1) |

### Example Templates

**Note template:**

```
---
title: "<%= it.bookTitle %>"
author: "<%= it.bookAuthor %>"
publisher: "<%= it.publisher %>"
last_read: <%= it.lastRead %>
highlight_count: <%= it.highlightCount %>
source: Kobo
---
<%= it.highlights %>
```

**Highlight template:**

```
*<%= it.dateCreated %>*<% if (it.chapter) { %> | <%= it.chapter %><% } %>

> <%= it.highlightText %>
<% if (it.annotation) { %>
**Note:** <%= it.annotation %>
<% } %>
---
```