# Octavo

**Read EPUB and PDF books in Obsidian, with highlights that live in your vault as linked Markdown.**

Octavo is a calm, full-featured book reader for Obsidian on desktop, iPhone, iPad and Android.

- **EPUB, PDF, MOBI, AZW3, FB2 and CBZ**: themes, fonts and spacing, page turns, two-page spreads, and a full-screen focus mode.
- **Highlights are notes.** One tap saves a highlight to the book's note as Markdown, with a deep link back to the exact passage.
- **Your notes in the margins.** Any note that links into a book shows up in the text. Hover over it to preview.
- **PDF++ links keep working.** Importers bring in highlights from Annotator, Weave, Elton, Kindle, KOReader, Readest and others.
- **A real library**: covers, Continue Reading, shelves and collections, built on your notes so they work with Bases and search.
- **Read-aloud** with your system voices, plus optional AI (your own API key or a local model through Ollama).
- **Goals and streaks** if you want them, logged to your daily note. Nothing leaves your device.

Website: https://octavo.devformat.tools

## Install

In Obsidian, go to **Settings → Community plugins → Browse**, search for **Octavo**, then select **Install** and **Enable**.


## Moving from PDF++ or Annotator

- **PDF++ links keep working.** `[[book.pdf#page=12&selection=…&color=…]]` and region embeds (`#page=…&rect=…`) open in Octavo at the same place, and highlights are drawn back onto the page.
- **Annotator highlights** come across with *Import highlights → Annotator* (colours and comments included).
- **Make Octavo your PDF viewer:** Settings → Octavo Reader → Library → "Open PDFs in Octavo". Your PDF files are never modified.
- **What differs:** Octavo stores highlights in the book's Markdown note (one callout per highlight) instead of inside the PDF, and adds a library, read aloud, phone layouts and EPUB in the same reader.

Full guide: https://octavo.devformat.tools/moving-from-pdfplusplus.html

## On mobile (iPhone, iPad, Android)

Obsidian keeps plugin icons in the **ribbon menu**: tap the **Menu** button at the bottom right. To show Octavo
there, open Settings → Appearance → Ribbon menu → Manage and turn on "Octavo library". You can also run
**"Octavo Reader: Open library"** from the command palette, or simply tap any EPUB or PDF in your files.

## Beta testing

Want new builds before everyone else? Install the **BRAT** plugin, choose "Add beta plugin" and enter
`meaLuda/OctavoRelease`. Beta builds are marked as pre-releases and never reach directory installs.
If something looks wrong on your phone, run **"Octavo Reader: Copy mobile diagnostics"** and paste the report
into an issue.

## Octavo Cloud (optional)

The reader is free and works fully offline. **Octavo Cloud** is an optional paid subscription for hosted services that cost money to run:

- a cloud library that keeps books outside your vault
- Send-to-Octavo email inbox
- OCR for scanned PDFs
- natural neural voices
- KOReader progress sync
- hosted AI, on the Cloud + AI plan

Plans and prices are on the website. No free feature will ever be moved behind the paywall.

## Disclosures

- **Payments.** Octavo Cloud features require a paid subscription. All reader features are free.
- **Account.** Octavo Cloud features need an Octavo account (email sign-in code, no password). The reader needs no account.
- **Network use.** Octavo makes network requests only when you use these features:
  - **Octavo Cloud** (`octavo.devformat.tools`): signing in, checking your plan, uploading and downloading cloud-library books, OCR and natural-voice jobs, and checkout.
  - **AI providers you configure yourself**: Anthropic, OpenAI or a local Ollama server, with your own key.

  Nothing is sent in the background.
- **No telemetry, no ads.** Octavo collects no usage data and shows no advertising.
- **Local storage.** Covers, tables of contents and book caches are kept in Obsidian's per-device browser storage (IndexedDB) and are never synced. Your highlights, notes and progress are plain files in your vault.
- **Files outside the vault.** Octavo does not read or write files outside your vault.
- **Why it lists vault files.** The library finds your books by listing the vault's EPUB and PDF files, and links highlights to notes. File contents are only read for books you open.
- **Clipboard.** Only written when you choose a Copy action (for example "Copy link" on a highlight); Octavo never reads your clipboard.

Privacy policy: https://octavo.devformat.tools/privacy.html · Terms: https://octavo.devformat.tools/terms.html

## Support

Email **eliud@munyala.pro** or open an issue in this repository.

## Source and licence

Octavo is open source under the **GNU Affero General Public License v3.0 or later** ([LICENSE](LICENSE)).
Copyright © 2026 Munyala Eliud (MEA Tech). Third-party components and their licences are listed in
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

Octavo Cloud is a separate, optional hosted service that the plugin talks to over HTTPS; its server is not
part of this repository.

Build it yourself (Node 22+):

```
npm ci
npm test
npm run build        # → packages/plugin/dist/main.js, styles.css, manifest.json
```

Every release is built from this repository by GitHub Actions and carries a signed build attestation
(`gh attestation verify main.js --repo meaLuda/OctavoRelease`).