Annotations

Highlights, notes, reactions, and replies — kept in a plain-text sidecar next to the file.

Creating annotations

• Highlight Selection (⌘⇧H) — colour-mark the current selection. No note attached.
• Add Note to Selection… (⌘⇧N) — highlight and attach a note in the sidebar.
• Both work on Markdown and on text-based PDF.

The annotations sidebar opens automatically the first time you annotate. Toggle it manually with ⌘⇧A.

Threads and reactions

Each annotation can carry a thread of replies, and each annotation or reply can carry reactions.

• Type into the card to add a reply.
• Click the reaction button on a card or reply to add 👍, ❤️, or 😄. Click again to remove.
• The card shows who added each reaction.

The sidecar file

Mindle never modifies the source file to record annotations. Instead, annotations live in a hidden JSON sidecar beside the source:

~/notes/paper.md
~/notes/.paper.md.mindle.json

URL-fetched and clipboard tabs use content-addressed sidecars under ~/Library/Application Support/Mindle/.

The sidecar is plain JSON. It survives independently of Mindle and is intended to be readable, diffable, and version-controllable.

Anchors and drift

Annotations are addressed by anchor: the surrounding text plus an occurrence index in case the same phrase appears more than once. When the source file changes, Mindle re-anchors on next open; if a passage can no longer be located, the annotation is shown as orphaned in the sidebar but never lost.

Identity

Each annotation and reply records the author. On first launch Mindle prompts for a display name; you can change it later. Annotations created via the MCP socket record the agent's identifier separately — see Agents.

Exporting

File → Export Annotations… (⌘⇧E) writes annotations to disk in one of two formats:

• Markdown. Each annotation as a heading, with the highlighted passage as a blockquote and notes/replies as paragraphs underneath. Ready to paste into another document.
• JSON. The same shape as the sidecar — suited for programmatic consumption.

Selecting from a card

Annotation card text is selectable. Click the jump-arrow on a card to scroll the reader to the highlighted range.

← Back to Mindle