Unearthed · Reading guides
Updated
Sync KOReader highlights to Obsidian, Craft or Notion
The Unearthed KOReader plugin sends your highlights and notes wirelessly to Local or Online. From Local, you can export to Obsidian or Craft. Online works with the Obsidian plugin, syncs books to Notion, and sends daily reflections to Supernotes. Capacities is coming soon.
Set up the KOReader plugin
Follow the plugin’s installation instructions on GitHub. You need to be reading in KOReader, rather than the default reader that came with your Kindle or Kobo.
- Install Unearthed.koplugin in KOReader’s plugins folder and restart KOReader.
- Enable Unearthed in Plugin Management if needed.
- Set Book Location to the folder containing your books and their .sdr folders, where KOReader saves highlights and reading progress.
- For Online, enter the Unearthed API key and User ID. For Local, copy the connection URL and Local Secret from your desktop setup.
- Close the current book so KOReader saves its highlights and notes, then use Send Books and check the received highlights.
Keep the connection working
For Local, keep the desktop app running and make sure your reader can connect to that computer. Copy the connection details from Local settings. Online syncing requires internet access. Startup and hourly sync options are available in the plugin.
Example: a KOReader book into an Obsidian vault
You’ll need KOReader installed on your reader and Unearthed Local running on your computer. Connect both devices to the same local network, then follow these steps to send a highlight to Obsidian.
- Open a book in KOReader, add a short highlight and a note, then close the book so its metadata is saved.
- In Local, save a secret under API Endpoint and copy the displayed connection URL. Keep Local running.
- In KOReader, open Tools → Unearthed → Local Settings. Enter that URL and the same secret; confirm the book is under General Settings → Book Location.
- Choose Send Books. Your book, highlight and note should now appear in Local.
- In Local, select your Obsidian vault and export the book. Check the Markdown note, then repeat with one additional highlight.
If a highlight is missing
Keep the books you want to sync in the folder you chose during setup. Close the book before syncing so KOReader saves your latest highlights. If you read the same title in Kindle and KOReader, check that both sets of highlights appear under the right book.
KOReader connection errors and quick checks
If you’re syncing to Local, start by checking that your reader can reach the computer and that the connection details match Local’s settings. For Online, check the API key and User ID instead.
| Problem | Check first |
|---|---|
| Unearthed is missing from the Tools menu | Keep the Unearthed.koplugin folder inside koreader/plugins, restart KOReader and check Plugin Management. |
| Connection refused or timed out | Keep Local running; check Wi-Fi, the displayed desktop address, guest network isolation and firewall access for the app. |
| Authentication error with Local | Save the secret in Local and use exactly the same Local Secret in KOReader. An Online API key is not the Local secret. |
| Only some books arrive | Check the configured Book Location and its metadata folders; close the current book before sending. |
| Sync stops after a network change | Copy the current connection URL from Local again; the computer's network address may have changed. |
Can I use the stock Kindle or Kobo reader instead?
The plugin reads highlights made in KOReader. It won’t pick up highlights from the reading app that came with your Kindle or Kobo. For Kindle books that appear in Amazon Kindle Notebook, use Unearthed’s Kindle connection instead. If you haven’t installed KOReader yet, check its device support and installation instructions first.
Documentation and links