From aaeca588fb959281b8e4cb7b518a63fbcd097877 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Sat, 22 Nov 2025 12:42:16 +0000 Subject: [PATCH] Enforce british english --- .github/workflows/deploy-docs.yml | 5 ++ docs/.cspell.json | 92 +++++++++++++++++++++++++++++ docs/.vitepress/config.mts | 2 +- docs/README.md | 16 ++++- docs/architecture/data-flow.md | 2 +- docs/architecture/index.md | 6 +- docs/architecture/sync-algorithm.md | 14 ++--- docs/config/advanced.md | 10 ++-- docs/guide/alternatives.md | 16 ++--- docs/guide/cli-client.md | 2 +- docs/guide/obsidian-plugin.md | 4 +- docs/guide/server-setup.md | 2 +- docs/guide/what-is-vaultlink.md | 2 +- docs/package.json | 6 +- 14 files changed, 147 insertions(+), 32 deletions(-) create mode 100644 docs/.cspell.json diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 49829998..e1c3bcf8 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -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 diff --git a/docs/.cspell.json b/docs/.cspell.json new file mode 100644 index 00000000..4967ec16 --- /dev/null +++ b/docs/.cspell.json @@ -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" + ] +} diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index d901bfde..64d77100 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -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", diff --git a/docs/README.md b/docs/README.md index 7a9f4522..bfeb0ee7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md index d11977b8..5b256f1d 100644 --- a/docs/architecture/data-flow.md +++ b/docs/architecture/data-flow.md @@ -33,7 +33,7 @@ sequenceDiagram ### 2. Initial Sync -After authentication, the client performs initial synchronization: +After authentication, the client performs initial synchronisation: ```mermaid sequenceDiagram diff --git a/docs/architecture/index.md b/docs/architecture/index.md index f210b3e1..5d4c6d73 100644 --- a/docs/architecture/index.md +++ b/docs/architecture/index.md @@ -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 diff --git a/docs/architecture/sync-algorithm.md b/docs/architecture/sync-algorithm.md index 47fa07fb..eb55e9a4 100644 --- a/docs/architecture/sync-algorithm.md +++ b/docs/architecture/sync-algorithm.md @@ -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 diff --git a/docs/config/advanced.md b/docs/config/advanced.md index 4e129a04..72052d50 100644 --- a/docs/config/advanced.md +++ b/docs/config/advanced.md @@ -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 diff --git a/docs/guide/alternatives.md b/docs/guide/alternatives.md index 5e9b8977..7f314127 100644 --- a/docs/guide/alternatives.md +++ b/docs/guide/alternatives.md @@ -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 diff --git a/docs/guide/cli-client.md b/docs/guide/cli-client.md index ba132908..eeb11131 100644 --- a/docs/guide/cli-client.md +++ b/docs/guide/cli-client.md @@ -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 \ diff --git a/docs/guide/obsidian-plugin.md b/docs/guide/obsidian-plugin.md index c87debf5..5b63e43d 100644 --- a/docs/guide/obsidian-plugin.md +++ b/docs/guide/obsidian-plugin.md @@ -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. diff --git a/docs/guide/server-setup.md b/docs/guide/server-setup.md index 9b39d5bc..bf09c5e6 100644 --- a/docs/guide/server-setup.md +++ b/docs/guide/server-setup.md @@ -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 diff --git a/docs/guide/what-is-vaultlink.md b/docs/guide/what-is-vaultlink.md index 9bb5addb..a7dee7c7 100644 --- a/docs/guide/what-is-vaultlink.md +++ b/docs/guide/what-is-vaultlink.md @@ -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. diff --git a/docs/package.json b/docs/package.json index a0d630a4..6904b5e5 100644 --- a/docs/package.json +++ b/docs/package.json @@ -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"