Import System

Status: Implemented Depends On: Workspace System, Page System, User Settings

---

Overview

The Import System enables users to bring existing content into Inklings from external sources. It supports markdown folders and Obsidian vaults.

Import Flow

Key Design Decisions

1. Copy, Not Move

Import copies files into the workspace. Original files remain untouched. This is:

• Safe: No risk of data loss
• Reversible: Can re-import if needed
• Clear: User knows where their content lives

2. Preserve Full Structure

Hierarchy is preserved exactly as-is with no depth limit. Deep nesting (5+ levels) triggers an informational warning in the preview, but does NOT prevent or modify the import:

Source (6 levels):          Imported (identical):
world/                      world/
└── regions/                └── regions/
    └── countries/              └── countries/
        └── cities/                 └── cities/
            └── districts/              └── districts/
                └── blocks/                 └── blocks/

Note: The informational warning helps users understand their content organization but respects the original structure.

3. Wiki-link Conversion

Obsidian-style [[wiki links]] converted to standard markdown:

• [[Page Name]] -> [Page Name](./page-name.md)
• [[Page Name|Display]] -> [Display](./page-name.md)

4. Preview Before Commit

Users see what is imported before it happens:

• File count
• Structure preview
• Potential issues (deep nesting, conflicts)
• Estimated time for large imports

Import Sources

Markdown Folder

Direct import of any folder containing .md files:

• Recursively scan for .md files
• Preserve relative structure
• Copy frontmatter as-is
• Generate IDs for pages without them

Obsidian Vault

Specialized handling for Obsidian vaults:

• Convert [[wiki links]] to standard links
• Handle ![[embeds]] (convert to links or inline)
• Map Obsidian frontmatter to Inklings format
• Ignore .obsidian/ config folder

Import Flow

1. Select Source
   └── User picks folder or Obsidian vault

2. Analyze
   └── Scan files, detect issues, build preview

3. Preview
   └── Show what is imported
   └── Highlight issues (deep nesting, conflicts)

4. Configure (optional)
   └── Rename conflicting pages
   └── Choose flatten strategy

5. Import
   └── Copy files with progress indicator
   └── Convert links
   └── Generate index

6. Complete
   └── Show summary
   └── Highlight any warnings

Preview UI

+-------------------------------------------------------------+
| Import Preview                                              |
+-------------------------------------------------------------+
| Source: /Users/user/Obsidian/My Vault                       |
| Type: Obsidian Vault                                        |
|                                                             |
| Files to import: 127                                        |
| Folders: 15                                                 |
|                                                             |
| i 3 folders are deeply nested (5+ levels)                   |
| ! 2 files have name conflicts                               |
|                                                             |
| Preview:                                                    |
| +-- characters/ (24 files)                                  |
| +-- locations/ (18 files)                                   |
| +-- factions/ (12 files)                                    |
| +-- ... 73 more files                                       |
|                                                             |
| [Cancel]                                    [Start Import]  |
+-------------------------------------------------------------+

API Surface

Tauri Commands

// Analyze source for import preview
analyze_import(path: string): Promise<ImportAnalysis>

// Execute import
execute_import(params: ImportParams): Promise<ImportResult>

// Get import progress (for large imports)
get_import_progress(): Promise<ImportProgress>

// Cancel in-progress import
cancel_import(): Promise<void>

TypeScript Types

interface ImportAnalysis {
  source_type: 'markdown' | 'obsidian';
  file_count: number;
  folder_count: number;
  issues: ImportIssue[];
  preview: FolderPreview;
}

interface ImportIssue {
  type: 'deep_nesting' | 'name_conflict' | 'invalid_frontmatter';
  path: string;
  message: string;
  suggestion: string;
}

interface ImportParams {
  source_path: string;
  destination_path?: string; // Default: workspace root
  flatten_strategy: 'preserve' | 'flatten_deep';
  conflict_strategy: 'skip' | 'rename' | 'overwrite';
}

interface ImportResult {
  imported_count: number;
  skipped_count: number;
  warnings: string[];
}

interface ImportProgress {
  total: number;
  completed: number;
  current_file: string;
  phase: 'analyzing' | 'copying' | 'converting' | 'indexing';
}

Link Conversion Rules

Obsidian to Standard Markdown

Obsidian	Standard Markdown
[[Page]]	[Page](./page.md)
[[Page|Display]]	[Display](./page.md)
[[Folder/Page]]	[Page](./folder/page.md)
![[Embed]]	[Embed](./embed.md) (or inline)
[[#Heading]]	[Heading](#heading)

Path Resolution

Links are resolved relative to the page containing them:

• Same folder: ./sibling.md
• Child folder: ./child/page.md
• Parent folder: ../sibling.md

Error Handling

Error	Handling
Unreadable file	Skip, add to warnings
Invalid frontmatter	Import as plain markdown
Circular links	Convert to plain text
Disk full	Stop import, show error, keep partial

Testing Strategy

• Unit: Link conversion, path resolution
• Application: Import analysis, conflict detection
• Infrastructure: File operations with temp directories
• E2E: Full import flow with sample vault

---

This is a “capstone” feature that proves the whole system works together.