Skip to content

feat: automatic periodic bookmarks sync#247

Open
andreas13xxx wants to merge 2 commits into
SebastianMC:masterfrom
andreas13xxx:feat/automatic-bookmarks-sync
Open

feat: automatic periodic bookmarks sync#247
andreas13xxx wants to merge 2 commits into
SebastianMC:masterfrom
andreas13xxx:feat/automatic-bookmarks-sync

Conversation

@andreas13xxx
Copy link
Copy Markdown

@andreas13xxx andreas13xxx commented May 12, 2026

Summary

This PR adds automatic periodic synchronization of sorting bookmarks with the file explorer, addressing the feature requests in #108 and #192.

What it does

  1. Full bookmark sync (syncSiblings): A new method that enforces the correct file explorer order in bookmarks. Unlike the existing bookmarkSiblings (which only appends missing items), this method:

    • Reorders existing bookmark entries to match the current sorting order
    • Inserts new items at their correct position (not just appended at the end)
    • Removes orphaned entries (bookmarks for files/folders that no longer exist)
  2. Configurable auto-sync timer: A new setting Automatic bookmarks sync interval (in seconds). Set to 0 to disable (default). When enabled, the plugin periodically runs a full vault-wide bookmark sync.

  3. Immediate sync on file creation: When auto-sync is enabled, newly created files/folders are immediately synced into the correct bookmark position via a vault.on('create') handler.

  4. Manual recursive sync (context menu): A new context menu entry Sync bookmarks for sorting (recursive) that performs a one-shot full sync on a folder and all its descendants.

How to use

  1. Enable the Bookmarks integration in plugin settings (if not already enabled)
  2. Set the Automatic bookmarks sync interval to your desired value (e.g. 60 for once per minute)
  3. The plugin will now keep bookmarks in sync with your file/folder structure automatically

For manual one-shot sync: right-click any folder in File Explorer → Custom sort → Sync bookmarks for sorting (recursive)

Addressing concerns from #108 and #192

Sebastian raised several valid concerns about automatic bookmark synchronization:

"Keeping bookmarks in sync is technically not feasible"
The periodic full-sync approach sidesteps the event-based synchronization problems. Rather than trying to catch every individual file system event in real-time, we periodically reconcile the entire state. Missed events (e.g. during plugin startup) are corrected at the next sync cycle. The vault.on('create') handler provides near-instant sync for the most common case (new files).

"Duplicate bookmark entries when rearranging items"
The syncSiblings method completely replaces the bookmark list for each folder with the correct ordered set. Any duplicates or orphans are eliminated on every sync cycle.

"High implementation/maintenance effort due to Obsidian breaking changes"
This implementation reuses the existing plugin infrastructure exclusively (orderedFolderItemsForBookmarking, findGroupForItemPathInBookmarks, the existing bookmark data structures). No new Obsidian API dependencies are introduced. The maintenance surface is minimal: one new method in BookmarksPluginWrapper, a timer, and a create-event handler.

"Conflict with manual drag & drop ordering"
This is an inherent trade-off: when auto-sync is enabled, manually reordered bookmarks will be overwritten at the next sync cycle. This is by design — the setting is opt-in (disabled by default) and intended for users who want bookmarks to mirror the sorting spec automatically. Users who prefer manual bookmark ordering should leave the interval at 0.

Technical details

  • No performance concerns for typical vaults: the sync only writes to disk when triggered by the timer or create-event
  • The timer is properly cleaned up on plugin unload
  • Changing the interval in settings immediately restarts the timer (no reload required)

- Implement syncSiblings() to reorder bookmarks to match file explorer order and remove orphaned entries

- Add configurable sync interval setting (0 = disabled, up to 3600s)

- Start/stop sync timer on setting change and plugin lifecycle

- Sync bookmarks immediately on new file/folder creation
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant