simple-notes-sync/docs/DESKTOP.md

Desktop Integration 🖥️

🌍 Languages: Deutsch · English

Edit your notes with any Markdown editor on desktop

---

📋 Overview

Desktop integration allows you to edit notes on PC/Mac:

• 📝 Any Markdown editor works
• 🔄 Automatic synchronization via WebDAV
• 💾 Dual-format: JSON (master) + Markdown (mirror)
• ⚡ Last-Write-Wins conflict resolution

---

🎯 Why Markdown?

Dual-Format Architecture

┌─────────────────────────────────────┐
│         Android App                 │
│                                     │
│  ┌──────────┐      ┌─────────────┐ │
│  │   JSON   │ ──→  │  Markdown   │ │
│  │ (Master) │      │  (Mirror)   │ │
│  └──────────┘      └─────────────┘ │
└────────┬────────────────┬───────────┘
         │                │
         ↓                ↓
    WebDAV Server
         │                │
    ┌────┴────┐      ┌────┴──────┐
    │ /notes/ │      │ /notes-md/│
    │ *.json  │      │ *.md      │
    └─────────┘      └───────────┘
         ↑                ↑
         │                │
    ┌────┴────────────────┴───────────┐
    │      Desktop Editor              │
    │  (VS Code, Typora, etc.)         │
    └──────────────────────────────────┘

Advantages

JSON (Master):

• ✅ Reliable and fast
• ✅ Structured data (IDs, timestamps)
• ✅ Primary sync mechanism
• ✅ Always active

Markdown (Mirror):

• ✅ Human-readable
• ✅ Desktop editor compatible
• ✅ Syntax highlighting
• ✅ Optionally activatable

---

🚀 Quick Start

1. First Synchronization

Important: Perform a sync FIRST before activating desktop integration!

1. Set up app (see QUICKSTART.en.md)
2. Test server connection
3. Create first note
4. Synchronize (pull-to-refresh or auto-sync)
5. ✅ Server automatically creates /notes/ and /notes-md/ folders

2. Activate Desktop Integration

1. Settings → Desktop Integration
2. Toggle ON
3. Initial export starts - Shows progress (X/Y)
4. ✅ All existing notes are exported as .md

3. Mount WebDAV as Network Drive

Windows

1. Open Explorer
2. Right-click on "This PC"
3. "Map network drive"
4. Enter URL: http://YOUR-SERVER:8080/notes-md/
5. Username: noteuser
6. Password: (your WebDAV password)
7. Drive letter: Z:\ (or any)
8. Done!

Access: Z:\ in Explorer

macOS

1. Open Finder
2. Menu "Go" → "Connect to Server" (⌘K)
3. Server address: http://YOUR-SERVER:8080/notes-md/
4. Connect
5. Username: noteuser
6. Password: (your WebDAV password)
7. Done!

Access: Finder → Network → notes-md

Linux (GNOME)

1. Open Files / Nautilus
2. "Other Locations"
3. "Connect to Server"
4. Server address: dav://YOUR-SERVER:8080/notes-md/
5. Username: noteuser
6. Password: (your WebDAV password)
7. Done!

Access: /run/user/1000/gvfs/dav:host=...

Linux (davfs2 - permanent)

# Installation
sudo apt install davfs2

# Create mount point
sudo mkdir -p /mnt/notes-md

# Mount once
sudo mount -t davfs http://YOUR-SERVER:8080/notes-md/ /mnt/notes-md

# Permanent in /etc/fstab
echo "http://YOUR-SERVER:8080/notes-md/ /mnt/notes-md davfs rw,user,noauto 0 0" | sudo tee -a /etc/fstab

Access: /mnt/notes-md/

---

📝 Markdown Editors

Recommended Editors

1. VS Code ⭐ Recommended

Advantages:

• ✅ Free & open source
• ✅ Markdown preview (Ctrl+Shift+V)
• ✅ Syntax highlighting
• ✅ Git integration
• ✅ Extensions (spell check, etc.)

Setup:

1. Install VS Code
2. Mount WebDAV drive
3. Open folder: Z:\notes-md\ (Windows) or /mnt/notes-md (Linux)
4. Done! Edit Markdown files

Extensions (optional):

• Markdown All in One - Shortcuts & preview
• Markdown Preview Enhanced - Better preview
• Code Spell Checker - Spell checking

2. Typora

Advantages:

• ✅ WYSIWYG Markdown editor
• ✅ Minimalist design
• ✅ Live preview
• ⚠️ Paid (~15€)

Setup:

1. Install Typora
2. Mount WebDAV
3. Open folder in Typora
4. Edit notes

3. Notepad++

Advantages:

• ✅ Lightweight
• ✅ Fast
• ✅ Syntax highlighting
• ⚠️ No Markdown preview

Setup:

1. Install Notepad++
2. Mount WebDAV
3. Open files directly

4. Obsidian

Advantages:

• ✅ Second brain philosophy
• ✅ Graph view for links
• ✅ Many plugins
• ⚠️ Sync conflicts possible (2 masters)

Setup:

1. Install Obsidian
2. Open WebDAV as vault
3. Caution: Obsidian creates own metadata!

⚠️ Not recommended: Can alter frontmatter

---

📄 Markdown File Format

Structure

Each note is exported as .md file with YAML frontmatter:

---
id: abc-123-def-456
created: 2026-01-05T14:30:22Z
updated: 2026-01-05T14:30:22Z
tags: []
---

# Note Title

Note content here...

Frontmatter Fields

Field	Type	Description	Required
id	UUID	Unique note ID	✅ Yes
created	ISO8601	Creation date	✅ Yes
updated	ISO8601	Modification date	✅ Yes
tags	Array	Tags (future)	❌ No

Filenames

Sanitization rules:

Title: "My Shopping List 🛒"
→ Filename: "My_Shopping_List.md"

Removed:
- Emojis: 🛒 → removed
- Special chars: / \ : * ? " < > | → removed
- Multiple spaces → single space
- Spaces → underscore _

Examples:

"Meeting Notes 2026" → "Meeting_Notes_2026.md"
"To-Do: Project" → "To-Do_Project.md"
"Vacation ☀️" → "Vacation.md"

---

🔄 Synchronization

Workflow: Android → Desktop

1. Create/edit note in app
2. Run sync (auto or manual)
3. JSON is uploaded (/notes/abc-123.json)
4. Markdown is exported (/notes-md/Note_Title.md) (only if Desktop Integration ON)
5. Desktop editor shows changes (after refresh)

Workflow: Desktop → Android

1. Edit Markdown file (in mounted folder)
2. Save - File is immediately on server
3. In app: Run Markdown import
   • Settings → "Import Markdown Changes"
   • Or: Auto-import on every sync (future)
4. App adopts changes (if desktop version is newer)

Conflict Resolution: Last-Write-Wins

Rule: Newest version (by updated timestamp) wins

Example:

App version:     updated: 2026-01-05 14:00
Desktop version: updated: 2026-01-05 14:30
→ Desktop wins (newer timestamp)

Automatic:

• ✅ On Markdown import
• ✅ On JSON sync
• ⚠️ No merge conflicts - only complete overwrite

---

⚙️ Settings

Desktop Integration Toggle

Settings → Desktop Integration

ON (activated):

• ✅ New notes → automatically exported as .md
• ✅ Updated notes → .md update
• ✅ Deleted notes → .md remains (future: also delete)

OFF (deactivated):

• ❌ No Markdown export
• ✅ JSON sync continues normally
• ✅ Existing .md files remain

Initial Export

What happens on activation:

1. All existing notes are scanned
2. Progress dialog shows progress (e.g., "23/42")
3. Each note is exported as .md
4. On errors: Individual note is skipped
5. Success message with number of exported notes

Time: ~1-2 seconds per 50 notes

---

🛠️ Advanced Usage

Manual Markdown Creation

You can create .md files manually:

---
id: 00000000-0000-0000-0000-000000000001
created: 2026-01-05T12:00:00Z
updated: 2026-01-05T12:00:00Z
---

# New Desktop Note

Content here...

⚠️ Important:

• id must be valid UUID (e.g., with uuidgen.io)
• Timestamps in ISO8601 format
• Frontmatter enclosed with ---

Bulk Operations

Edit multiple notes at once:

1. Mount WebDAV
2. Open all .md files in VS Code
3. Find & Replace across all files (Ctrl+Shift+H)
4. Save
5. In app: "Import Markdown Changes"

Scripting

Example: Sort all notes by date

#!/bin/bash
cd /mnt/notes-md/

# Sort all .md files by update date
for file in *.md; do
  updated=$(grep "^updated:" "$file" | cut -d' ' -f2)
  echo "$updated $file"
done | sort

---

❌ Troubleshooting

"404 Not Found" when mounting WebDAV

Cause: /notes-md/ folder doesn't exist

Solution:

1. Perform first sync - Folder is created automatically
2. OR: Create manually via terminal:

   curl -X MKCOL -u noteuser:password http://server:8080/notes-md/
   

Markdown files don't appear

Cause: Desktop integration not activated

Solution:

1. Settings → "Desktop Integration" ON
2. Wait for initial export
3. Refresh WebDAV folder

Changes from desktop don't appear in app

Cause: Markdown import not executed

Solution:

1. Settings → "Import Markdown Changes"
2. OR: Wait for auto-sync (future feature)

"Frontmatter missing" error

Cause: .md file without valid YAML frontmatter

Solution:

1. Open file in editor
2. Add frontmatter at the beginning:

   ---
   id: NEW-UUID-HERE
   created: 2026-01-05T12:00:00Z
   updated: 2026-01-05T12:00:00Z
   ---
   

3. Save and import again

---

🔒 Security & Best Practices

Do's ✅

• ✅ Backup before bulk edits - Create local backup
• ✅ One editor at a time - Don't edit in app AND desktop in parallel
• ✅ Wait for sync - Run sync before desktop editing
• ✅ Respect frontmatter - Don't change manually (unless you know what you're doing)

Don'ts ❌

• ❌ Parallel editing - App and desktop simultaneously → conflicts
• ❌ Delete frontmatter - Note can't be imported anymore
• ❌ Change IDs - Note is recognized as new
• ❌ Manipulate timestamps - Conflict resolution doesn't work

Recommended Workflow

1. Sync in app (pull-to-refresh)
2. Open desktop
3. Make changes
4. Save
5. In app: "Import Markdown Changes"
6. Verify
7. Run another sync

---

📊 Comparison: JSON vs Markdown

Aspect	JSON	Markdown
Format	Structured	Flowing text
Readability (human)	⚠️ Medium	✅ Good
Readability (machine)	✅ Perfect	⚠️ Parsing needed
Metadata	Native	Frontmatter
Editors	Code editors	All text editors
Sync speed	✅ Fast	⚠️ Slower
Reliability	✅ 100%	⚠️ Frontmatter errors possible
Mobile-first	✅ Yes	❌ No
Desktop-first	❌ No	✅ Yes

Conclusion: Using both formats = Best experience on both platforms!

---

🔮 Future Features

Planned for v1.3.0+:

• ⏳ Auto-Markdown-import - Automatically on every sync
• ⏳ Bidirectional sync - Without manual import
• ⏳ Markdown preview - In the app
• ⏳ Conflict UI - On simultaneous changes
• ⏳ Tags in frontmatter - Synchronized with app
• ⏳ Attachments - Images/files in Markdown

---

📚 See also:

• QUICKSTART.en.md - App setup
• FEATURES.en.md - Complete feature list
• BACKUP.en.md - Backup & restore

Last update: v1.2.1 (2026-01-05)