🌐 04. Blog & Sync

Publish and synchronize content effortlessly.
FlashNote is designed not only as an offline scratchpad, but as a modern visual authoring and publishing hub for static blogs (such as MagicNote based on VitePress).

📑 In This Guide

1. Direct-to-Blog Pipeline Setup
2. Pre-publish Validation Gate
3. Understanding “Pending Sync” States
4. Backup, Restore & Multi-Device Sync
5. Publish Failures & Conflict Resolution

1. Direct-to-Blog Pipeline Setup

1.1 Why Direct-to-Blog?

Traditional static site maintenance requires terminal commands, manual YAML FrontMatter editing, and copying screenshots. FlashNote turns your browser sidebar into an integrated publishing pipeline:

• Visual Authoring Without Config Hassle: Write in rich text; metadata such as titles, dates, tags, and slugs are managed automatically;
• Strict Physical Sandbox Isolation: Only folders with blog sync enabled are built into public posts; private notes are strictly safeguarded.

1.2 Configuration Steps

1. Navigate to FlashNote “Settings” -> “Blog Direct & Publishing”;
2. Bind the local or remote repository directory of your blog;
3. Enable [Blog Sync] for designated public folders (e.g., tech, posts);
4. Non-public folders (such as private, journal) remain strictly sandboxed.

2. Pre-publish Validation Gate

To prevent broken links and missing assets, FlashNote includes a three-state Readiness Gate:

Publishing Checklist:

1. Preview Layout: Switch to “Preview Mode” to inspect code highlights, KaTeX formulas, and diagrams;
2. Slug Uniqueness: Automated check prevents overwriting existing posts with identical slugs;
3. Path Traversal Protection: Sanitizer strips relative escape tokens like ../ to ensure assets stay strictly within destination folders.

3. Understanding “Pending Sync” States

When cloud sync is active, the status indicator reflects a strict 4-State Atomic Machine:

• idle: Local and remote fingerprints match; all changes synchronized;
• pending: New or modified notes queued for microtask synchronization;
• syncing: Actively exchanging differential hashes and payloads with WebDAV / OneDrive / Baidu Pan;
• error: Network interruption, credential expiration, or conflict detected.

The state machine prevents high-concurrency re-entrancy, ensuring zero data corruption during network instability.

4. Backup, Restore & Multi-Device Sync

• RFC 9562 UUID v7 Keys: Notes and chapter IDs embed monotonically increasing timestamps, ensuring chronological merging even after offline work on multiple machines;
• Chunked Differential Hashes: Only modified text deltas are transmitted, drastically minimizing bandwidth;
• Seamless Multi-Device Roaming: Configure matching cloud credentials on work and home laptops for real-time two-way sync.

5. Publish Failures & Conflict Resolution

5.1 Troubleshooting Publishing Failures

• Blocked Status: Verify that a title is set and that the slug is unique;
• Target Folder Not Writable: Check if your browser still holds File System Access permissions for the target folder.

5.2 Conflict Resolution

If the same note is edited offline across two devices simultaneously:

1. FlashNote retains the version with the most recent timestamp;
2. Automatically saves the other machine’s version as Original Title - Conflict Copy [Timestamp];
3. A conflict alert appears, allowing you to review both versions side by side without losing data.