The silent decay of attachments in local-first knowledge bases
Markdown's strength is its pure plain-text longevity. However, rich documentation inevitably incorporates binary assets: system architecture screenshots, vector flowcharts, audio interview recordings, and reference PDF specifications. In Obsidian and CommonMark repositories, media is referenced via embedding syntax like ![[architecture.png]] or standard links like .
Over time, attachment links suffer from silent decay. Reorganizing folders moves notes without updating relative asset paths, operating system clipboard drops paste non-portable absolute machine paths, and cloud image hosts suffer link rot. Without an automated attachment audit, broken media references linger undetected until critical documentation is needed.
Audit classifications: from resolved assets to portability risks
The Attachment Path Auditor evaluates every media reference against six operational classifications:
- Resolved (Vault Conformance): The binary file exists in your inventory and resides within your designated assets directory.
- Missing / Broken: The referenced image, audio memo, or PDF cannot be located anywhere in your vault inventory.
- Absolute System Path (High Portability Hazard): References using
file:///Users/...or/Users/name/Desktop/.... These paths work on the author's local desktop but immediately break when synced to mobile devices, shared with colleagues, or moved to another computer. - Remote Web URLs: Images hosted on external HTTP/HTTPS domains. While convenient, remote hosting breaks offline availability and leaves documentation vulnerable to third-party outages.
- Outside Folder: The attachment exists in the vault, but sits in the root folder or an unorganized subfolder rather than your designated
attachments/directory. - Ambiguous Filenames: Multiple files with identical names reside in different directories (e.g.
ui/icon.pngvsbrand/icon.png), making shortest-path resolution unpredictable.
Best practices for organizing Markdown vault media
To ensure decades-long portability for your personal knowledge base:
- Designate a Single Attachment Folder: Configure your editor (such as Obsidian's "Files and Links > Default location for new attachments") to save all media into a dedicated subfolder such as
attachments/. - Eliminate Absolute Paths: Never link files directly from your Desktop or Downloads folder. Always move binaries into your vault before embedding them.
- Localize Cloud Images: Download critical remote diagrams and save them locally to eliminate dependencies on third-party CDNs.
- Audit Before Archiving: Run an attachment path audit prior to publishing wikis or migrating notes across storage engines.
Related local note management tools
Explore complementary utilities designed for clean, resilient Markdown documentation:
- Broken Wikilink Finder: Find dangling note connections, casing mismatches, and dead links.
- Vault Health Inspector: Comprehensive audit of note backlinks, orphan attachments, and file integrity.
- Heading Anchor Checker: Validate section anchor links across GitHub and Obsidian.
- All Tools Directory: Discover private browser-based utilities for Markdown workflows.