andras/vault-link
1
0
Fork 0
Code Issues Pull requests 18 Projects Releases 55 Packages Wiki Activity Actions 1
vault-link/docs/guide/obsidian-plugin.md

6.9 KiB
Raw Blame History

Obsidian Plugin

Real-time sync for Obsidian vaults.

Installation

From Obsidian Community Plugins

  1. Open Obsidian Settings
  2. Navigate to Community Plugins
  3. Click Browse and search for "VaultLink"
  4. Click Install
  5. Enable the plugin

Manual Installation

  1. Download the latest release from GitHub Releases
  2. Extract main.js, manifest.json, and styles.css
  3. Copy to .obsidian/plugins/vault-link/ in your vault
  4. Reload Obsidian
  5. Enable VaultLink in Community Plugins settings

Configuration

After installation, configure the plugin in Settings → VaultLink.

Required Settings

Server URL

The WebSocket URL of your sync server.

  • Development/Local: ws://localhost:3000
  • Production (SSL): wss://sync.example.com

::: tip Use ws:// for unencrypted connections and wss:// for SSL connections (production). :::

Authentication Token

Your authentication token from the server's config.yml.

Generate a secure token:

openssl rand -hex 32

Vault Name

The name of the vault on the server. Can be any string.

Multiple Obsidian vaults can sync to the same server vault name (for shared vaults), or use unique names for separate vaults.

Optional Settings

Sync Concurrency

Number of files to sync simultaneously.

  • Default: 1
  • Range: 1-10
  • Higher values = faster initial sync, more resource usage

Max File Size

Maximum file size to sync (in MB).

  • Default: 10
  • Files larger than this are skipped

Ignore Patterns

Glob patterns for files to exclude from sync.

Examples:

  • *.tmp - Ignore temporary files
  • .trash/** - Ignore trash folder
  • private/** - Ignore private directory

WebSocket Retry Interval

Milliseconds between reconnection attempts when disconnected.

  • Default: 3500ms
  • Increase for flaky networks to avoid connection spam

Usage

Initial Sync

When first connecting:

  1. The plugin uploads all local files to the server
  2. Downloads any missing files from the server
  3. Resolves any conflicts using operational transformation
  4. Begins real-time synchronisation

Initial sync time depends on vault size and sync_concurrency setting.

Real-Time Sync

Once connected:

  • File changes: Automatically synced when saved
  • File creation: New files immediately uploaded
  • File deletion: Deletions propagated to other clients
  • File renames: Tracked and synchronised

The plugin watches your vault filesystem and syncs changes in real-time via WebSocket.

Status Indicators

The plugin provides visual feedback:

  • Connected: Green status in settings
  • Syncing: Progress indicator during uploads
  • Disconnected: Red status, automatic reconnection attempts
  • Error: Error message in settings and console

Check the Obsidian console (Ctrl+Shift+I / Cmd+Option+I) for detailed logs.

Features

Automatic Conflict Resolution

When multiple users edit the same file simultaneously, operational transformation merges changes automatically:

  • All edits are preserved
  • No manual conflict resolution required
  • Changes appear in real-time as others type

Mobile Support

VaultLink works on Obsidian mobile (iOS and Android):

  • Same configuration as desktop
  • Real-time sync across all devices
  • Handle network changes gracefully

::: warning Ensure your sync server is accessible from mobile networks (use WSS with a public domain or VPN). :::

Offline Support

The plugin handles offline scenarios:

  • Continue working when disconnected
  • Changes queue locally
  • Automatic sync when connection restored
  • Conflict resolution if others edited the same files

Collaboration Workflows

Personal Multi-Device Sync

Sync the same vault across devices:

  1. Configure each Obsidian instance with the same vault name
  2. Use the same authentication token
  3. All devices stay in sync automatically

Team Shared Vault

Multiple users collaborating:

  1. Each user has their own token (configured in server config.yml)
  2. All users connect to the same vault name
  3. Real-time collaborative editing with automatic conflict resolution

Selective Sharing

Share specific folders while keeping others private:

  1. Use different vault names for shared vs. private content
  2. Configure access control on the server per vault
  3. Use ignore patterns to exclude sensitive directories

Troubleshooting

Plugin won't connect

  1. Verify server is running:

    curl http://your-server:3000/vaults/test/ping

    Should return pong

  2. Check URL format:

    • Local: ws://localhost:3000
    • Remote (SSL): wss://sync.example.com
    • Don't include /vault/name in the URL

  3. Verify token:

    • Must match server config exactly
    • No extra spaces or quotes
    • Check server logs for authentication errors

  4. Check firewall:

    • Ensure port is accessible from your network
    • For mobile, server must be publicly accessible or use VPN

Files not syncing

  1. Check ignore patterns: File may match an exclusion pattern
  2. File size: Check if file exceeds max_file_size_mb
  3. Permissions: Ensure vault directory is readable/writable
  4. Console errors: Open dev tools (Ctrl+Shift+I) and check console

Slow initial sync

  1. Increase concurrency: Set sync_concurrency higher (e.g., 5)
  2. Network speed: Check internet connection
  3. Server resources: Ensure server isn't overloaded
  4. Large files: Consider increasing timeout settings

Conflicts not resolving

Operational transformation should handle conflicts automatically. If issues persist:

  1. Check console for sync errors
  2. Verify both clients are connected
  3. Check server logs for processing errors
  4. Ensure files are text-based (binary files may not merge well)

High CPU/Memory usage

  1. Reduce concurrency: Lower sync_concurrency
  2. Add ignore patterns: Exclude unnecessary files
  3. File watchers: Large vaults may trigger many filesystem events
  4. Check for sync loops: Ensure no circular dependencies

Advanced Configuration

Multiple Vaults

To sync multiple Obsidian vaults to different server vaults:

  1. Each Obsidian vault has its own VaultLink plugin configuration
  2. Use different vault names for each
  3. Can use the same or different tokens (depending on access control)

Custom Sync Patterns

Combine ignore patterns for fine-grained control:

# Ignore patterns
*.tmp
*.bak
.DS_Store
.trash/**
private/**
drafts/**/*.draft.md

Development/Testing

For plugin development:

  1. Clone the repository
  2. cd frontend && npm install
  3. npm run dev to build in watch mode
  4. Plugin rebuilds automatically on changes
  5. Reload Obsidian to test changes

Next Steps