Skip to main content

​
Overview

While Sync Folds automatically manages fold states in the background, it provides two manual commands for advanced use cases and troubleshooting.

​
Available Commands

Export Folds from Local Storage

Manually exports all current fold states from localStorage to the settings file.

Import Folds into Local Storage

Manually imports fold states from the settings file to localStorage.

​
Export Folds from Local Storage

​
Command Details

  • Command ID: export-fold-states
  • Command Name: Export folds from local storage
  • Source: main.ts:38-45

​
What It Does

This command reads all fold states currently stored in your browser’s localStorage and writes them to .obsidian/plugins/sync-folds/data.json. This is the same operation that happens automatically when you fold/unfold content (after the debounce period). 
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 It

The plugin debounces fold state changes by 150ms. If you want to force an immediate write to disk (for example, before closing Obsidian on an unreliable sync connection), use this command.
If your fold states in the file got corrupted but localStorage still has good data, this command can rebuild the file from localStorage.
When you first install the plugin on a device that already has fold states in localStorage, the plugin automatically exports on load. However, if you disabled sync initially and want to export later, use this command.
This command only exports folds for files that currently have fold states in localStorage. If you’ve never opened a file on this device, its fold states won’t be included in the export.

​
How to Invoke

  1. Press Ctrl+P (or Cmd+P on Mac) to open the command palette
  2. Type “export folds” to filter commands
  3. Select Export folds from local storage
  4. You’ll see a notice: “Fold states saved to settings”

​
What Gets Exported

The command scans localStorage for all keys matching the pattern: 
{appId}-note-fold-{filePath}
For each matching key, it extracts:
  • The file path
  • The fold state data (array of folded regions and line count)
These are then written to the folds setting as a JSON string.
The export operation is logged in the console when DEBUG mode is enabled. You can verify what was exported by checking the developer console.

​
Import Folds into Local Storage

​
Command Details

  • Command ID: import-fold-states
  • Command Name: Import folds into local storage
  • Source: main.ts:47-54

​
What It Does

This command reads all fold states from .obsidian/plugins/sync-folds/data.json and writes them to localStorage. This makes the fold states immediately available to Obsidian. 
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 It

If you manually edit the plugin’s data.json file (for example, to merge fold states from multiple devices), use this command to apply the changes to localStorage.
If localStorage fold states seem out of sync with what’s in the file, this command forces a full re-import from the source of truth (the file).
During development, testing, or recovery from data loss, you might want to manually restore fold states from a backup data.json.
After importing, you may need to close and reopen files for the fold states to visually apply. The fold states are in localStorage, but Obsidian only reads them when opening a file.

​
How to Invoke

  1. Press Ctrl+P (or Cmd+P on Mac) to open the command palette
  2. Type “import folds” to filter commands
  3. Select Import folds into local storage
  4. You’ll see a notice: “Fold states applied from settings”

​
What Gets Imported

The command reads the folds setting from data.json, parses the JSON string, and writes each fold state to localStorage: 
private importFoldsToStorage() {
    const folds = this.getFoldsObject()
    const app = this.app 
    const appId = app.appId

    for (const [filePath, foldData] of Object.entries(folds)) {
        const key = `${appId}-note-fold-${filePath}`
        const value = JSON.stringify(foldData)
        this.originalSetItem.call(localStorage, key, value)
    }

    this.cachedFolds = { ...folds }
}
The import uses the original (non-intercepted) setItem method to avoid triggering the debounced sync logic. This prevents an infinite loop where importing triggers an export.

​
Command Comparison

AspectExportImport
DirectionlocalStorage → filefile → localStorage
Source of truthlocalStoragedata.json
Triggers auto-syncNoNo
Updates cacheYesYes
Common use caseForce immediate saveApply synced changes

​
Common Workflows

​
Merging Fold States from Multiple Devices

1

Export from both devices

On each device, run Export folds from local storage to ensure the latest fold states are in each device’s data.json.
2

Manually merge the files

Copy the folds JSON from both files and merge them in a text editor. The folds field is a JSON string, so you’ll need to parse it, merge the objects, and stringify again.
3

Place merged file on both devices

Replace .obsidian/plugins/sync-folds/data.json on both devices with your merged version.
4

Import on both devices

On each device, run Import folds into local storage to apply the merged fold states.

​
Recovering from a Conflict

1

Identify the good copy

Determine which device has the correct fold states. Open a file and check if folds are as expected.
2

Export from the good device

On the device with good fold states, run Export folds from local storage.
3

Sync to other devices

Let your sync solution propagate the data.json file to other devices.
4

Import on other devices

On each other device, run Import folds into local storage to overwrite their localStorage with the good copy.
The import command overwrites localStorage keys for all files in the folds data. If you have fold states in localStorage for files not in the import, those will remain unchanged. Use export first if you want to preserve them.

​
Troubleshooting

Ensure the plugin is enabled in Settings → Community plugins. If enableSync is set to false, the commands are still registered, but the plugin won’t intercept fold changes automatically.
Close and reopen the file. Obsidian reads fold states from localStorage when opening a file, not continuously. If the file is already open, the import won’t visually affect it until you close and reopen.
Check if enableSync is true in the plugin settings. If sync is disabled, the export command will skip the write operation. Also check file permissions on data.json.
For most users, the automatic sync is sufficient. Only use these commands when troubleshooting, forcing immediate syncs, or performing advanced manual operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us