Obsidian Stats logoObsidian Stats

Book Note

by hellokunzai
5
4
3
2
1
Score: 51/100
Install Code

Description

Reviews

No reviews yet.

Stats

1
stars
304
downloads
0
forks
26
days
26
days
26
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
125
commits

Latest Version

0.27.4
a month ago

Changelog

See all version on GitHub

README file from

Github

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.

中文文档

Highlight in reading view Sticky notes overview

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:

Setting Description
Default highlight color The color applied to new highlights.
Default author Signature attached to your annotations.
Migrate annotations on rename When a source file is renamed or moved, migrate its sidecar annotations and update links.
Annotation tags Manage semantic tags — enable up to 5, rename, reorder, disable, assign a preset icon, or restore defaults. Duplicate names are blocked (whitespace / full-vs-half-width / case are normalized).
EPUB font size Base body font size in px (12–28). Applies when you reopen the book.
EPUB reading theme One of 6 themes.
EPUB flow mode Paginated (page-turn) or Scrolled (continuous).
EPUB highlight style Fill / Underline / Wavy underline.
PDF reading progress Record the current page and reading progress. Disabling does not delete existing progress.

Commands & hotkeys

Command Hotkey Action
Highlight selection Ctrl/Cmd+Shift+H Highlight the selected text (PDF; EPUB uses its in-reader toolbar).
Add sticky note to selection Ctrl/Cmd+Alt+M Attach a thought/note to the selection.
Open annotation overview — Open the Book Note sidebar.
Open EPUB bookshelf — Browse e-books inside the vault.
Show PDF outline — List the current PDF's table of contents.
Test Book Note storage — Verify write access to the sidecar directory.

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

Sponsors