Notion To Markdown — Documentation skill for Claude Code

notion-to-markdown

A [Claude Code](https://claude.ai/code) skill that migrates Notion exports into clean, organized markdown. Designed to teach you how to organize your knowledge base while doing the migration for you.

What This Does

Instead of dumping your entire Notion export and hoping for the best, this skill:

1. Interviews you about how your knowledge base is organized (or helps you decide)
2. Builds a config file (.notion-migrate.yml) that captures your preferences
3. Migrates in three phases, starting with easy items and working up to complex ones
4. Learns from your feedback — the config gets smarter after each phase

By the end, your content is organized and you understand your own system well enough to maintain it.

Quick Start

1. Export from Notion

In Notion: Settings → Export → Markdown & CSV → Export all workspace content.

Unzip the export into your repo (e.g., `./notion-export/`).

2. Install the Skill

Add to your Claude Code project:

claude skill add alexknowshtml/notion-to-markdown

Or clone and reference locally:

git clone https://github.com/alexknowshtml/notion-to-markdown.git .claude/skills/notion-to-markdown

3. Run It

Tell Claude Code:

"I have a Notion export I need to migrate"

The skill will detect this is its first run, start the setup interview, and guide you from there.

How the Phases Work

Phase 1: Quick Wins (5-10 items)

Migrates the easy stuff — templates, frameworks, raw data. The skill explains every filing decision so you understand the system.

**You learn:** What Notion artifacts look like and how cleanup works.

Phase 2: Structured Content (10-20 items)

Migrates SOPs, guides, and how-tos. The skill makes filing decisions with less hand-holding, flagging uncertainty instead of asking about everything.

**You learn:** How to distinguish content types and make filing decisions.

Phase 3: High-Judgment Content (remainder)

Migrates policies, pers