Notion To Markdown

Notion to Markdown Migration Skill

Migrate content from a Notion export into your own markdown-based knowledge base, with progressive learning phases.

How It Works

This skill operates in three phases. Each phase migrates increasingly complex content, refines the config based on your feedback, and builds your understanding of what "clean" looks like.

First Run: Setup

If no .notion-migrate.yml config exists, start with the setup interview:

1. Load setup.md and run the interview
2. Scan the user's repository for directory patterns
3. Generate .notion-migrate.yml from their answers
4. Proceed to Phase 1

Phase 1: Quick Wins (5-10 items)

What gets migrated: Templates, frameworks, raw data, simple reference docs.

How it works:

1. Pick the easiest items from the export — files with minimal judgment calls
2. Apply the cleanup checklist (see references/cleanup-checklist.md)
3. File each item using the config's target path mappings
4. Explain every decision: "I put this in /docs/templates/ because your config maps templates there"
5. After the batch: present a summary and ask "Anything I should adjust?"
6. Update .notion-migrate.yml with any corrections

What the user learns: How Notion artifacts get cleaned up. What their filing structure looks like in practice.

Phase 2: Structured Content (10-20 items)

What gets migrated: SOPs, guides, how-tos, process docs — content that requires filing judgment.

How it works:

1. Migrate with less hand-holding — make filing decisions based on config
2. Flag uncertainty: "I filed this as an SOP, but it could also be a guide — which feels right?"
3. Show the cleanup checklist in action so the user understands what changed
4. After the batch: review + config refinement

What the user learns: The difference between content types. How to make filing decisions themselves.

Phase 3: High-Judgment Content (remainder)

What gets migrated: Policy docs, personal writing, identity content, IP — material that needs human review.

How it works:

1. Operate with higher autonomy — only flag true edge cases
2. For sensitive content (pricing, people's names, policy): always present with context and wait for approval
3. The config now has enough "case law" from Phases 1-2 to handle most decisions

What the user learns: By now they've seen 20+ examples and could almost do it manually. The skill saves time; the user has the judgment.

Workflow Per Item

For each file being migrated:

1. Read the Source File

• Notion exports live in a directory the user specifies during setup
• Files have UUID suffixes (e.g., Meeting Notes abc123def456.md)
• Some items have nested directories with sub-pages

2. Clean the Content

Apply the full cleanup checklist from references/cleanup-checklist.md:

• Strip Notion formatting artifacts
• Fix heading hierarchy
• Preserve all substantive content
• Remove broken internal links

3. Decide Where to File It

Use the config's target_paths mappings. If uncertain:

• Phase 1: Ask the user
• Phase 2: Make a call, flag it
• Phase 3: Make a call, only flag true ambiguity

4. Write the Clean File

• Use the target path from config
• Follow the user's naming convention (from config)
• For multi-file sets: create a directory with an index file and navigation links

5. Track Progress

Update the migration tracker (if the user has one) or report status:

• What was migrated
• What was cleaned/changed
• What's next

6. Commit

Follow the user's git workflow preference from config:

• per_file: Commit after each file
• per_batch: Commit after each phase batch
• manual: Stage changes, let the user commit

Decision Framework

See references/decision-patterns.md for detailed guidance on:

• What can be auto-approved vs. what needs human review
• How to handle stale references
• When to merge duplicate files
• What "content preservation" means in practice

Config Reference

See references/config-schema.md for the full .notion-migrate.yml specification.