Importing from Obsidian

Import from Obsidian

Strayfiles can import notes from your Obsidian vault. The import is non-destructive - your original files stay where they are, and Strayfiles tracks them using your preferred method (Frontmatter or HTML Comment).

Access the import wizard:

• TUI: Settings → Advanced → Import from Obsidian
• macOS App: File → Import from Obsidian (⌘⇧I)

Note: Obsidian import requires desktop access (TUI or macOS). iOS is a cloud-only interface without filesystem access.

What the Import Does

1. Detects your vault - Validates the Obsidian vault folder (looks for .obsidian/)
2. Scans for markdown files - Finds all .md and .mdx files
3. Lets you choose tracking method - Frontmatter or HTML Comment
4. Converts wiki links - Optionally converts [[wiki links]] to standard markdown
5. Tracks your files - Embeds UUID via your chosen method

Your Obsidian folder structure is preserved. Files are tracked in-place, not copied.

Step-by-Step Wizard

The import wizard guides you through six steps:

Step 1: Select Vault

Browse to your Obsidian vault folder or paste the path directly.

~/Documents/ObsidianVault/

The wizard validates that the folder contains a .obsidian/ directory and shows a summary:

• Number of markdown files found
• Number of folders in the vault

Step 2: Select Files

Review all discovered markdown files. The wizard shows:

• File path relative to vault root
• File size
• Wiki link count (if any)
• Whether the file already has strayfiles metadata

Select which files to import. By default, all files are selected.

Files already tracked by Strayfiles are flagged with “Already tracked” - you can skip these or re-import them.

Step 3: Select Tracking Method

Choose how Strayfiles should track your imported files:

Method	Description
Frontmatter	Adds a strayfiles: YAML block at the top of each file
HTML Comment	Adds an invisible <!-- strayfiles: {...} --> comment

When to use each method:

• Frontmatter - Best for regular notes and personal documentation. The YAML block is a standard format that many tools understand.
• HTML Comment - Best for README files and public documentation. The comment is invisible when rendered, so readers won’t see the tracking metadata.

Both methods embed the UUID directly in the file, so tracking survives renames and moves. This is more robust than path-based tracking.

Note: Both TUI and macOS SwiftUI apps support Frontmatter and HTML Comment methods.

Step 4: Configure Options

Choose how you want the import to behave:

Option	Default	Description
Convert wiki links	On	Converts [[wiki links]] to [wiki links](path)
Preserve folder structure	On	Keeps your folder hierarchy as directories
Modify in place	On	Applies changes to original files

Step 5: Importing

The wizard processes your files:

• Injects tracking metadata using your chosen method
• Converts wiki links and embeds (if enabled)
• Reports progress

Step 6: Results

See a summary of the import:

• Number of files successfully imported
• Number of warnings (e.g., unresolved links)
• Number of errors (if any)
• Wiki links and embeds converted

What Gets Converted

Wiki links are converted to standard markdown:

<!-- Before -->
[[My Note]]
[[folder/My Note]]
[[My Note|Display Text]]

<!-- After -->
[My Note](My Note.md)
[My Note](folder/My Note.md)
[Display Text](My Note.md)

Embeds are converted to image/link syntax:

<!-- Before -->
![[image.png]]
![[My Note]]

<!-- After -->
![](image.png)
![My Note](My Note.md)

Comments are converted to HTML comments:

<!-- Before -->
%%This is a comment%%

<!-- After -->
<!-- This is a comment -->

Highlights are converted to HTML mark tags:

<!-- Before -->
==highlighted text==

<!-- After -->
<mark>highlighted text</mark>

What Doesn’t Get Converted

Some Obsidian-specific features are not converted:

Feature	Behavior
> [!callouts]	Preserved as-is - shown as warnings
Dataview queries	Preserved as-is - non-functional outside Obsidian
Templater syntax	Preserved as-is
Obsidian plugins	Not applicable - plugin-specific syntax preserved

Files with callouts are flagged during import so you can review them.

Tips for Obsidian Users

1. Review wiki links before converting

The wizard shows how many wiki links each file contains. If you plan to keep using Obsidian alongside Strayfiles, consider leaving wiki links unconverted.

2. Exclude system folders

By default, the scanner excludes:

• .obsidian/** - Obsidian config
• .trash/** - Obsidian trash

These won’t appear in the file selection.

3. Files stay in place

Unlike some migration tools, Strayfiles doesn’t move or copy your files. Your Obsidian vault continues to work normally after import.

4. Choose your tracking method wisely

• Use Frontmatter for personal notes where you don’t mind visible metadata
• Use HTML Comment for README files and documentation that others will read

Both methods modify the file to embed a UUID, but HTML comments are invisible when rendered.

5. Use workspaces for organization

After import, you can assign notes to workspaces without changing your folder structure. This gives you Obsidian-like organization without touching the filesystem.

Post-Import Workflow

After importing:

1. Assign workspaces - Group related notes into virtual workspaces
2. Add tags - Tag notes for filtering and search
3. Set aliases - Give notes display names different from filenames
4. Enable sync - Optionally sync to Stray Cloud for cross-device access

Troubleshooting

“Invalid vault”

The folder doesn’t contain a .obsidian/ directory. Make sure you’re pointing to the root of your vault.

Unresolved wiki links

Wiki links to files that don’t exist are converted but flagged as warnings. You can fix these manually after import.

Files not appearing

Check that the file extension is .md or .mdx. Other extensions are excluded by default.

Already tracked files

Files that already have strayfiles metadata are flagged. Re-importing them won’t duplicate tracking.

Import vs. Discovery

Feature	Obsidian Import	File Discovery
Use case	Migrate from Obsidian	Track any markdown files
Wiki link conversion	Yes	No
Vault validation	Yes	No
Batch selection	Yes	Yes
Tracking methods	Frontmatter, HTML comment	Frontmatter, HTML comment, User TOML, Project TOML

Use Obsidian Import when migrating from an Obsidian vault. Use File Discovery for tracking arbitrary markdown files.

Note: Obsidian Import supports Frontmatter and HTML Comment methods because these embed the UUID in the file, making tracking robust across renames and moves. File Discovery additionally supports TOML-based tracking for cases where you don’t want to modify the file at all.

TUI Keyboard Shortcuts

When using the TUI (terminal interface), these keyboard shortcuts help navigate the wizard:

Context	Key	Action
Select Vault	Tab	Scan vault path
Select Vault	Enter	Proceed to next step
Select Files	Space	Toggle file selection
Select Files	a	Select all files
Select Files	Tab	Proceed to tracking method
Select Tracking Method	j/k	Navigate options
Select Tracking Method	Enter	Select method and proceed
Select Tracking Method	Shift+Tab	Go back
Configure Options	Tab	Next step
Configure Options	Shift+Tab	Go back
Results	Enter	Close wizard
Any step	Esc	Cancel and exit