Skip to main content

​
What is Sync Folds?

Sync Folds is an Obsidian plugin that synchronizes your fold states across all your devices. When you fold or unfold sections in your notes, those states are preserved and synced, ensuring a consistent editing experience wherever you open your vault.

​
The Problem

By default, Obsidian stores fold states in localStorage, which is browser-specific storage that doesn’t sync across devices. This means:
  • Fold states you create on your desktop don’t appear on your mobile device
  • Each device maintains its own separate fold configuration
  • You lose your carefully organized document structure when switching devices
localStorage is a web storage API that browsers use to store data locally. Since it’s tied to the specific browser instance, it cannot sync through Obsidian Sync, iCloud, or any other file syncing solution.

​
How Sync Folds Solves This

Sync Folds intercepts fold state changes and stores them in the plugin’s data.json file, which lives in your vault at .obsidian/plugins/sync-folds/data.json. Since this file is part of your vault, it syncs automatically with:
  • Obsidian Sync
  • iCloud
  • Dropbox
  • Git
  • Syncthing, CouchDB, or any self-hosted solution

​
Key Features

Automatic Sync

Fold changes are automatically saved and synced as you work (debounced to 150ms)

Cross-Device Support

Works on both desktop and mobile devices (not desktop-only)

No Network Required

All syncing happens through your existing file sync solution - no external services

Manual Controls

Export and import commands let you manually control fold state sync

​
How It Works

The plugin operates in three key phases:

​
1. On Plugin Load

When Obsidian starts and the plugin loads:
  • If fold states exist in data.json, they’re imported into localStorage
  • If no fold states exist in settings, current localStorage states are exported to the file
  • The plugin begins intercepting localStorage changes

​
2. During Active Use

As you fold and unfold content:
  • The plugin intercepts calls to localStorage.setItem() and localStorage.removeItem()
  • Changes are debounced (150ms) to avoid excessive writes
  • Updated fold states are saved to data.json
  • Your sync solution propagates the changes to other devices

​
3. When Settings Change Externally

When data.json is updated by your sync solution:
  • The plugin detects the external change
  • It compares previous and current fold states
  • Deleted folds are removed from localStorage
  • New or updated folds are applied to localStorage
The plugin maintains a cached copy of fold states to efficiently detect what changed during external updates.

​
Technical Details

Fold states are stored as JSON with this structure:
interface FoldStateData {
  [filePath: string]: {
    folds: Array<{
      from: number  // Starting line number
      to: number    // Ending line number
    }>
    lines: number   // Total lines in file
  }
}
Example:
{
  "MyNote.md": {
    "folds": [
      { "from": 5, "to": 15 },
      { "from": 20, "to": 30 }
    ],
    "lines": 50
  }
}
The plugin intercepts localStorage by replacing the native setItem and removeItem methods:
localStorage.setItem = (key: string, value: string) => {
  this.originalSetItem(key, value)
  
  if (key.startsWith(foldPrefix)) {
    const filePath = key.replace(foldPrefix, '')
    this.debouncedSyncFile(filePath, value)
  }
}
The fold prefix is constructed as: {appId}-note-fold-{filePath}

​
Get Started

Installation

Install Sync Folds from Community Plugins or manually

Quickstart Guide

Get up and running in under 5 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us