Sync Setup

Overview

Sync Folds stores fold states in .obsidian/plugins/sync-folds/data.json, which means any file sync solution that syncs your vault will automatically sync your fold states. No additional configuration is required beyond ensuring the plugin is installed on all devices.

The data.json file is stored in your vault’s plugin directory, so it’s treated like any other vault file by sync solutions.

File Location

Fold states are persisted to:

<YourVault>/.obsidian/plugins/sync-folds/data.json

Example structure:

MyVault/
├── .obsidian/
│   ├── plugins/
│   │   ├── sync-folds/
│   │   │   ├── main.js
│   │   │   ├── manifest.json
│   │   │   └── data.json          ← Fold states stored here
│   │   └── other-plugins/
│   └── workspace.json
├── Notes/
└── Projects/

If your sync solution excludes .obsidian/ or .obsidian/plugins/, fold states will not sync. Ensure these directories are included in your sync configuration.

Sync Solutions

Obsidian Sync

Status: ✅ Fully compatibleObsidian Sync automatically syncs all plugin data files, including data.json.

Setup Steps

Install the plugin on all devices

Install and enable Sync Folds from Settings → Community plugins on each device where you use Obsidian.

Verify sync settings

Open Settings → Sync → Vault configuration sync and ensure “Plugins” is enabled. This is usually enabled by default.

Wait for initial sync

After enabling the plugin on multiple devices, Obsidian Sync will propagate the data.json file. This typically takes a few seconds to minutes depending on sync frequency.

Verify fold states sync

Fold some headings on Device A, wait for sync, then open the same file on Device B. The folds should be preserved.

Obsidian Sync’s conflict resolution handles data.json like any other file. If you fold different sections on two devices while offline, the last sync wins. Use the manual commands to merge if needed.

Troubleshooting

Fold states not syncing

Check that “Plugins” is enabled in Sync settings
Verify the plugin is enabled on both devices
Check sync status in the bottom-right corner
Try running Export folds from local storage to force a write

Sync conflicts

If you see sync conflicts for data.json, choose the version from the device with the most complete fold states, or manually merge using the export/import commands.

iCloud Drive

Status: ✅ Compatible (with caveats)iCloud Drive syncs files across Apple devices. It works well for Obsidian vaults, but has occasional sync delays.

Setup Steps

Place vault in iCloud Drive

Ensure your Obsidian vault is stored in an iCloud Drive folder (e.g., ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault/).

Install the plugin on all devices

Install Sync Folds on each Mac, iPhone, or iPad where you use Obsidian.

Verify iCloud sync is active

Check that iCloud Drive is enabled in System Settings → Apple ID → iCloud → iCloud Drive.

Wait for sync to complete

After folding content, give iCloud a minute to sync. You can check sync status by looking at the cloud icon next to files in Finder.

iCloud Drive syncs in the background and may take longer than real-time sync solutions. If you switch devices quickly, fold states might not be synced yet. Wait a minute after closing Obsidian on one device before opening on another.

Known Issues

Sync delays

iCloud Drive doesn’t sync immediately. Small files like data.json usually sync within 30-60 seconds, but can take longer under poor network conditions.

iOS limitations

On iOS, iCloud sync may pause when Obsidian is in the background. Ensure Obsidian has completed saving before closing the app.

Conflict resolution

iCloud occasionally creates conflicted copies. If you see data (conflicted copy).json, manually merge the fold states using the export/import commands.

Dropbox

Status: ✅ Fully compatibleDropbox provides reliable file syncing with good conflict detection.

Setup Steps

Place vault in Dropbox folder

Store your Obsidian vault in a Dropbox folder (e.g., ~/Dropbox/Obsidian/YourVault/).

Install Dropbox on all devices

Ensure Dropbox is installed and running on each device. Verify the vault folder is synced (not selective-sync excluded).

Install the plugin on all devices

Install and enable Sync Folds on each device.

Verify sync

Fold some content on one device, wait for the Dropbox icon to show “Up to date”, then check on another device.

Dropbox typically syncs within seconds for small files like data.json. It’s one of the fastest sync options for Obsidian.

Conflict Handling

If you edit fold states on multiple devices while offline, Dropbox will create a conflicted copy:

data.json
data (Conflicted copy from MacBook Pro).json

To resolve:

Compare both files

Open both data.json files in a text editor to see which has the fold states you want to keep.

Choose or merge

Either keep one version, or manually merge the folds JSON string if you want to preserve changes from both devices.

Delete conflicted copy

Once resolved, delete the conflicted copy and run Import folds into local storage on all devices.

Git-based Sync

Status: ✅ Fully compatibleUsing Git (with plugins like Obsidian Git) provides version control for your fold states.

Setup Steps

Initialize Git repository

Initialize a Git repo in your vault or ensure your vault is already tracked by Git.

cd /path/to/vault
git init

Ensure .obsidian is tracked

Verify that .obsidian/plugins/sync-folds/ is not in your .gitignore.

# Your .gitignore should NOT exclude:
# .obsidian/plugins/sync-folds/

Some templates exclude all of .obsidian/, which would prevent fold state syncing.

Install the plugin on all devices

Install Sync Folds on each device where you work with the vault.

Commit and push data.json

After the plugin creates data.json, commit and push it:

git add .obsidian/plugins/sync-folds/data.json
git commit -m "Add initial fold states"
git push

Pull on other devices

On other devices, pull the changes:

git pull

If Obsidian is already running, use Import folds into local storage to apply the synced states.

If using the Obsidian Git plugin, it will automatically commit and push data.json based on your configured intervals. This provides automatic sync similar to other solutions.

Merge Conflicts

If two devices modify fold states while offline, Git will create a merge conflict:

<<<<<<< HEAD
{"enableSync":true,"folds":"{...}"}
=======
{"enableSync":true,"folds":"{...}"}
>>>>>>> origin/main

To resolve:

Decide which version to keep

Open .obsidian/plugins/sync-folds/data.json and examine both versions.

Manually merge if needed

Since folds is a JSON string, parse both, merge the objects, and stringify back. Or choose one version and discard the other.

Remove conflict markers

Delete the <<<<<<<, =======, and >>>>>>> lines.

Commit the resolution

git add .obsidian/plugins/sync-folds/data.json
git commit -m "Resolve fold state merge conflict"
git push

Import on all devices

Run Import folds into local storage on each device to apply the resolved state.

Syncthing

Status: ✅ Fully compatibleSyncthing provides peer-to-peer file synchronization without cloud services.

Setup Steps

Install Syncthing on all devices

Download and install Syncthing from syncthing.net on each device.

Add vault folder to Syncthing

In the Syncthing web UI, add your Obsidian vault folder as a synced folder.

Ensure .obsidian is included

In folder settings, verify that .obsidian is not in the ignore patterns. By default, Syncthing syncs hidden files.

Share with other devices

Share the vault folder with your other devices via Syncthing’s device pairing.

Install the plugin on all devices

Install and enable Sync Folds on each device.

Verify sync

Check Syncthing’s web UI to ensure data.json is syncing. It should show “Up to Date” once initial sync completes.

Syncthing syncs continuously and quickly on local networks. It’s excellent for home/office setups where devices are frequently on the same WiFi.

Conflict Resolution

Syncthing creates .sync-conflict files when it detects conflicts:

data.json
data.sync-conflict-20260305-123456.json

Resolve by choosing the correct version and deleting the conflict file, similar to Dropbox.

Self-Hosted Solutions

Status: ✅ Compatible with most solutionsMany self-hosted sync solutions work with Sync Folds, including:

Nextcloud / ownCloud: WebDAV-based file sync
Seafile: Block-level file syncing
Resilio Sync: Peer-to-peer BitTorrent-based sync
rsync: Manual or automated file copying
CouchDB / PouchDB: Database-backed sync

General Setup

Ensure .obsidian directory syncs

Configure your sync solution to include .obsidian/plugins/ in the sync scope.

Install the plugin on all devices

Install Sync Folds on each device where the vault is synced.

Verify file syncing

Make a test change to data.json on one device and verify it appears on others.

Handle conflicts according to your solution

Each self-hosted solution has its own conflict resolution mechanism. Consult its documentation for how to handle conflicted data.json files.

Performance and sync speed vary by solution. Real-time sync solutions (like Nextcloud with desktop clients) work best. Periodic sync solutions (like cron-based rsync) may have delays.

WebDAV Example (Nextcloud)

If using Nextcloud:

Install the Nextcloud desktop client on each device
Sync your vault folder via Nextcloud
Nextcloud automatically handles .obsidian directories
Install Sync Folds on all devices
Fold states will sync through Nextcloud’s conflict-free sync

Enable/Disable Sync

Sync Folds includes an enableSync setting that controls whether the plugin actively syncs fold states.

Settings Interface

export interface SyncFoldSettings {
    enableSync: boolean
    folds: string
}

export const DEFAULT_SETTINGS: SyncFoldSettings = {
    enableSync: true,
    folds: '{}'
}

By default, enableSync is true. When false:

localStorage interception is disabled
Fold changes are not written to data.json
External change detection is not active
Manual commands still work (export/import)

When to Disable Sync

Testing or debugging

Disable sync to prevent the plugin from modifying data.json while you’re testing or debugging other parts of your vault setup.

Temporary performance issues

If you’re experiencing performance issues and suspect the plugin, temporarily disable sync to see if it improves performance.

Using only on one device

If you only use Obsidian on one device, you may not need sync. However, keeping it enabled is harmless and provides a backup of fold states.

Disabling sync doesn’t delete existing fold states from data.json or localStorage. It only stops new changes from being synced. Re-enabling sync resumes normal operation.

Sync Performance Tips

Use Local Networks

For peer-to-peer solutions like Syncthing, keep devices on the same WiFi network for fastest sync speeds.

Check Sync Intervals

Some sync solutions have configurable intervals. Set them to sync frequently (every 1-5 minutes) for near-real-time fold state updates.

Monitor File Size

data.json typically stays small (a few KB), but if you have thousands of files with fold states, it can grow. Most sync solutions handle small files very efficiently.

Close Obsidian Before Switching

For non-real-time sync (like rsync or periodic iCloud), close Obsidian on one device before opening on another to ensure changes are synced.

Troubleshooting Common Sync Issues

Fold states not syncing between devices

Checklist:

Verify the plugin is installed and enabled on both devices
Check that enableSync is true in settings
Ensure .obsidian/plugins/sync-folds/ is not excluded by your sync solution
Verify data.json exists: .obsidian/plugins/sync-folds/data.json
Check sync solution status (cloud icon, web UI, etc.)
Try manually running Export folds from local storage on one device and Import folds into local storage on the other

Sync conflicts

If your sync solution creates conflicted copies of data.json:

Open both versions in a text editor
Compare the folds JSON string to see which has more complete data
Choose one version or manually merge the fold objects
Replace data.json with the resolved version
Delete the conflicted copy
Run Import folds into local storage on all devices

Fold states revert after syncing

This can happen if:

Two devices both export at the same time, and the wrong one wins
Your sync solution’s conflict resolution chose the older version
The plugin wasn’t running when the file synced, so localStorage wasn’t updated

Solution: Run Export folds from local storage on the device with the correct fold states, ensure it syncs, then run Import folds into local storage on the other device.

data.json is empty or corrupted

If data.json contains {"enableSync":true,"folds":"{}"} but you have fold states:

The plugin may have reset on load because the file was empty
Run Export folds from local storage to rebuild from localStorage
If localStorage is also empty, fold states were lost and cannot be recovered

For most sync issues, the export/import commands are your best diagnostic tools. Export from the device that has correct fold states, sync, then import on other devices.

Get Started

Usage

Technical

Support

Overview

File Location

Sync Solutions

Obsidian Sync

Setup Steps

Troubleshooting

iCloud Drive

Setup Steps

Known Issues

Dropbox

Setup Steps

Conflict Handling

Git-based Sync

Setup Steps

Merge Conflicts

Syncthing

Setup Steps

Conflict Resolution

Self-Hosted Solutions

General Setup

WebDAV Example (Nextcloud)

Enable/Disable Sync

Settings Interface

When to Disable Sync

Sync Performance Tips

Use Local Networks

Check Sync Intervals

Monitor File Size

Close Obsidian Before Switching

Troubleshooting Common Sync Issues

Build docs developers (and LLMs) love

Get Started

Usage

Technical

Support

​Overview

​File Location

​Sync Solutions

​Obsidian Sync

​Setup Steps

​Troubleshooting

​iCloud Drive

​Setup Steps

​Known Issues

​Dropbox

​Setup Steps

​Conflict Handling

​Git-based Sync

​Setup Steps

​Merge Conflicts

​Syncthing

​Setup Steps

​Conflict Resolution

​Self-Hosted Solutions

​General Setup

​WebDAV Example (Nextcloud)

​Enable/Disable Sync

​Settings Interface

​When to Disable Sync

​Sync Performance Tips

Use Local Networks

Check Sync Intervals

Monitor File Size

Close Obsidian Before Switching

​Troubleshooting Common Sync Issues

Build docs developers (and LLMs) love

Overview

File Location

Sync Solutions

Obsidian Sync

Setup Steps

Troubleshooting

iCloud Drive

Setup Steps

Known Issues

Dropbox

Setup Steps

Conflict Handling

Git-based Sync

Setup Steps

Merge Conflicts

Syncthing

Setup Steps

Conflict Resolution

Self-Hosted Solutions

General Setup

WebDAV Example (Nextcloud)

Enable/Disable Sync

Settings Interface

When to Disable Sync

Sync Performance Tips

Troubleshooting Common Sync Issues