andras/vault-link
1
0
Fork 0
Code Issues Pull requests 18 Projects Releases 55 Packages Wiki Activity Actions 1

Enforce british english

Browse source
This commit is contained in:
Andras Schmelczer 2025-11-22 12:42:16 +00:00
parent 1b1b72cb92
commit aaeca588fb
14 changed files with 147 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.github/workflows/deploy-docs.yml vendored
View file

@ -47,6 +47,11 @@ jobs:
cd docs
npm run format:check
- name: Check spelling
run: |
cd docs
npm run spell:check
- name: Build documentation
run: |
cd docs

92
docs/.cspell.json Normal file
View file

@ -0,0 +1,92 @@
{
"version": "0.2",
"language": "en-GB",
"dictionaries": ["en-gb"],
"ignorePaths": [
"node_modules",
".vitepress/dist",
".vitepress/cache",
"package-lock.json"
],
"words": [
"VaultLink",
"Obsidian",
"WebSocket",
"SQLite",
"codebase",
"CRDT",
"CRDTs",
"YAML",
"nginx",
"Caddy",
"Traefik",
"systemd",
"localhost",
"vaultlink",
"Axum",
"Tokio",
"SQLx",
"reconcile",
"postgresql",
"VitePress",
"markdownlint",
"filesystem",
"backend",
"frontend",
"macOS",
"CLI",
"API",
"JSON",
"HTTP",
"HTTPS",
"SSL",
"TLS",
"WSS",
"TCP",
"VPS",
"Docker",
"Github",
"Dockerfile",
"dockerignore",
"Rustup",
"PostgreSQL",
"UUID",
"CORS",
"HSTS",
"CI",
"CD",
"OpenSSL",
"README",
"config",
"submodule",
"repo",
"autocomplete",
"autoformat",
"dedupe",
"diff",
"grep",
"stdout",
"stderr",
"chmod",
"mkdir",
"rclone",
"uuidgen",
"letsencrypt",
"fullchain",
"privkey",
"schmelczer",
"Schmelczer",
"ghcr",
"keepalive",
"healthcheck",
"writable",
"Cloudant",
"Syncthing",
"cadvisor",
"Caddyfile",
"nodelay",
"websecure",
"certresolver",
"rootfs"
]
}

2
docs/.vitepress/config.mts
View file

@ -2,7 +2,7 @@ import { defineConfig } from "vitepress"
export default defineConfig({
title: "VaultLink",
description: "Self-hosted real-time synchronization for Obsidian",
description: "Self-hosted real-time synchronisation for Obsidian",
base: "/vault-link/",
themeConfig: {
logo: "/logo.svg",

16
docs/README.md
View file

@ -58,6 +58,16 @@ Check formatting without making changes:
npm run format:check
```
### Spell Check
Check spelling (British English):
```bash
npm run spell
```
The spell checker enforces British English spellings (e.g., "synchronisation", "optimise", "behaviour").
## Deployment
The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch.
@ -92,11 +102,15 @@ docs/
## Writing Documentation
### Language
All documentation uses **British English**. The spell checker enforces this in CI.
### Markdown Features
VitePress supports:
- GitHub Flavored Markdown
- GitHub Flavoured Markdown
- Custom containers (tip, warning, danger)
- Code syntax highlighting
- Mermaid diagrams

2
docs/architecture/data-flow.md
View file

@ -33,7 +33,7 @@ sequenceDiagram
### 2. Initial Sync
After authentication, the client performs initial synchronization:
After authentication, the client performs initial synchronisation:
```mermaid
sequenceDiagram

6
docs/architecture/index.md
View file

@ -40,7 +40,7 @@ Central sync server with multiple clients. High-level architecture and design de
### Sync Server
Central authority for synchronization. Rust + Axum framework.
Central authority for synchronisation. Rust + Axum framework.
**Responsibilities**:
@ -213,7 +213,7 @@ Clients maintain sync metadata:
└── cache/ # Optional local cache
```
The `.vaultlink` directory tracks which files have been synced and their versions to enable efficient synchronization.
The `.vaultlink` directory tracks which files have been synced and their versions to enable efficient synchronisation.
## Communication Protocol
@ -279,7 +279,7 @@ Token-based authentication on connection:
- **Small vaults** (< 1000 files): Excellent performance
- **Medium vaults** (1000-10000 files): Good performance with tuning
- **Large vaults** (> 10000 files): May require optimization
- **Large vaults** (> 10000 files): May require optimisation
- **Concurrent users**: Tested with dozens of simultaneous clients per vault
## Security Model

14
docs/architecture/sync-algorithm.md
View file

@ -19,7 +19,7 @@ Operational transformation:
- **Automatic**: No user intervention required
- **Preserves all edits**: No data loss
- **Real-time**: Changes appear immediately
- **Intuitive**: Behavior matches user expectations
- **Intuitive**: Behaviour matches user expectations
## The reconcile-text Library
@ -27,7 +27,7 @@ VaultLink uses the [`reconcile-text`](https://crates.io/crates/reconcile-text) R
### Why reconcile-text over CRDTs?
VaultLink faces a **differential synchronization** challenge: users edit Obsidian vaults with various editors (Obsidian desktop, Obsidian mobile, Vim, VS Code, or any text editor), often while offline. This means we only observe the **final state** of each document after editing, not the individual keystrokes or operations that produced it.
VaultLink faces a **differential synchronisation** challenge: users edit Obsidian vaults with various editors (Obsidian desktop, Obsidian mobile, Vim, VS Code, or any text editor), often while offline. This means we only observe the **final state** of each document after editing, not the individual keystrokes or operations that produced it.
**The fundamental problem**:
@ -50,9 +50,9 @@ VaultLink faces a **differential synchronization** challenge: users edit Obsidia
6. **Simpler infrastructure**: No need for complex operation capture, transformation logs, or tombstone management that CRDTs require
**The tradeoff**:
**The trade-off**:
CRDTs excel when you control the entire editing infrastructure and can capture every operation. reconcile-text excels when you're synchronizing independently-edited files—exactly VaultLink's scenario. The merge quality depends on Myers' diff algorithm rather than operation history, which is the correct tradeoff for differential sync.
CRDTs excel when you control the entire editing infrastructure and can capture every operation. reconcile-text excels when you're synchronising independently-edited files—exactly VaultLink's scenario. The merge quality depends on Myers' diff algorithm rather than operation history, which is the correct trade-off for differential sync.
For note-taking workflows where users value editor freedom and offline editing, this approach provides superior user experience compared to either CRDTs (which would require operation tracking) or Git-style merging (which requires manual conflict resolution).
@ -253,9 +253,9 @@ Result: "Line 1\nLine 2 modified\nLine 3"
- **Cursors**: O(clients × vaults)
- **Active operations**: Minimal (processed in real-time)
### Optimization
### Optimisation
VaultLink optimizes for:
VaultLink optimises for:
- Small, frequent edits (typical typing patterns)
- Text documents (not binary files)
@ -404,7 +404,7 @@ fn transform(op_a: Operation, op_b: Operation) -> (Operation, Operation) {
1. **Small edits**: Make small, focused changes for easier merging
2. **Coordinate major changes**: Discuss large refactors with team
3. **Monitor sync status**: Ensure changes are uploaded before signing off
4. **Test conflict resolution**: Verify behavior matches expectations
4. **Test conflict resolution**: Verify behaviour matches expectations
### For Developers

10
docs/config/advanced.md
View file

@ -1,12 +1,12 @@
# Advanced Configuration
Advanced topics for optimizing and customizing your VaultLink deployment.
Advanced topics for optimising and customising your VaultLink deployment.
## Database Optimization
## Database Optimisation
### SQLite Tuning
While VaultLink handles most SQLite configuration automatically, you can optimize for specific workloads.
While VaultLink handles most SQLite configuration automatically, you can optimise for specific workloads.
#### WAL Mode
@ -36,7 +36,7 @@ du -h databases/*.db
# Vacuum to reclaim space (offline only)
sqlite3 databases/vault.db "VACUUM;"
# Analyze for query optimization
# Analyse for query optimisation
sqlite3 databases/vault.db "ANALYZE;"
```
@ -47,7 +47,7 @@ sqlite3 databases/vault.db "ANALYZE;"
# monthly-maintenance.sh
for db in databases/*.db; do
echo "Optimizing $db"
echo "Optimising $db"
sqlite3 "$db" "PRAGMA optimize;"
sqlite3 "$db" "PRAGMA wal_checkpoint(TRUNCATE);"
done

16
docs/guide/alternatives.md
View file

@ -1,10 +1,10 @@
# Comparison with Alternatives
VaultLink is one of several solutions for synchronizing Obsidian vaults. This page compares VaultLink with popular alternatives to help you choose the right tool.
VaultLink is one of several solutions for synchronising Obsidian vaults. This page compares VaultLink with popular alternatives to help you choose the right tool.
## Key Differentiator: Editor Agnostic
**VaultLink is not tied to Obsidian.** While it includes an Obsidian plugin for convenience, VaultLink synchronizes plain text files and works with any editor:
**VaultLink is not tied to Obsidian.** While it includes an Obsidian plugin for convenience, VaultLink synchronises plain text files and works with any editor:
- Edit with **Obsidian desktop** on your laptop
- Edit with **Vim** on your server
@ -12,7 +12,7 @@ VaultLink is one of several solutions for synchronizing Obsidian vaults. This pa
- Edit with **Obsidian mobile** on your phone
- Use the **CLI client** for automated workflows
All changes merge automatically without conflict markers, regardless of which editor you use. This is possible because VaultLink uses [reconcile-text](/architecture/sync-algorithm#why-reconcile-text-over-crdts) for differential synchronization rather than requiring operation-level tracking.
All changes merge automatically without conflict markers, regardless of which editor you use. This is possible because VaultLink uses [reconcile-text](/architecture/sync-algorithm#why-reconcile-text-over-crdts) for differential synchronisation rather than requiring operation-level tracking.
## VaultLink's Core Strengths
@ -136,7 +136,7 @@ Before diving into comparisons:
**Downloads**: ~1.4M
**Repository**: https://github.com/denolehov/obsidian-git
**Overview**: Uses Git for version control and synchronization.
**Overview**: Uses Git for version control and synchronisation.
| Aspect | Obsidian Git | VaultLink |
| ------------------------- | ----------------------------- | ----------------------- |
@ -173,7 +173,7 @@ Before diving into comparisons:
**Downloads**: ~22,600
**Repository**: https://github.com/LBF38/obsidian-syncthing-integration
**Overview**: Wrapper around Syncthing for file synchronization.
**Overview**: Wrapper around Syncthing for file synchronisation.
| Aspect | Syncthing Integration | VaultLink |
| ------------------------- | ------------------------------ | ----------------- |
@ -228,7 +228,7 @@ Before diving into comparisons:
**Downloads**: ~5,000
**Repository**: https://github.com/alex-donnan/SyncFTP
**Overview**: Simple FTP-based file synchronization.
**Overview**: Simple FTP-based file synchronisation.
| Aspect | SyncFTP | VaultLink |
| ------------------------- | ---------------------- | ---------------- |
@ -239,7 +239,7 @@ Before diving into comparisons:
**When to use SyncFTP**: Don't use SyncFTP for any scenario where data integrity matters.
**When to use VaultLink**: Any scenario requiring reliable synchronization.
**When to use VaultLink**: Any scenario requiring reliable synchronisation.
---
@ -270,7 +270,7 @@ VaultLink is the **only** solution that combines:
2. **Editor agnostic** operation (not locked to Obsidian)
3. **Automatic conflict-free merging** using operational transformation
4. **Real-time collaborative editing** with cursor tracking
5. **Differential synchronization** supporting out-of-band edits
5. **Differential synchronisation** supporting out-of-band edits
6. **Comprehensive test coverage** ensuring reliability
7. **Simple deployment** via Docker or single binary

2
docs/guide/cli-client.md
View file

@ -195,7 +195,7 @@ vaultlink \
### Long-Running Sync
Run as a daemon for continuous synchronization:
Run as a daemon for continuous synchronisation:
```bash
docker run -d \

4
docs/guide/obsidian-plugin.md
View file

@ -96,7 +96,7 @@ 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 synchronization
4. Begins real-time synchronisation
Initial sync time depends on vault size and `sync_concurrency` setting.
@ -107,7 +107,7 @@ 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 synchronized
- **File renames**: Tracked and synchronised
The plugin watches your vault filesystem and syncs changes in real-time via WebSocket.

2
docs/guide/server-setup.md
View file

@ -347,7 +347,7 @@ docker logs vaultlink-server
- Reduce `max_connections_per_vault`
- Reduce `max_clients_per_vault`
- Check for large vaults (may need database optimization)
- Check for large vaults (may need database optimisation)
### Database corruption

2
docs/guide/what-is-vaultlink.md
View file

@ -13,7 +13,7 @@ Syncing Obsidian vaults across devices or sharing with teammates sucks:
## VaultLink's Solution
Differential synchronization with operational transformation.
Differential synchronisation with operational transformation.
Edit files with Obsidian, Vim, VS Code, or any editor. VaultLink compares versions and automatically merges all changes. No operation tracking required, no conflict markers, no data loss.

6
docs/package.json
View file

@ -8,12 +8,16 @@
"build": "vitepress build",
"preview": "vitepress preview",
"format": "prettier --write \"**/*.md\" \"**/*.mts\"",
"format:check": "prettier --check \"**/*.md\" \"**/*.mts\""
"format:check": "prettier --check \"**/*.md\" \"**/*.mts\"",
"spell": "cspell \"**/*.md\" \"**/*.mts\"",
"spell:check": "cspell \"**/*.md\" \"**/*.mts\""
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"@cspell/dict-en-gb": "^5.0.19",
"cspell": "^9.3.2",
"prettier": "^3.6.2",
"vitepress": "^1.6.4",
"vue": "^3.5.24"