Skip to main content

​
Quick Setup

This guide walks you through setting up Sync Folds and verifying that fold states sync across your devices.
1

Install the plugin

Follow the installation guide to install Sync Folds via Community Plugins or manual installation.The plugin requires these files in your vault:
  • VaultFolder/.obsidian/plugins/sync-folds/main.js
  • VaultFolder/.obsidian/plugins/sync-folds/manifest.json
2

Enable Sync Folds

After installation, enable the plugin:
  1. Navigate to Settings → Community Plugins
  2. Find “Sync Folds” in the installed plugins list
  3. Toggle the switch to enable it
On first load, if the plugin finds no saved fold states but detects existing folds in localStorage, it will automatically export them to data.json. This ensures you don’t lose any existing folds.
3

Test your first fold

Let’s verify fold syncing is working:
  1. Open any note with multiple sections
  2. Fold a heading by clicking the collapse arrow next to it
  3. Wait 150ms (the debounce delay)
  4. Check that the fold was saved: 
    cat VaultFolder/.obsidian/plugins/sync-folds/data.json
You should see fold data in the JSON file:
{
  "enableSync": true,
  "folds": "{\"YourNote.md\":{\"folds\":[{\"from\":5,\"to\":15}],\"lines\":50}}"
}
Fold changes are debounced to 150ms to avoid excessive disk writes. If you fold/unfold rapidly, only the final state after 150ms of inactivity will be saved.
4

Verify sync across devices

Now test that folds sync to another device:On Device 1 (where you just folded content):
  1. Ensure your sync solution has uploaded the changes
  2. Check the modification time on data.json to confirm it was updated
On Device 2:
  1. Wait for your sync solution to download the updated data.json
  2. If Obsidian is already open, the plugin will automatically detect the change and update localStorage
  3. If Obsidian is closed, open it - the plugin will import fold states on load
  4. Open the same note and verify the fold state matches Device 1
The plugin detects external changes to data.json, but currently does not automatically apply them to already-open notes. You may need to close and reopen the note to see synced fold states. This is a known limitation tracked in the Work in Progress section.

​
Available Commands

Sync Folds provides two commands for manual control:

​
Export Folds from Local Storage

Command ID: export-fold-states Manually exports all current fold states from localStorage to the plugin’s data.json file. 
this.addCommand({
  id: 'export-fold-states',
  name: 'Export folds from local storage',
  callback: async () => {
    await this.exportFoldsToFile()
    new Notice('Fold states saved to settings')
  }
})
When to use:
  • After making many fold changes and wanting to ensure they’re saved immediately
  • Before switching devices or closing Obsidian
  • When troubleshooting sync issues
Run this command from the command palette (Ctrl/Cmd + P), then type “export folds”. You’ll see a notice confirming the save.

​
Import Folds into Local Storage

Command ID: import-fold-states Manually imports fold states from data.json into localStorage, overriding any local fold states. 
this.addCommand({
  id: 'import-fold-states',
  name: 'Import folds into local storage',
  callback: async () => {
    this.importFoldsToStorage()
    new Notice('Fold states applied from settings')
  }
})
When to use:
  • After sync completes on a new device
  • When fold states appear out of sync
  • After manually editing data.json
  • To restore fold states after clearing browser data
This command overwrites all local fold states with what’s in data.json. Any local-only fold changes will be lost.

​
How Automatic Sync Works

​
localStorage Interception

Sync Folds works by intercepting changes to localStorage:
Source: main.ts:140-148
localStorage.setItem = (key: string, value: string) => {
  this.originalSetItem(key, value)
  
  if (key.startsWith(foldPrefix)) {
    const filePath = key.replace(foldPrefix, '')
    log('Fold state changed:', filePath)
    this.debouncedSyncFile(filePath, value)
  }
}
When you fold or unfold content:
  1. Obsidian writes to localStorage with key format: {appId}-note-fold-{filePath}
  2. The plugin’s interceptor detects the write
  3. After 150ms of inactivity, the change is written to data.json
  4. Your sync solution propagates the file change

​
External Change Detection

When data.json changes externally (from sync):
Source: main.ts:73-107
public async onExternalSettingsChange(): Promise<void> {
  log('Fold states file changed externally: Syncing with localStorage')
  
  const previousFolds = { ...this.cachedFolds }
  await this.loadSettings()
  const currentFolds = this.getFoldsObject()
  
  // Remove deleted folds...
  // Upsert new/updated folds...
  
  this.cachedFolds = currentFolds
  log('localStorage sync complete')
}
The plugin:
  1. Compares cached fold states with newly loaded states
  2. Removes folds that were deleted on another device
  3. Updates or adds folds that changed
  4. Updates the cache for future comparisons

​
Sync Solution Compatibility

Sync Folds stores data in data.json, which syncs with any file syncing solution:

Obsidian Sync

Official Obsidian sync - fully compatible

iCloud

Apple’s cloud storage - syncs the entire .obsidian folder

Dropbox

Popular file sync service - fully compatible

Git

Version control - commit data.json along with your notes

Syncthing

Open-source continuous sync - fully compatible

Other Solutions

Any solution that syncs the vault folder works
No special configuration is needed. As long as your sync solution includes the .obsidian/plugins/sync-folds/ directory, fold states will sync automatically.

​
Best Practices

Let automatic sync do the work: In most cases, you won’t need to use the manual export/import commands. The plugin automatically syncs fold changes as you work.
Wait for sync to complete: When switching devices, give your sync solution a moment to upload/download changes before opening notes.
Enable sync on all devices: Install and enable Sync Folds on every device where you use your vault. The plugin must be active to apply synced fold states.
Monitor the data file: If fold states seem inconsistent, check the modification time of data.json to verify your sync solution is working correctly.

​
Work in Progress

Sync Folds is actively developed. Current limitations:
Synced folds not applied to open notes: When data.json changes externally, the plugin updates localStorage but doesn’t automatically refresh fold states in currently open notes. You may need to close and reopen notes to see synced changes.This feature is tracked in the TODO list.

​
Troubleshooting

  1. Verify the plugin is installed and enabled on both devices
  2. Check that data.json exists and is being updated when you fold/unfold
  3. Confirm your sync solution is syncing the .obsidian/plugins/sync-folds/ folder
  4. Try manually running “Export folds from local storage” on Device 1, then “Import folds into local storage” on Device 2
  1. Check if data.json still contains fold data
  2. If the file is empty or missing, restore from a backup
  3. If localStorage was cleared (e.g., browser data cleared), run “Import folds into local storage” to restore from data.json
The plugin uses a 150ms debounce to avoid excessive writes. If your sync solution has additional delays, there may be a longer gap between folding and seeing the change on another device. This is normal and expected.
  1. Verify main.js and manifest.json are in the correct folder
  2. Check that the folder is named exactly sync-folds (matching the ID in manifest.json)
  3. Ensure Community Plugins are enabled in Settings → Community Plugins
  4. Try reloading Obsidian (Ctrl/Cmd + R or restart the app)

​
Next Steps

Sync Setup

Learn about plugin settings and sync configuration

How It Works

Understand the technical details and architecture

Troubleshooting

Solve common issues and debug sync problems

GitHub Repository

View source code, report issues, and contribute

Build docs developers (and LLMs) love

Get started for freeTalk to us