Prepare an Obsidian vault for migration

When you decide to evaluate a new note-taking application, the greatest anxiety is rarely about learning a new interface. It is the fear of silent data corruption: broken internal links, orphaned image attachments, lost metadata properties, and unrendered plugin queries across hundreds or thousands of personal documents.

An Obsidian vault is fundamentally just a folder of plain text files on your local disk. That architecture gives you immense portability advantages over proprietary cloud databases. However, because Obsidian’s rich ecosystem allows community plugins, custom link resolution rules, and specialized frontmatter schemas, moving between apps requires preparation.

This preflight guide walks through a disciplined, non-destructive process for auditing, backing up, and validating your vault before trying another note-taking tool.

1. Understand what your vault actually contains

Before moving or inspecting any notes, separate your vault’s contents into three distinct operational layers:

The portable core: Markdown files and folders

Your .md files, nested directories, and standard CommonMark elements (headings, bold text, bulleted lists, standard markdown links, and tables) form the permanent layer of your knowledge base. This layer is universal and renders predictably in virtually any text editor or Markdown application.

The asset layer: Media and attachments

Images (.png, .jpg, .svg), PDF documents, audio clips, and reference files stored throughout your vault. While the files themselves are portable, the syntax used to embed them—and the directory paths used to locate them—differs widely between applications.

The application runtime: Configuration and plugins

The hidden .obsidian/ directory sitting at the root of your vault. This folder houses your theme CSS, hotkeys, core plugin states, workspace layouts, and third-party community plugins. This layer is not part of the Markdown standard. No other note application runs Obsidian community plugins. Recognizing what is content versus what is runtime behavior is the foundation of a safe migration.

2. Step one: Create an isolated sandbox copy

Never test a new application on your primary, active vault folder. Even well-behaved applications create background indexes, cache directories, or temporary lockfiles that can trigger sync conflicts or alter file modification timestamps.

1. Close Obsidian: Ensure all active file handles and background indexing tasks are stopped.
2. Duplicate the vault folder: In macOS Finder, select your vault directory, press ⌘D to duplicate, and rename the copy to Vault-Migration-Test.
3. Generate an immutable archive: Right-click the duplicated folder and select Compress “Vault-Migration-Test” to create a .zip backup. Store this zip file in an external folder or cold backup drive.
4. Isolate your sync client: If your vault is managed by Obsidian Sync, iCloud Drive, or Git, ensure your test copy is moved outside the synced directory tree so test edits do not propagate to other devices.

3. Inventory notes, links, and attachment paths

Once your test sandbox is secure, catalog the scope of your collection. You need clear counts of notes, non-text assets, and how references connect between them.

Attachment storage conventions

Check your Obsidian attachment settings (Settings › Files and links › Default location for new attachments). Obsidian supports four storage modes:

• Vault root folder
• Same folder as current note
• In subfolder under current folder
• Specified folder (e.g. attachments/ or assets/)

If your vault stores attachments in arbitrary subfolders, Obsidian’s link resolver uses “shortest path” logic to find them. If Note A in Work/Projects/ references ![[wireframe.png]], Obsidian searches the entire vault and displays the image even if wireframe.png sits in Archive/Design/.

When moving to applications that enforce strict relative paths (such as standard CommonMark or editors expecting ./attachments/wireframe.png), unrouted attachments will appear broken. Consolidating attachments into a predictable directory structure is one of the highest-value cleanup steps you can perform.

Link format variations

Examine which link conventions dominate your notes:

• Wikilinks ([[Note Name]]): Fast to type, but require the target application to build a full-vault filename index.
• Wikilinks with display aliases ([[Note Name|Display Label]]): Supported by Oyma and several knowledge-base tools, but ignored by standard CommonMark renderers.
• Section anchors ([[Note Name#Heading]]): Points to a specific subhead. Depends on target heading slugification matching between apps.
• Block identifiers ([[Note Name#^block-id]]): Appends an alphanumeric ID to a paragraph. This is an Obsidian-specific construct; other tools display ^block-id as literal text.
• Standard Markdown links ([Display Label](path/to/Note.md)): Universal across all Markdown tools, but fragile when files are renamed outside a specialized link-refactoring editor.

4. Run an automated health audit

Rather than manually opening hundreds of individual notes, run a deterministic health inspection to flag structural issues before testing another tool.

You can use the browser-based Vault Health Inspector, which runs 100% locally in your browser without uploading files or transmitting data over the network. It catalogs your vault and identifies:

1. Broken wikilinks: References pointing to note titles that do not exist anywhere in the vault.
2. Ambiguous short targets: Multiple notes in different directories sharing the same filename (e.g. Projects/Overview.md and Archive/Overview.md). When linked simply as [[Overview]], different applications resolve different documents.
3. Missing heading anchors: Links targeting [[Note#Section]] where the destination note lacks that heading.
4. Unresolved attachments: Embedded media tags where the referenced image or graphic is missing from your attachments folder.
5. Fenced code block immunity: Verifies that code examples containing brackets (such as programming arrays or documentation) are safely ignored and not falsely flagged as broken notes.

You can also download the Vault Health Kit and review the Markdown Vault Preflight Checklist directly in your editor.

5. Audit YAML properties and frontmatter

Modern Obsidian stores note metadata in YAML frontmatter blocks between --- delimiters at the beginning of each file. While standard YAML is portable, specific property implementations require verification:

Date formats

Ensure dates in frontmatter follow ISO 8601 formatting (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss). Freeform dates like October 8th, 2026 or last Tuesday are not recognized by automated filters, calendar bridges, or schema parsers.

Tags in frontmatter

Obsidian accepts tags in frontmatter as either a bracketed list:

---
tags: [research, architecture, privacy]
---

Or as a bulleted YAML array:

---
tags:
  - research
  - architecture
  - privacy
---

Both forms are valid YAML. However, avoid prefixing frontmatter tag values with hash symbols (e.g. tags: [#research]). In YAML specification, # indicates a code comment; in unquoted values, this can truncate or corrupt the property line in other parsers.

Aliases

If you rely heavily on the aliases: property for note linking, be aware that many Markdown applications index files strictly by their file basename on disk rather than checking YAML aliases. Where possible, use explicit pipe aliases in links ([[Actual File|Alternative Title]]) to maintain predictable navigation.

6. Catalog plugin dependencies and dynamic syntax

Community plugins provide immense power in Obsidian, but they represent the largest migration hazard. Plugins store executable instructions inside your notes that other software cannot interpret.

Plugin construct	Syntax example	Behavior in alternative editors	Recommended remediation
Dataview queries	dataview\nTABLE file.mtime\nFROM #project\n	Displays as inert text inside a code block; query does not run.	If dynamic data must be visible, export the query table to static Markdown before archiving.
Tasks plugin	- [ ] Review draft 📅 2026-10-12 🔺	Displays as a standard task checkbox with trailing emoji text.	Task stays checkable; date filtering and priority sorting stop functioning.
Obsidian Canvas	Dashboard.canvas	Not opened or rendered. Canvas files are JSON diagrams, not Markdown.	Keep the JSON file preserved, or export key flowcharts to SVG or PNG graphics.
Excalidraw	Diagram.excalidraw.md	Opens as raw JSON embedded in a Markdown envelope.	Export completed sketches to SVG or PNG files and link the rendered image.
Templater macros	<% tp.date.now("YYYY-MM-DD") %>	Displays as literal syntax text unless executed prior to export.	Execute templates during note creation; do not leave raw execution tags in active notes.

7. Test on a representative subset

Before opening your entire knowledge base in a candidate application, build or isolate a small test corpus containing every structural feature your workflow uses.

A representative test set should include:

• A root-level note linking to a deeply nested note.
• Two notes in different folders sharing the exact same name (to observe how the application handles disambiguation).
• A note containing a valid heading link ([[Note#Heading]]).
• A note with an embedded image located in a dedicated attachments subfolder.
• A note with YAML frontmatter containing tags, aliases, and custom text fields.
• A note containing a fenced code block with bracketed text (to confirm the editor does not parse code snippets as active links).
• A note with non-Latin or Unicode characters in the filename (such as accents or Japanese characters).

Open this test folder in the candidate tool and observe:

1. Do all wikilinks resolve and remain clickable?
2. Do embedded images render cleanly without broken placeholder icons?
3. Does renaming a file update references in connecting notes, or does it leave broken links?
4. Does the application create non-standard configuration directories or alter your files’ line endings?

8. How Oyma handles an Obsidian vault

If you are testing Oyma as your daily note-taking and meeting workflow on macOS, opening an existing Obsidian vault is completely non-destructive:

• Direct folder opening: Point Oyma at your vault folder via File › Open Vault… (⌘⇧O). Notes are indexed directly in memory on your Mac.
• Zero conversion: Oyma does not import, translate, or rewrite your files. Notes remain standard .md files in their original directories.
• Configuration isolation: Oyma leaves your .obsidian/ configuration folder untouched. Its own lightweight local state (such as meeting recordings and audio search index) is stored in a separate hidden .app/ directory that Obsidian ignores.
• Simultaneous editing: You can switch between Obsidian and Oyma freely. Both applications read and write directly to disk, allowing you to use Obsidian for specialized plugin workflows and Oyma for distraction-free writing and botless meeting transcription.

For specific configuration steps, review the companion guide on opening an Obsidian vault and our detailed comparison of Oyma and Obsidian.

9. Preflight summary checklist

Before committing to any note reorganization, verify each item:

• Complete .zip backup created and verified on independent storage.
• Active vault closed; testing conducted solely on a duplicated sandbox directory.
• Attachment storage path reviewed and consolidated if necessary.
• Broken links and ambiguous duplicate note names resolved via Vault Health Inspector.
• Frontmatter YAML formatted cleanly with ISO dates and valid tags.
• Dynamic plugin queries (Dataview, Canvas) documented or exported to static representations.
• Representative test notes validated in the target application before moving your full collection.