Free tool · works now

Unicode Filename Inspector

Inspect vault filenames for Unicode normalization clashes, invisible characters, and cross-platform filesystem hazards.

Runs 100% in your browser. Inspect vault file paths for NFD decomposition, zero-width traps, Trojan Source Bidi overrides, and cross-platform filesystem hazards.

Vault Path Audit Engine
10Files scanned
2Clean files
1NFD decomposed
5Critical hazards
2Invisible / Bidi
Vault file paths listOne relative path per line

Paste outputs from terminal utilities. Supports standard relative paths, directory prefixes, and Markdown bullet lists.

Unicode health audit findings10 items evaluated
CLEAN2026-10-13.md
Path is portable NFC with zero filesystem hazards.
Codepoints:U+0032 U+0030 U+0032 U+0036 U+002D U+0031 U+0030 U+002D U+0031 U+0033 U+002E U+006D U+0064
CLEANalpha-launch.md
Path is portable NFC with zero filesystem hazards.
Codepoints:U+0061 U+006C U+0070 U+0068 U+0061 U+002D U+006C U+0061 U+0075 U+006E U+0063 U+0068 U+002E U+006D U+0064
WARNINGresumé.mdNFD
•Filename is in NFD (decomposed) form. Windows, Linux, and git treat this as different from standard NFC.
Proposed safe name:resumé.md
Codepoints:U+0072 U+0065 U+0073 U+0075 U+006D U+0065 U+0301 U+002E U+006D U+0064
CRITICALmeeting​notes.md
•Filename contains invisible or zero-width codepoints (U+200B).
Proposed safe name:meetingnotes.md
Codepoints:U+006D U+0065 U+0065 U+0074 U+0069 U+006E U+0067 U+200B U+006E U+006F U+0074 U+0065 U+0073 U+002E U+006D U+0064
CRITICALstatement‮fdp.pdf
•Dangerous bidirectional override marker detected (U+202E). Extension or name may be spoofed.
Proposed safe name:statementfdp.pdf
Codepoints:U+0073 U+0074 U+0061 U+0074 U+0065 U+006D U+0065 U+006E U+0074 U+202E U+0066 U+0064 U+0070 U+002E U+0070 U+0064 U+0066
CRITICALquestion:mark*test.md
•Filename contains filesystem reserved characters (: *) forbidden on Windows/FAT/NTFS.
Proposed safe name:question-mark-test.md
Codepoints:U+0071 U+0075 U+0065 U+0073 U+0074 U+0069 U+006F U+006E U+003A U+006D U+0061 U+0072 U+006B U+002A U+0074 U+0065 U+0073 U+0074 U+002E U+006D U+0064
CRITICALaux.md
•Base name "aux" is a reserved DOS device name (CON, PRN, AUX, NUL, COM*, LPT*) invalid on Windows.
Proposed safe name:vault-aux.md
Codepoints:U+0061 U+0075 U+0078 U+002E U+006D U+0064
WARNING project plan .md.
•Filename has leading or trailing spaces. Windows and git trim these, leading to synchronization errors.
•Filename ends with a period. Windows filesystem silently strips trailing dots.
Proposed safe name:project plan .md
Codepoints:U+0020 U+0070 U+0072 U+006F U+006A U+0065 U+0063 U+0074 U+0020 U+0070 U+006C U+0061 U+006E U+0020 U+002E U+006D U+0064 U+002E
WARNINGpаsswords.md
•Filename mixes Latin letters with visually identical Cyrillic or Greek lookalikes (homoglyphs).
Codepoints:U+0070 U+0430 U+0073 U+0073 U+0077 U+006F U+0072 U+0064 U+0073 U+002E U+006D U+0064
CRITICALcachebell.md
•Filename contains non-printable ASCII control characters.
Proposed safe name:cachebell.md
Codepoints:U+0063 U+0061 U+0063 U+0068 U+0065 U+0007 U+0062 U+0065 U+006C U+006C U+002E U+006D U+0064

Click "Copy bash rename script" to inspect and run non-destructive renames in your local terminal.

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

  1. Inventory your vault files: Open your terminal inside your vault root and list all paths using git ls-files or find . -name "*.md".
  2. Paste into the inspector: Paste your list into the audit box above to immediately categorize normalization forms, invisible codepoints, and platform traps.
  3. 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.
  4. 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.
  5. 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.

Questions

Why does Unicode normalization cause problems when syncing Markdown vaults?

macOS traditionally stores filenames using decomposed Unicode (NFD), where accented characters like e-acute are split into an ASCII base letter plus a combining diacritic codepoint. Conversely, Linux, Windows, and modern web systems prefer precomposed Unicode (NFC), where e-acute is represented as a single indivisible codepoint. Although both render identically to human eyes, git, command-line utilities, and wikilink search treat them as different byte sequences, resulting in duplicate ghost files or broken link references.

How do invisible and zero-width characters enter note filenames?

When copying article titles, PDF chapter names, or web headings from browser tabs, invisible formatting codepoints such as zero-width spaces (U+200B), word joiners (U+2060), and UTF-8 Byte Order Marks (U+FEFF) frequently accompany the pasted text. While invisible in graphical file trees, they cause terminal scripts, ripgrep queries, and relative wikilink references to fail unexpectedly.

What is a Bidirectional Override (Trojan Source) hazard in filenames?

Unicode includes bidirectional control characters designed for right-to-left languages such as Arabic and Hebrew. The Right-to-Left Override character (U+202E) forces text engines to render subsequent characters backward. In security analyses known as Trojan Source, this mechanism can disguise executable extensions—making a file that appears as invoice-fdp.pdf actually execute as an executable binary on disk.

Why does Windows refuse filenames like AUX.md or question:mark.md?

The Windows operating system inherits reserved device names from 1980s MS-DOS architectures. Basenames matching CON, PRN, AUX, NUL, COM1 through COM9, or LPT1 through LPT9 cannot be opened, edited, or deleted through standard Windows APIs, regardless of their file extension. Furthermore, Windows prohibits characters such as colons, question marks, asterisks, and pipe symbols, which causes file sync errors when transferring vaults across platforms.

Does the generated rename shell script overwrite my existing notes?

No. The generated bash script exclusively uses the mv -n (no-clobber) flag and incorporates preflight existence checks. If the proposed normalized filename already exists on disk, the script skips the operation and outputs an explicit warning rather than overwriting your note data.

Does this inspector upload or transmit my file paths across the network?

No. All string parsing, Unicode normalization checks, codepoint extraction, and script generation execute entirely within your browser tab memory. No paths, filenames, or directory structures ever leave your device.

Keep your Markdown vault clean, durable, and cross-platform

Private on-device text intelligence and native Markdown editing in Oyma. Keep your vault filenames portable across platforms.

tools unicode filename inspector downloadDownload for Mac

No account needed. Intel Mac build