Skip to main content
Sync Folds is an open source project and welcomes contributions from the community!

​
Ways to Contribute

Report Bugs

Found an issue? Open a bug report on GitHub with details about the problem.

Suggest Features

Have an idea for improvement? Create a feature request to discuss it.

Improve Documentation

Help make the docs better by fixing typos or adding clarifications.

Submit Code

Fix bugs or implement features by submitting a pull request.

​
Development Setup

1

Fork and clone the repository

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/YOUR-USERNAME/obsidian-sync-folds.git
cd obsidian-sync-folds
2

Install dependencies

The project uses npm for package management:
npm install
This installs all required dependencies including TypeScript, esbuild, and eslint.
3

Start development build

Run the development build with watch mode:
npm run dev
This uses esbuild to compile TypeScript and automatically rebuilds on file changes.
4

Link to your test vault

Create a symlink from your Obsidian vault to the development folder:
# Create the plugins directory if it doesn't exist
mkdir -p /path/to/your/vault/.obsidian/plugins

# Create symlink (adjust paths as needed)
ln -s /path/to/obsidian-sync-folds /path/to/your/vault/.obsidian/plugins/sync-folds
On Windows, use mklink /D instead of ln -s to create the symlink.
5

Enable the plugin in Obsidian

  1. Open your test vault in Obsidian
  2. Go to Settings → Community plugins
  3. Disable Safe Mode if prompted
  4. Find Sync Folds and enable it
  5. Reload Obsidian after making changes (Cmd/Ctrl + R)

​
Project Structure

The codebase is organized into focused modules: 
src/
├── main.ts           # Plugin entry point and lifecycle
├── settings.ts       # Settings interface and defaults  
├── types.ts          # TypeScript type definitions
└── log.ts            # Logging utilities
Key files:
  • main.ts - Core plugin logic including localStorage interception, sync operations, and command registration
  • settings.ts - Defines SyncFoldSettings interface with enableSync and folds properties
  • types.ts - Type definitions for fold data structures (Fold, FoldedProperties, FoldStateData)

​
Build Commands

The project provides several npm scripts: 
npm run dev
The production build command (npm run build) runs TypeScript type checking before bundling with esbuild.

​
Code Style

The project uses ESLint with TypeScript support to maintain code quality. Before submitting a PR:
  1. Run the linter to check for issues: 
    npm run lint
  2. Auto-fix issues where possible: 
    npm run lint:fix
  3. Ensure all TypeScript types are correct (the build command checks this): 
    npm run build
Code conventions:
  • Use TypeScript with strict type checking
  • Follow existing code patterns and structure
  • Keep main.ts focused on plugin lifecycle
  • Add JSDoc comments for public APIs
  • Use descriptive variable and function names

​
Testing

While the project doesn’t currently have automated tests, you should thoroughly test your changes:
  1. Manual testing in Obsidian:
    • Test fold creation, modification, and deletion
    • Verify sync behavior across mock “devices” (different vault folders)
    • Test with both the setting enabled and disabled
  2. Test the manual commands:
    • Export folds from local storage
    • Import folds into local storage
  3. Edge cases to consider:
    • Large numbers of folds (performance)
    • Files being renamed or moved
    • Plugin reload/unload behavior
    • Mobile vs desktop compatibility
The plugin sets isDesktopOnly: false in manifest.json, so test on mobile if possible.

​
Pull Request Process

1

Create a feature branch

Create a branch from main with a descriptive name:
git checkout -b fix/fold-sync-issue
# or
git checkout -b feature/bulk-export
2

Make your changes

  • Write clean, well-documented code
  • Follow existing code style and patterns
  • Test thoroughly in Obsidian
  • Run npm run lint:fix before committing
3

Commit with clear messages

Write descriptive commit messages explaining the “why”:
git add .
git commit -m "Fix: Prevent duplicate fold entries on rapid toggling"
4

Push and create PR

Push your branch and create a pull request on GitHub:
git push origin your-branch-name
In your PR description:
  • Explain what changes you made and why
  • Reference any related issues
  • Describe how you tested the changes
  • Note any breaking changes or migration steps
5

Respond to feedback

The maintainer will review your PR and may request changes. Be responsive to feedback and update your PR as needed.

​
Technical Details

​
How Sync Works

Understanding the sync mechanism helps when contributing:
  1. localStorage Interception (main.ts:130-159):
    • Wraps localStorage.setItem and localStorage.removeItem
    • Monitors keys prefixed with {appId}-note-fold-
    • Triggers debounced sync on changes
  2. Debounced Sync (main.ts:170-182):
    • 150ms debounce prevents excessive writes
    • Batches rapid fold changes into single save
  3. External Change Detection (main.ts:73-107):
    • Detects when data.json changes (from sync)
    • Updates localStorage to match
    • Uses cache to minimize unnecessary updates

​
Build System

The project uses esbuild for fast compilation:
  • Configuration in esbuild.config.mjs
  • Bundles all dependencies into main.js
  • Supports both development (watch) and production modes
  • TypeScript compilation with type checking

​
Funding

If you’d like to support the project financially, consider sponsoring the author:

GitHub Sponsors

Support the development of Sync Folds and other open source projects.

​
License

Sync Folds is licensed under the 0BSD License (Zero-Clause BSD). This is an extremely permissive license that allows you to:
  • Use the code for any purpose
  • Modify and distribute the code
  • Use the code commercially or privately
  • No attribution required
See the LICENSE file for full details.

​
Questions?

If you have questions about contributing: We appreciate all contributions, big or small!

Build docs developers (and LLMs) love

Get started for freeTalk to us