Notion to MDX Converter

Overview

This skill automates the conversion of Notion markdown exports into Next.js MDX-compatible format for this repository. It handles metadata extraction, formatting transformations, interactive conversion of expandable sections, and automatic downloading of images from Notion.

When to Use This Skill

Use this skill when:

• Converting Notion markdown exports to page.mdx files in this repository
• A file needs MDX frontmatter metadata added
• Notion-specific markdown syntax needs to be transformed to Next.js MDX format
• User mentions converting Notion content or asks to work with Notion markdown

Conversion Workflow

Step 1: Identify the Source File

When a user requests conversion of Notion markdown, identify the target file:

• User may provide a file path directly
• User may have a file open in their editor (check system reminders)
• User may paste Notion markdown content directly

Step 2: Run the Conversion Script

Execute the conversion script with the appropriate file path:

python .claude/skills/notion-to-mdx/scripts/convert_notion_to_mdx.py <input_file> [output_file] [--page-id PAGE_ID]

Parameters:

• <input_file>: Path to the Notion markdown file (required)
• [output_file]: Optional output path (defaults to overwriting input file)
• --page-id PAGE_ID: Optional Notion page ID for downloading images

Image Downloading: If --page-id is provided and NOTION_API_KEY is found in .env.local, the script will:

• Detect Notion image attachments (format: ![text](attachment:UUID:filename))
• Download images from Notion using the API
• Save images to public/images/from-notion/ using the attachment ID as the filename
• Update markdown references to point to local files

The script will:

1. Download Notion images (if page ID provided)
2. Extract the title from the first top-level heading (# Title)
3. Add MDX frontmatter with the title metadata
4. Identify bullet list sections and interactively prompt about expandable dropdowns

Step 3: Interactive Dropdown Conversion

The script will identify bullet list sections in the document and prompt the user:

--- Section 1 (lines 45-52) ---
- First bullet point
- Second bullet point
- Third bullet point

Convert this to expandable dropdown? (y/n):

If the user responds 'y', the script prompts for summary text:

Enter the summary text (what appears when collapsed):

The script then converts the bullet list to:

<details>
  <summary>User's summary text</summary>

- First bullet point
- Second bullet point
- Third bullet point
</details>

Step 4: Verify the Output

After conversion, review the generated MDX file to ensure:

• Title metadata is correct in the frontmatter
• Expandable dropdowns are correctly formatted
• Images are downloaded to public/images/ and references are updated
• File structure matches Next.js MDX requirements

Conversion Details

Title Extraction

The script extracts the title from the first top-level heading in the markdown:

# My Document Title

Content here...

Becomes:

---
title: "My Document Title"
---

# My Document Title

Content here...

If no top-level heading is found, defaults to "Untitled".

Expandable Dropdowns

Regular bullet lists in Notion exports appear as standard markdown bullets. The script identifies these sections and allows interactive conversion to HTML <details> elements:

Before (Notion bullet list):

- Point one
- Point two
- Point three

After (if converted to dropdown):

<details>
  <summary>Click to expand</summary>

- Point one
- Point two
- Point three
</details>

Image Downloading

When a Notion page ID is provided via --page-id, the script automatically downloads images embedded in the Notion export.

How it works:

1. Script scans the markdown for Notion image attachments: ![alt](attachment:UUID:filename)
2. Extracts the attachment IDs from the markdown
3. Fetches blocks from the Notion page using the API
4. Matches attachment IDs to find signed S3 URLs
5. Downloads images to public/images/from-notion/
6. Uses the attachment ID as the filename (keeping original extension)
7. Updates markdown references to point to local files

Before (Notion attachment):

![image.png](attachment:6e9315e9-4f0f-4fec-82d9-28ef74260e5f:image.png)

After (local reference):

![image.png](/public/images/from-notion/6e9315e9-4f0f-4fec-82d9-28ef74260e5f.png)

Requirements:

• Notion page must be shared with the integration (API key owner)
• NOTION_API_KEY must be present in .env.local
• Page ID can be extracted from Notion URL: notion.site/Page-Title-{PAGE_ID}

Note: The script automatically searches for .env.local starting from the input file's directory up to the repository root.

Example Usage

User request: "Convert the Notion markdown in app/my-post/page.mdx and download the images"

Actions:

1. Extract page ID from Notion URL (e.g., 1f82e4fe580280a29479cba5d8ffa898)
2. Run: python .claude/skills/notion-to-mdx/scripts/convert_notion_to_mdx.py app/my-post/page.mdx --page-id 1f82e4fe580280a29479cba5d8ffa898
3. Script automatically:
   • Finds NOTION_API_KEY in .env.local
   • Downloads images from Notion
   • Extracts title
   • Prompts user about bullet list sections for dropdown conversion
4. User responds to prompts interactively
5. File is updated with converted content and local image references

Example without images:

python .claude/skills/notion-to-mdx/scripts/convert_notion_to_mdx.py app/my-post/page.mdx

Example with images:

python .claude/skills/notion-to-mdx/scripts/convert_notion_to_mdx.py app/my-post/page.mdx --page-id 1f82e4fe580280a29479cba5d8ffa898

Non-Interactive Mode

To skip the interactive dropdown prompts (useful when no dropdowns are needed), modify the script call in code:

convert_notion_to_mdx(input_path, output_path, interactive=False)

This will perform title extraction only.

Resources

scripts/convert_notion_to_mdx.py

Python script that performs the markdown-to-MDX conversion. Handles:

• Notion image downloading via API
• Title extraction from top-level headings
• MDX frontmatter generation
• Interactive dropdown creation with user prompts
• Automatic .env.local discovery for API credentials

Dependencies: requests library for HTTP requests to Notion API

The script can be executed directly from the command line or imported as a Python module for programmatic use.