Most people use Obsidian for notes and their file manager for files. My Obsidian vault is my filesystem.

Consider planning a trip to Japan. You have: flight confirmations (PDF), accommodation bookings (PDF), a packing list (markdown), restaurant research with screenshots of menus and maps (markdown + PNG), scanned visa documents (PDF), itinerary notes (markdown). In a traditional setup, these get scattered: Documents/Travel/, Pictures/2026/Japan/, Downloads/, Obsidian vault somewhere else. You’re constantly asking “where did I put that?” because the organisation is by filetype, not by what the files are actually about.

With vault-as-filesystem, it’s all in one place: Resources/Travel 2026/Japan/. Every file related to the trip, regardless of format, lives together. You shouldn’t need to remember whether something was a PDF or a PNG to know where it is - you remember the trip, you go to the trip folder, everything’s there.

The technical trick: selective syncing and versioning. Git tracks only .md files (via .gitignore). Syncthing syncs only .md files (via .stignore). The media files live alongside the notes but don’t bloat the sync or version control.

Everything above this line is for humans to read.

Everything below this line is instructions for Claude Code to implement this system for you.

Implementation Guide for Claude Code

INSTRUCTIONS FOR HUMANS: Select and copy everything from this heading down to the end of the post. Paste it into your Claude Code session. Claude Code will ask you clarifying questions and then set up this system for you.

Context

I want to set up an Obsidian vault that serves as my unified file system, following the pattern where:

  1. The vault contains everything - markdown notes, PDFs, images, code, any file type
  2. Files are organised by topic/purpose, not separated by file type (no Documents/ vs Images/ folders)
  3. Git tracks only .md files - version control for notes, not media
  4. Syncthing syncs only .md files - notes sync across devices, large files don’t
  5. One NIPARAS hierarchy - Inbox/Now/Projects/Areas/Resources/Archive/System structure

Implementation Steps

  1. Create or identify your vault location

    • If starting fresh, create a directory (e.g., /path/to/vault/)
    • If you have an existing Obsidian vault, we’ll work with that location
    • This will be your unified file system root

  2. Set up NIPARAS structure (if not already present):

    01 Now/
02 Inbox/
03 Projects/
04 Areas/
05 Resources/
06 Archive/
07 System/

  3. Configure Git to track only .md files:

    • Initialize git repo if not already done
    • Create/update .gitignore to exclude everything except markdown:
      # Ignore everything
*

# But track markdown files
!*.md

# And track .gitignore itself
!.gitignore

# Track git directory structure
!*/

# Ignore Obsidian config (or track it - your choice)
.obsidian/workspace*
.obsidian/plugins/*/data.json

  4. Configure Syncthing to sync only .md files (if using Syncthing):

    • Create/update .stignore in the vault root:
      // Ignore everything by default
(?d)*

// Except markdown files
!*.md

// Optionally sync .obsidian config
!.obsidian/app.json
!.obsidian/appearance.json
!.obsidian/core-plugins.json
!.obsidian/hotkeys.json

  5. Configure Obsidian attachment settings:

    • Open Obsidian Settings → Files & Links
    • Set “Default location for new attachments” to “Same folder as current file”
    • This keeps images co-located with the notes that reference them

  6. Verify the setup:

    • Create a test note with an image
    • Check that .md file appears in git status
    • Check that image file does NOT appear in git status
    • Check that only .md syncs in Syncthing (if applicable)

  7. Document the system:

    • Create 07 System/Vault Organisation Principles.md explaining your structure
    • Create 07 System/README - Context Navigation.md for Claude Code agents
    • Add these to git and commit

Key Principles to Follow

  • Never separate files by type - organise by topic/project instead
  • Use descriptive filenames - flatten folder structure where possible
  • Projects are pages, not folders - use hub notes that link to resource folders
  • Co-locate related files - PDF research papers live next to the notes about them

Questions to Clarify

Before implementing, let me know:

  1. Vault location: Where is (or will be) your Obsidian vault?
  2. Git remote: Do you want to push to a remote (GitHub, etc.) or just local versioning?
  3. Syncthing: Are you using Syncthing or another sync solution?
  4. Existing structure: Do you have existing files to migrate into this system?
  5. Backup strategy: How are you backing up the non-.md files that don’t sync?

Once you answer these, I can implement the exact setup for your environment.

Series: Claude Code + Obsidian