Skip to content

About

Kobo highlight sync to hardcover.app

Topics

Resources

Stars

27 stars

Watchers

2 watching

Forks

Repository files navigation

Kscribbler

Sync your Kobo highlights to hardcover.app!

Here is an example for the book Crooked Kingdom by Leigh Bardugo:

K - Kobo|kepub Scribe - Someone who writes stuff to a new location

ps. add me on hardcover 🤓 https://hardcover.app/@countmancy

Installation

  1. Download and install nickelmenu
  2. Download the latest release of kscribbler from the releases page
  3. Install kscribbler on your Kobo:
    • Connect your Kobo to your computer and mount the device
    • Navigate to the .kobo directory on your Kobo (might need to show hidden files)
    • Copy the KoboRoot.tgz into this directory and unmount the device safely. This will trigger a reboot and upgrade.
  4. Remount the device and navigate to /mnt/onboard/.adds/kscribbler.
    • If you don't see this directory check for /mnt/onboard/.adds/kscribbler
  5. Copy the example config file: cp config.env.example config.env
  6. Connect to Hardcover, either:
    • Sign in (recommended): with WiFi on, open a book, tap the top of the screen and tap the K icon in the reading menu, then Sign in to Hardcover. Scan the QR code (or visit the link and enter the code), approve, then tap Continue. The token is saved to /mnt/onboard/.adds/kscribbler/token.json and refreshed automatically.
    • Personal access token: add it to HARDCOVER_API_TOKEN in config.env. A Hardcover Personal Access Token (PAT) with the necessary permissions (read:me, read:catalog, write:library) can be generated directly from this link.

Upgrade

From the main menu of your Kobo device open nickelmenu and select Upgrade Kscribbler to download and install the latest version.

The download is verified against the release's checksums.txt before it is installed.

Update channels / testing builds

  • UPDATE_CHANNEL in config.env picks what Upgrade Kscribbler installs: stable (default), testing, or a release tag such as v1.4.0 to pin or roll back.
  • testing is a rolling pre-release published by the Testing Build workflow. Run it from the Actions tab on any branch, or push to a test/** branch.
  • With the debug options visible (Toggle Visibility of Kscribbler Options), Kscribbler Install Testing Build and Kscribbler Reinstall Stable Build install that channel right away, even if it is already installed.
  • From a shell: /mnt/onboard/.adds/kscribbler/upgrade.sh [stable|testing|<tag>] [--force]

Usage

The K icon in the reading menu has Sign in to Hardcover and Sync highlights now.

Once installed nickelmenu should have a new entry in the right corner of reading view that will trigger a sync when clicked.

This will trigger kscribbler to generate its database of quotes and upload them to hardcover.app. WARNING: This will attempt to upload all quotes from all books on the device. If you want to tame this you will need to manipulate the kscribblerdb yourself. More info below.

The quotes are uploaded to hardcover.app based on the book's ISBN. See the note below or the troubleshooting section if quotes are not being uploaded.

  • If your book doesn't have an ISBN saved to the kobo device's database you can highlight the book's ISBN on its copyright page and kscribbler will attempt to parse it and save it to the book's metadata.
    • A note with kscrib:<you isbn number with no angle brackets can be added anywhere in the book to manually set the ISBN
    • Can be useful for sideloaded books

Configuration

All configuration is done via /mnt/onboard/.adds/kscribbler/config.env. See config.env.example for a template.

Variable Default Description
HARDCOVER_API_TOKEN (optional when signed in) Your Hardcover Personal Access Token (PAT). Can be generated with required scopes here
UPLOAD_ANNOTATIONS false Set to true to upload annotations (notes) alongside quotes. When enabled, the highlighted passage and your note are combined into a single journal entry separated by --- Personal Annotation ---
HARDCOVER_CLIENT_ID (built in) Override the OAuth client ID used by sign-in
PRIVACY public Privacy level for uploaded journal entries. Options: public, followers, private

Troubleshooting

  • Logs are stored in /mnt/onboard/.adds/kscribbler/kscribbler.log
  • If you are having issues with the quotes not being uploaded, check that hardcover.app has an edition for the ISBN.

Advanced Usage

  • The database of quotes is stored at /mnt/onboard/.adds/kscribbler/kscribblerdb
  • This is a sqlite database with two tables: books and quotes
  • You can manipulate this database directly if you want to control what gets uploaded by setting kscribbler_uploaded to 1 for quotes you don't want uploaded
  • telnet/ssh into the kobo is possible and allows for manually running kscribbler if so desired
  • From the main Kobo screen you can open nickelmenu and Toggle Visibility of Kscribbler Options to run the following commands:
    • kscribbler --init will initialize the database but not upload anything
    • kscribbler --mark-all-as-uploaded will initialize the database, mark all found quotes as upload but will not upload anything
      • Useful for testing/migrating
    • The initial output is displayed but truncated. Full output is in the log file

Contributing

  • Star the repository ⭐
  • File bug reports
  • Submit pull requests
  • Suggest improvements
  • Share the project with others if you find it useful

Check Out My Other Ebook-Related Projects

About

Kobo highlight sync to hardcover.app

Topics

Resources

Stars

27 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages