Sync your reading highlights and notes from Kavita to your Obsidian vault.
This plugin pulls all your annotations, highlights, and notes from Kavita and organizes them in your Obsidian vault. Choose between two export modes:
Organizes annotations as Root Folder / Series / Book.md. Each book gets its own markdown file with rich frontmatter for tags and linking.
Kavita Annotations/
├── The Great Gatsby/
│ └── The Great Gatsby.md
├── Foundation Series/
│ ├── Foundation.md
│ ├── Foundation and Empire.md
│ └── Second Foundation.md
└── Dune/
└── Dune.md
Example book file:
---
tags:
- kavita
- fiction
- classic
kavita_series_id: 42
kavita_chapter_id: 123
updated: 2025-12-19T10:30:00Z
---
# The Great Gatsby
**Series:** [[The Great Gatsby]]
**Author:** [[F. Scott Fitzgerald]]
## Annotations
#### Chapter: One
> In my younger and more vulnerable years my father gave me some advice...
*Note:* This opening is iconic
Page 3
---
> So we beat on, boats against the current...
Page 180All annotations in one markdown file, grouped by series and chapter.
---
tags:
- kavita
- annotations
updated: 2025-12-06T10:30:00Z
---
# Kavita Annotations
## The Great Gatsby
**Author:** [[F. Scott Fitzgerald]]
### Chapter 1
> In my younger and more vulnerable years...- Go to the Releases page
- Download
main.jsandmanifest.jsonfrom the latest release - In your vault, create the folder
.obsidian/plugins/kavita-to-obsidian/ - Copy both downloaded files into that folder
- Restart Obsidian
- Go to Settings → Community Plugins and enable "Kavita Sync"
Once accepted into Obsidian's Community Plugins directory, install via: Settings → Community Plugins → Browse → search for "Kavita Sync" → click Install → click Enable.
- Open Kavita and log in
- Click your profile icon → User Settings
- Go to 3rd Party Clients
- Copy your API key (or generate one if you don't have one)
- In Obsidian, go to Settings → Kavita Sync
- Enter your Kavita server URL (e.g.,
http://localhost:5000orhttps://kavita.example.com) - Paste your API key
- Adjust other settings as desired
| Setting | What it does | Default |
|---|---|---|
| Kavita URL | Your Kavita server address | - |
| API Key | Your Kavita API key for authentication | - |
| Export Mode | Choose between "Single file" or "Hierarchical folders" | Hierarchical folders |
| Output Path | Where to save annotations (single file mode only) | kavita-annotations.md |
| Root Folder | Root folder for book files (hierarchical mode only) | Kavita Annotations |
| Delete Orphaned Files | Remove files when annotations are deleted | Yes |
| Include Comments | Include your personal notes with highlights | Yes |
| Include Spoilers | Include highlights marked as spoilers | No |
| Include Tags | Generate Obsidian tags from genres | Yes |
| Tag Prefix | Prefix for generated tags (empty for no prefix) | (empty) |
| Include Wikilinks | Create links to author/series notes | Yes |
Option 1: Click the book icon in the left sidebar
Option 2: Press Ctrl/Cmd + P to open the command palette, then search for "Sync Kavita Annotations"
In hierarchical mode, each book becomes its own file in a folder structure. In single file mode, all annotations are saved to one file.
Hierarchical mode: Each book is its own note, perfect for Obsidian's graph view and backlinks:
See my highlights from [[The Great Gatsby]]Single file mode: Link to specific sections:
See my highlights from [[kavita-annotations#The Great Gatsby]]If you have notes for authors or series, the wikilinks will automatically connect:
**Author:** [[F. Scott Fitzgerald]] ← Links to your author note if it existsFor detailed solutions to common issues, see the Troubleshooting Guide.
Quick fixes:
| Error | Solution |
|---|---|
| Authentication failed | Regenerate your API key |
| Network error (404) | Check your Kavita URL |
| Connection refused | Ensure Kavita is running |
| No annotations synced | Create highlights in Kavita first |
This plugin connects to your self-hosted Kavita server to sync annotations. Here's what it does:
- Connects to: Your configured Kavita server URL only (no third-party services)
- Authentication: Sends your API key via HTTP header to authenticate with Kavita
- Data fetched: Annotation, series, and chapter data via Kavita's REST API
- No telemetry: The plugin does not collect analytics, usage data, or send information to any external service
Want to help improve the plugin? See CONTRIBUTING.md for development setup and guidelines.
MIT