Book Note

Non-invasive reading annotation plugin for Obsidian. Annotate PDF and EPUB in one place — highlights, notes, and tags live in separate sidecar files, so your original documents are never modified.

中文文档

Why Book Note

Most annotation tools mutate your source files. Book Note takes the opposite approach: every highlight, note, and reading-progress record is written to a sidecar Markdown file next to your vault's config, while the original document stays byte-for-byte intact. Rename, move, or delete a source file and the plugin migrates its annotations with it.

It started as a Markdown/PDF highlighter and grew into a full reading workspace focused on PDF and EPUB:

• EPUB reading powered by the foliate-js engine
• One unified sidebar that aggregates annotations across PDF and EPUB
• Excerpt export and bidirectional deep links (obsidian://book-note) that jump back to the exact highlight

Features

EPUB reading (foliate-js engine)

• Full reading experience — pagination / scrolling, font-size control, and 6 reading themes (Follow Obsidian, White, Warm, Eye-care Green, Parchment, Night).
• 6-color highlight + idea notes — select text to open a floating toolbar; draw a highlight or attach a thought.
• In-page full-text search — search the current chapter from the toolbar.
• Reading progress — auto-saved position, elapsed reading time, and a remaining-time estimate.
• Broad format support — foliate-js natively reads EPUB, MOBI, AZW3, FB2, CBZ, and TXT.

Unified annotation sidebar

• One panel for all formats — PDF and EPUB annotations converge in a single overview.
• Filter & search — filter by color, type, or semantic tag; keyword-search annotation content.
• Semantic tags — ships with Insight, Question, and Reminder; enable up to 5 tags, rename them, reorder, disable, and assign custom preset icons.
• Inline editing — edit a thought or add a note right inside the panel.
• Jump back — click a card to return to the original spot (PDF page / EPUB CFI).
• Export — Markdown summary, color-grouped export, or reading-notes layout.

Unified export & bidirectional deep links

• Export annotations — one "Export annotations" action at the bottom of the sidebar exports PDF and EPUB marks together.
• Unified deep links — both excerpts and sidebar cards produce an obsidian://book-note link that returns to the exact PDF or EPUB annotation.
• Backward-compatible backlinks — hidden anchor points from older EPUB/PDF exports keep working after upgrade.

PDF annotations

• Overlay highlight rectangles + sticky notes.
• Selection detection with color coding.
• All marks flow into the unified sidebar.

Note: Book Note annotates PDF and EPUB files only. Markdown files in your vault are not annotated by this plugin.

Installation

Via BRAT (recommended)

1. Install the BRAT plugin.
2. BRAT → Add Plugin → enter the repository: hellokunzai/obsidian-book-note.
3. Enable Book Note after installation.
4. Important: after an update, fully quit and restart Obsidian (a plugin reload is not enough).

Manual

1. Download main.js, manifest.json, and styles.css from the Releases page.
2. Place them in <vault>/.obsidian/plugins/book-note/.
3. Settings → Community plugins → enable Book Note.

Opening EPUB files

Obsidian hides unknown extensions by default. To show .epub in the file explorer:

• Settings → Files & Links → enable Detect all file extensions.

Settings

Configure under Settings → Book Note:

Commands & hotkeys

Mod maps to Ctrl on Windows/Linux and Cmd on macOS.

Data storage

All annotation data lives in sidecar files. The Sidecar location setting (Settings → Storage) controls where they go:

• Specified folder (default): sidecars collected under a configurable vault-relative directory (default <vault>/booknote/). Name = path segments joined by -, original filename + extension, then .md.
• Next to source file: each sidecar sits beside its source file as <source>.md.

The sidecar index (which file maps to which sidecar) is stored inside the plugin's own data.json — there is no separate index.json file.

• One sidecar file per annotated file, stored as Markdown (human-readable). Metadata and reading progress live in YAML frontmatter and each annotation becomes its own heading.
• Stores highlights, notes, reading progress, plus legacy fields kept for backward compatibility.
• Your original documents are never touched — delete a sidecar file to erase that file's annotations.
• Change the storage location in Settings → Storage, then click Migrate data to move existing sidecars to the new location.

# Specified folder mode (default):
booknote/                     # default folder (configurable)
  papers-example.pdf.md         # PDF annotations (Markdown)
  books-novel.epub.md           # EPUB annotations (CFI anchors + reading progress)

# Next to source file mode:
books/novel.epub                # your source EPUB
books/novel.epub.md             # its sidecar, next to the source
papers/example.pdf              # your source PDF
papers/example.pdf.md           # its sidecar, next to the source

Deep links

Book Note emits links of the form:

obsidian://book-note?file=<vault-relative-path>&id=<annotation-id>
obsidian://book-note-epub?file=<vault-relative-path>&cfi=<epub-cfi>   # legacy EPUB links

Clicking a link opens the file and scrolls to the exact annotation.

Technical architecture

• EPUB engine: foliate-js 1.0.1 — a single engine covering multiple formats natively.
• Rendering: a foliate-view custom element embedded in an Obsidian leaf, with CSP / sandbox patches for the desktop runtime.
• Data layer: sidecar Markdown files via AnnotationStore, unified into a FileAnnotationDocument model.
• Annotation sync: renderedAnnotationMeta tracks the foliate highlight layer so add/remove operations refresh immediately.
• Non-invasive by design: every annotation is an overlay; the source text is never rewritten.

Development

npm install
npm run dev      # development build (with sourcemap)
npm run build    # production build

Type-check:

npx tsc --noEmit

Copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/book-note/ to test in a vault.

License

MIT

Acknowledgements

• foliate-js — EPUB rendering engine.
• obsidian-weave-reader — foliate integration, footnote / search / canvas references.
• ob-epub-reader — excerpt back-link and deep-link approach.
• Axl Light — original project basis.