obsidian-migration-deep-dive

Obsidian Migration Deep Dive

Overview

Comprehensive guide for migrating to Obsidian from other note-taking apps, or performing major plugin architecture rewrites.

Prerequisites

• Source data access
• Understanding of Obsidian vault structure
• Node.js for scripted migrations
• Backup of source data

Migration Types

Type	Complexity	Duration	Risk
Single app import	Low	Hours	Low
Multi-source merge	Medium	Days	Medium
Plugin major rewrite	Medium	Weeks	Medium
Enterprise migration	High	Months	High

Instructions

Step 1: Pre-Migration Assessment

// scripts/migration-assessment.ts
interface MigrationAssessment {
  sourceSystem: string;
  noteCount: number;
  attachmentCount: number;
  totalSize: number;
  linkCount: number;
  tagCount: number;
  uniqueTags: string[];
  folderStructure: string[];
  issues: MigrationIssue[];
}

interface MigrationIssue {
  type: 'encoding' | 'format' | 'link' | 'attachment' | 'metadata';
  severity: 'warning' | 'error';
  description: string;
  affectedFiles: string[];
}

async function assessMigration(sourcePath: string): Promise<MigrationAssessment> {
  const assessment: MigrationAssessment = {
    sourceSystem: 'unknown',
    noteCount: 0,
    attachmentCount: 0,
    totalSize: 0,
    linkCount: 0,
    tagCount: 0,
    uniqueTags: [],
    folderStructure: [],
    issues: [],
  };

  // Scan source directory
  // Count files, measure sizes
  // Identify formats and potential issues

  return assessment;
}

// Generate report
function generateAssessmentReport(assessment: MigrationAssessment): string {
  return `
# Migration Assessment Report

## Source System: ${assessment.sourceSystem}

### Content Summary
- Notes: ${assessment.noteCount}
- Attachments: ${assessment.attachmentCount}
- Total Size: ${(assessment.totalSize / 1024 / 1024).toFixed(2)} MB
- Links: ${assessment.linkCount}
- Tags: ${assessment.tagCount} (${assessment.uniqueTags.length} unique)

### Folder Structure
${assessment.folderStructure.map(f => `- ${f}`).join('\n')}

### Issues Found
${assessment.issues.map(i => `- [${i.severity.toUpperCase()}] ${i.type}: ${i.description}`).join('\n')}

### Recommendations
${assessment.issues.length === 0 ? '- No issues found, proceed with migration' : '- Address issues before migration'}
  `;
}

Step 2: Format Converters

// scripts/converters/evernote.ts
import * as fs from 'fs';
import * as path from 'path';
import { parseStringPromise } from 'xml2js';

interface EvernoteNote {
  title: string;
  content: string;
  created: string;
  updated: string;
  tags: string[];
  attachments: EvernoteAttachment[];
}

interface EvernoteAttachment {
  filename: string;
  mime: string;
  data: string; // base64
}

export async function convertEvernoteExport(
  enexPath: string,
  outputPath: string
): Promise<{ notes: number; attachments: number }> {
  const content = fs.readFileSync(enexPath, 'utf-8');
  const parsed = await parseStringPromise(content);
  const notes = parsed['en-export']?.note || [];

  let noteCount = 0;
  let attachmentCount = 0;

  for (const note of notes) {
    const converted = convertEvernoteNote(note);
    const fileName = sanitizeFileName(converted.title) + '.md';
    const filePath = path.join(outputPath, fileName);

    // Convert HTML content to Markdown
    const markdown = convertHtmlToMarkdown(converted.content);

    // Add frontmatter
    const frontmatter = `---
title: ${converted.title}
created: ${converted.created}
updated: ${converted.updated}
tags: [${converted.tags.join(', ')}]
source: evernote
---

`;

    fs.writeFileSync(filePath, frontmatter + markdown);
    noteCount++;

    // Handle attachments
    for (const attachment of converted.attachments) {
      const attachmentPath = path.join(outputPath, 'attachments', attachment.filename);
      const data = Buffer.from(attachment.data, 'base64');
      fs.writeFileSync(attachmentPath, data);
      attachmentCount++;
    }
  }

  return { notes: noteCount, attachments: attachmentCount };
}

function convertEvernoteNote(note: any): EvernoteNote {
  return {
    title: note.title?.[0] || 'Untitled',
    content: note.content?.[0] || '',
    created: formatDate(note.created?.[0]),
    updated: formatDate(note.updated?.[0]),
    tags: note.tag || [],
    attachments: extractAttachments(note.resource || []),
  };
}

// scripts/converters/notion.ts
export async function convertNotionExport(
  notionPath: string,
  outputPath: string
): Promise<{ notes: number; databases: number }> {
  // Notion exports as nested folders with markdown/CSV
  // Walk directory and convert

  let noteCount = 0;
  let databaseCount = 0;

  // Implementation...

  return { notes: noteCount, databases: databaseCount };
}

// scripts/converters/roam.ts
export async function convertRoamExport(
  roamJsonPath: string,
  outputPath: string
): Promise<{ pages: number; blocks: number }> {
  const content = fs.readFileSync(roamJsonPath, 'utf-8');
  const roamData = JSON.parse(content);

  let pageCount = 0;
  let blockCount = 0;

  for (const page of roamData) {
    const markdown = convertRoamPage(page);
    const fileName = sanitizeFileName(page.title) + '.md';

    fs.writeFileSync(path.join(outputPath, fileName), markdown);
    pageCount++;
    blockCount += countBlocks(page);
  }

  return { pages: pageCount, blocks: blockCount };
}

function convertRoamPage(page: any): string {
  const lines: string[] = [`# ${page.title}`, ''];

  if (page.children) {
    for (const block of page.children) {
      lines.push(...convertRoamBlock(block, 0));
    }
  }

  return lines.join('\n');
}

function convertRoamBlock(block: any, depth: number): string[] {
  const lines: string[] = [];
  const indent = '  '.repeat(depth);
  const content = convertRoamSyntax(block.string || '');

  lines.push(`${indent}- ${content}`);

  if (block.children) {
    for (const child of block.children) {
      lines.push(...convertRoamBlock(child, depth + 1));
    }
  }

  return lines;
}

function convertRoamSyntax(text: string): string {
  // Convert Roam-specific syntax to Obsidian
  return text
    .replace(/\[\[([^\]]+)\]\]/g, '[[$1]]') // Links same
    .replace(/\(\(([^)]+)\)\)/g, '^$1') // Block refs to block IDs
    .replace(/#\[\[([^\]]+)\]\]/g, '#$1') // Tag pages to tags
    .replace(/{{embed: \[\[([^\]]+)\]\]}}/g, '![[$ 1]]'); // Embeds
}

Step 3: Link Migration

// scripts/migrate-links.ts
import * as fs from 'fs';
import * as path from 'path';
import * as glob from 'glob';

interface LinkMapping {
  original: string;
  converted: string;
  type: 'internal' | 'external' | 'attachment';
}

export class LinkMigrator {
  private linkMappings: Map<string, LinkMapping> = new Map();
  private orphanedLinks: string[] = [];

  async buildLinkIndex(vaultPath: string): Promise<void> {
    const files = glob.sync('**/*.md', { cwd: vaultPath });

    for (const file of files) {
      const baseName = path.basename(file, '.md');
      this.linkMappings.set(baseName.toLowerCase(), {
        original: baseName,
        converted: baseName,
        type: 'internal',
      });
    }
  }

  async migrateLinks(vaultPath: string): Promise<{
    updated: number;
    orphaned: string[];
  }> {
    const files = glob.sync('**/*.md', { cwd: vaultPath });
    let updatedCount = 0;

    for (const file of files) {
      const filePath = path.join(vaultPath, file);
      let content = fs.readFileSync(filePath, 'utf-8');
      let modified = false;

      // Find all wiki-style links
      const linkRegex = /\[\[([^\]|]+)(\|[^\]]+)?\]\]/g;
      let match;

      while ((match = linkRegex.exec(content)) !== null) {
        const originalLink = match[1];
        const alias = match[2] || '';
        const resolvedLink = this.resolveLink(originalLink);

        if (resolvedLink !== originalLink) {
          const newLink = `[[${resolvedLink}${alias}]]`;
          content = content.replace(match[0], newLink);
          modified = true;
        }
      }

      if (modified) {
        fs.writeFileSync(filePath, content);
        updatedCount++;
      }
    }

    return {
      updated: updatedCount,
      orphaned: this.orphanedLinks,
    };
  }

  private resolveLink(link: string): string {
    // Try exact match
    const mapping = this.linkMappings.get(link.toLowerCase());
    if (mapping) {
      return mapping.converted;
    }

    // Try without path
    const baseName = path.basename(link);
    const baseMapping = this.linkMappings.get(baseName.toLowerCase());
    if (baseMapping) {
      return baseMapping.converted;
    }

    // Mark as orphaned
    if (!this.orphanedLinks.includes(link)) {
      this.orphanedLinks.push(link);
    }

    return link;
  }

  async createOrphanedLinksReport(vaultPath: string): Promise<void> {
    const report = `# Orphaned Links Report

These links could not be resolved during migration:

${this.orphanedLinks.map(link => `- [[${link}]]`).join('\n')}

## Actions Needed
- Create missing notes
- Update or remove broken links
- Check for renamed files
`;

    fs.writeFileSync(
      path.join(vaultPath, '_migration', 'orphaned-links.md'),
      report
    );
  }
}

Step 4: Batch Migration Script

// scripts/migrate.ts
import * as fs from 'fs';
import * as path from 'path';
import { convertEvernoteExport } from './converters/evernote';
import { convertNotionExport } from './converters/notion';
import { convertRoamExport } from './converters/roam';
import { LinkMigrator } from './migrate-links';

interface MigrationConfig {
  source: {
    type: 'evernote' | 'notion' | 'roam' | 'markdown';
    path: string;
  };
  target: {
    vaultPath: string;
    createBackup: boolean;
  };
  options: {
    preserveFolderStructure: boolean;
    convertTags: boolean;
    migrateAttachments: boolean;
    fixLinks: boolean;
    dryRun: boolean;
  };
}

async function runMigration(

---

*Content truncated.*