The Architecture of Cross-Platform Vault Filename Hazards
Personal knowledge management systems built on local Markdown files rely heavily on filesystem stability. Unlike proprietary cloud databases that store notes behind opaque numerical IDs, file-first systems use the note path itself as the permanent address. When filenames contain non-standard Unicode normalization forms, invisible codepoints, or reserved OS characters, note synchronization across macOS, Windows, Linux, and iOS breaks in silent and frustrating ways.
Canonical Composition (NFC) versus Decomposition (NFD)
The Unicode standard provides multiple representations for characters with diacritical marks. In precomposed form (Normalization Form C or NFC), an accented glyph like é is recorded as a single codepoint (U+00E9). In decomposed form (Normalization Form D or NFD), the same character is recorded as two distinct codepoints: the base ASCII letter e (U+0065) followed by the combining acute accent (U+0301).
Historically, macOS filesystems (HFS+ and APFS) enforce decomposed NFD representation for directory entries. In contrast, Windows NTFS, Linux ext4, and modern git repositories operate natively on precomposed NFC. When a vault repository is shared across these environments, git may register phantom modifications on every checkout, or Obsidian wikilinks such as [[café]] may fail to resolve because the link query byte sequence does not match the disk entry bytes.
Invisible Codepoints and Accidental Pastes
Note titles frequently originate from copied clipboard text—such as webpage headlines, academic papers, and PDF outlines. Web typography frequently inserts zero-width spaces (U+200B), word joiners (U+2060), and non-breaking spaces (U+00A0) to manage justification and line breaks.
When pasted into a note title, these codepoints remain invisible inside graphical desktop file explorers. However, command-line operations, backup rsync tasks, and wikilink autocompletion match on exact byte strings. The presence of a single hidden zero-width character produces baffling errors where two notes appear identical on screen yet exist as separate documents on disk.
Trojan Source and Bidirectional Overrides
The Unicode bidirectional algorithm (Bidi) accommodates right-to-left scripts such as Arabic and Hebrew. Control characters such as Right-to-Left Override (U+202E) and Left-to-Right Override (U+202D) alter the visual presentation order of subsequent text.
In computing security (formally analyzed under CVE-2021-42574), this mechanism can be abused to execute extension spoofing. For example, a file physically named summary[U+202E]fdp.sh will visually display in macOS Finder and file managers as summaryhs.pdf. Running or opening such a file poses critical security risks. This inspector highlights all directional overrides as critical hazards.
Legacy MS-DOS Device Names and Windows Filesystem Constraints
While modern Unix operating systems permit almost any byte except the null terminator and the forward slash in filenames, Windows filesystems enforce strict legacy rules dating back to CP/M and MS-DOS. Basenames corresponding to reserved peripheral devices—including CON, PRN, AUX, NUL, COM1 through COM9, and LPT1 through LPT9—cannot be opened, read, or deleted using standard Win32 APIs, even when saved with a .md extension.
Additionally, characters including :, *, ?, ", <, >, and | are strictly forbidden on Windows. A vault note created on a Mac with a question mark (e.g. Why does this work?.md) will fail to synchronize when pulled onto a Windows workstation, often aborting git operations or leaving corrupted sync stubs.
Mixed Script Homoglyphs
The Unicode charset includes scripts with visually indistinguishable characters. The Cyrillic small letter "а" (U+0430) looks identical to the Latin small letter "a" (U+0061) in standard monospaced and sans-serif fonts. When a filename inadvertently contains mixed scripts, users may type standard Latin queries into their search bar and find that the target note is never indexed.
Step-by-Step Vault Normalization Protocol
- Inventory your vault files: Open your terminal inside your vault root and list all paths using
git ls-filesorfind . -name "*.md". - Paste into the inspector: Paste your list into the audit box above to immediately categorize normalization forms, invisible codepoints, and platform traps.
- Examine the audit matrix: Review the proposed safe filenames. All diacritics are preserved in standardized NFC composition, invisible bytes are purged, and Windows-incompatible characters are converted to safe delimiters.
- Run non-destructive renames: Copy the generated bash script. The script uses
mv -n(no-clobber) and checks for file collisions before executing, guaranteeing that no notes are accidentally overwritten. - Update wikilink references: After renaming, execute a batch search-and-replace or vault link re-indexer to update any existing wikilinks pointing to the old decomposed names.