276 lines
6.9 KiB
Markdown
276 lines
6.9 KiB
Markdown
# 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](https://github.com/schmelczer/vault-link/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:
|
|
|
|
```bash
|
|
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**:
|
|
|
|
```bash
|
|
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
|
|
|
|
- [Learn about the sync algorithm →](/architecture/sync-algorithm)
|
|
- [Configure the server →](/config/server)
|
|
- [Set up the CLI client →](/guide/cli-client)
|