Annotations

Highlight and annotate PDFs, web pages, and EPUBs; everything collects in one place, exports, and can be read by agents.

This page covers the mechanics — where annotations are stored, how they anchor, where the boundaries are. For where the UI lives, see Highlights.

Supported formats

Format	Highlight	Margin note	Sticky note
PDF	✅	✅	✅
Web pages (.html / .mhtml)	✅	✅	—
EPUB	✅	✅	—

Markdown, images, audio, and video are not annotatable. That's a deliberate scope decision: their anchoring models have nothing to do with text selection, and forcing one model over all of them would distort the data structure.

Kinds of annotation

Markup (text-anchored) — attached to a span of selected text, in four styles:

Style
Highlight
Underline
Strikethrough
Squiggly

Six colors: yellow · orange · green · cyan · pink · magenta. What a color means is entirely up to you — Scholardo doesn't impose "yellow = important, red = doubtful" semantics. These are the standard fluorescent colors common PDF tools use.

Sticky Note — PDF only. A free-floating marker pinned anywhere on a page, not attached to any text. Good for "the y-axis units on this figure are wrong" — comments that aren't about a particular sentence.

Every markup annotation can carry a margin note: what you thought about that passage.

Where they're stored

Annotations are not written into the original file. They live in a separate file inside the project:

<project>/.scholardo/annotations/<sha-prefix>/<sha>.json

The sha is a hash of the file's contents, not its path. Two direct consequences:

• Rename or move a file and the annotations follow — identity is content, not location
• The original file stays clean — you can send that PDF to someone as-is, with none of your markup attached

The flip side: change the content and they lose their home

Re-download a differently-typeset edition of a PDF and the content SHA changes, so old annotations can't anchor to the new file. They aren't deleted — they're kept as orphan annotations in Highlights, just without the ability to jump back to the source.

Existing embedded PDF annotations

If your PDF already carries annotations made elsewhere (Preview, Adobe, Zotero), Scholardo imports them the first time it opens the file and manages them from then on. They're marked with an external origin, distinguishing them from ones you make in Scholardo (native).

Anchoring on the web and in EPUBs

Web pages and EPUBs have no page coordinate system like a PDF, so annotations anchor via text selectors: the selected text itself, some surrounding context, and a position within the document. Reopening re-locates them from those clues.

EPUB anchoring precision

EPUB annotations currently anchor by text selector; CFI is not implemented (the EPUB standard's canonical locator). That's fine for nearly all reading. If you hold several differently-sourced editions of the same book, cross-edition positioning may be off.

Licensing boundaries

Operation	Trial / valid license	After expiry
View existing annotations	✅	✅
Export annotations	✅	✅
Create / edit / delete	✅	❌

After expiry your annotations are completely unaffected — they display, read, and export as always. You just can't make new ones.

Exporting

Export from Highlights as Markdown or CSV, to the clipboard or to a file, for everything or just a selection.

You can also turn a batch of highlights straight into a note in Notes.

Agents are read-only

Agents get three annotation tools, all read-only:

Tool	Purpose
list_annotations	Every annotation on a document (by contentSha)
get_annotation	One by ID
search_annotations	By text or tag

There is no write tool, deliberately. Agents can work from your markup — "pull together what I highlighted about catalytic mechanisms across these five papers" is a fine request — but they can't mark things up for you, or change what you marked. Marking up stays yours.

Hypothesis sync

Annotations you made on the open web with Hypothesis can be synced in; see Highlights → Hypothesis sync. The sync is one-way (Hypothesis → Scholardo).

Multi-device caveat

Annotation files have no concurrency protection

Annotation sidecars are plain JSON files. If your project lives on iCloud / Dropbox and you annotate the same file on two machines at once, the later write wins and the other machine's changes are lost.

Single-machine use is unaffected. Across devices, the safe pattern is to close the project on one machine before opening it on the other.

See also

• Highlights — where the UI is, how to filter and export
• Preview Windows — per-format differences in annotating