notion-to-markdown

Migrate Notion exports into clean, organized Markdown with phase-based configs.

7|1|Updated Feb 15, 2026

Search Tags:#automation #markdown #migration #cleanup #config #notion #knowledge-base

Ready to run

npx skills add https://github.com/alexknowshtml/notion-to-markdown --skill notion-to-markdown-alexknowshtml

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: notion-to-markdown
Source: https://github.com/alexknowshtml/notion-to-markdown/tree/main
Command: npx skills add https://github.com/alexknowshtml/notion-to-markdown --skill notion-to-markdown-alexknowshtml

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Notion exports contain formatting cruft, nested structures, and Notion-specific artifacts that hinder sharing and publishing. This skill migrates a Notion export into clean, organized Markdown, preserving meaning while removing noise.

Core Features & Use Cases

Interviews you about how your knowledge base is organized to tailor the migration
Builds a config file '.notion-migrate.yml' that captures preferences and filing logic
Migrates in three phases, starting with easy items and progressing to higher-judgment content
Applies the Notion cleanup checklist to remove artifacts while preserving substantive content
Reports back with a migration summary and learns from feedback to improve decisions

Quick Start

Run the notion-to-markdown skill on your Notion export to generate a clean, organized Markdown knowledge base.

Frequently Asked Questions about notion-to-markdown

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I clean up Notion export artifacts for Markdown migration?▼

To clean up Notion export artifacts for Markdown migration, this skill applies a cleanup checklist that removes formatting cruft and Notion-specific structures while preserving your substantive content.

What is the best way to organize a large Notion knowledge base into Markdown?▼

The best way to organize a large Notion knowledge base into Markdown is running a multi-phase migration. This skill interviews you about your setup, builds a config file, and migrates content in three phases.

How does the config file work when migrating Notion to Markdown?▼

The config file works by capturing your filing logic and preferences in a .notion-migrate.yml file. It supports target_path mappings and per-file git workflows to structure your Markdown knowledge base.

Can I migrate Notion content to Markdown in phases instead of all at once?▼

You can migrate Notion content to Markdown in phases. The migration starts with easy items and progressively handles higher-judgment content, allowing you to review decisions and provide feedback.

Why does my Notion Markdown export contain nested structures and formatting cruft?▼

Notion Markdown exports contain nested structures and formatting cruft because Notion embeds specific artifacts that hinder publishing. This skill targets those artifacts to generate clean, organized Markdown files.

Do I need a YAML frontmatter setup to migrate Notion pages to Markdown?▼

You need a YAML frontmatter entry point in your SKILL.md to migrate Notion pages to Markdown. The skill leverages this setup along with references to guide migration decisions and apply the cleanup checklist.