Skip to content

File Sync

Jump to bottom
Josh Glazer edited this page Aug 19, 2026 · 3 revisions

File Sync

Enhanced Notes allows you to synchronize your Zotero notes directly with Markdown (.md) files on your local disk. This makes it easy to edit your notes using external markdown editors (like Obsidian) and have the changes flow bidirectionally.

Core Features

1. Bidirectional Background Sync

  • Local File Writing: Notes are exported to .md files on your local drive.
  • Background Polling: Enhanced Notes re-checks the exported files on a timer (default: every 30 seconds). There is no filesystem event watcher; instead it compares each file's modification time (stat-gating) and only re-reads files that actually changed, so idle files cost almost nothing.
  • Automatic Imports: Even while Zotero is unfocused, modifications made in your external markdown editor are picked up on the next tick and synced back into Zotero.

2. Automatic 3-Way Merge

When edits occur simultaneously in both Zotero and the local file:

  • Non-Conflicting Edits: Enhanced Notes executes an automatic 3-way merge to integrate changes from both sides seamlessly without user intervention.
  • Conflict Handling: If conflicting edits occur on the exact same line/section, a diff view is surfaced to let you review and resolve the conflict manually.

3. Keystroke Protection (Focus Guard)

To prevent incoming syncs from overwriting text while you are actively typing inside Zotero:

  • If a note is currently open and focused in the Zotero editor, sync updates are temporarily paused.
  • The note will only refresh once Zotero detects that you have stopped typing for a few seconds, ensuring that your active edits are never overridden by external disk changes.

Managing Sync

Sync interval (syncPeriodSeconds, default 30 s) and the background-sync toggle are set in Zotero → Settings → Enhanced Notes (the plugin's preferences pane), not in the Sync Manager.

The Sync Manager (open with ⌃⌥M or from the Tools menu) is for managing which notes are synced:

  • Track which notes/files are currently synced and refresh their status.
  • Sync or un-sync individual notes.
  • Detect already-synced .md files in a chosen folder and re-link them.
  • Clean up orphaned sync entries (whose files no longer exist).

Force an immediate synchronization of all notes any time with ⌃⌥S.

Clone this wiki locally