README file from
Github
An Obsidian plugin that utilises the fantastic highlight handling of BookOrbit and syncs them to Obsidian. I have taken inspiration from the official Readwise plugin on most functionality, but tweaked for self-hosted BookOrbit users.
Features
- One-way highlight and annotation sync from BookOrbit to Obsidian.
- One note per book.
- Incremental sync for new highlights.
- Manual and optional automatic sync.
- API key authentication, with username/password login when no key is configured.
- Option to add custom frontmatter to all synced notes.
- Option to pull extra metadata (Highlight time, highlight colour, chapter, etc.).
- Reader deep links.
- Download covers option.
- Colour-to-tag mapping.
- Sync BookOrbit personal reviews.
- Sync finished books with no highlights.
- Highlight ordering by page number.
- Option to show the book cover at the top of each note, as well as in its properties.
Requirements
- The plugin requires the user to have a self-hosted BookOrbit instance.
- The plugin requires the user to have an account for that server.
Installation
Manual Installation
- Download
main.jsandmanifest.jsonfrom the latest release. - Create a new folder called
bookorbit-syncinside your vault's.obsidian/plugins/directory. - Copy the downloaded
main.jsandmanifest.jsoninto that new folder - In Obsidian, go to Settings → Community plugins and click Reload plugins.
- Find BookOrbit Sync in the list and toggle it on.
- Click the settings (cog) icon next to it to configure your BookOrbit server URL and API key, or your username and password.
API key authentication
Create a key in BookOrbit under Settings > You > API keys, then paste it into the plugin's API key setting. A read-only key with access to the libraries you want to sync is sufficient; no additional key permissions are needed. Creating keys requires the Create API keys permission on your account.
When an API key is configured, the plugin uses it instead of username/password login for both manual and automatic sync. Clear the key to use username/password login again. An invalid, expired, or revoked key causes sync to fail; the plugin does not fall back to password login.
The key is saved in Obsidian's plugin settings, like the existing password, and is not encrypted. Do not share the plugin's data.json file.
The plugin is also available to install from Obsidian Community Plugins here.
Known Limitations
I don't want to edit notes that have already been synced, so a lot of settings changes only apply to a fresh sync.
Next Features
- Per-book exclude list
- Format and styling templates
Privacy & Network Use
This plugin connects to the BookOrbit server URL you provide in settings, using your API key or username and password, to fetch your own highlights, annotations, personal reviews, and book covers. No data is sent to any third party or any server other than the one you configure.
License
This project is licensed under the GNU General Public License v3.0.