# Notion Importer Complete Notion to MDX (Markdown + JSX) importer optimized for Astro with advanced media handling, interactive components, and seamless integration. ## 🚀 Quick Start ```bash # Install dependencies npm install # Setup environment variables cp env.example .env # Edit .env with your Notion token # Complete Notion → MDX conversion with all features node index.mjs # For step-by-step debugging node notion-converter.mjs # Notion → Markdown node mdx-converter.mjs # Markdown → MDX ``` ## 📁 Structure ``` notion-importer/ ├── index.mjs # Complete Notion → MDX pipeline ├── notion-converter.mjs # Notion → Markdown with notion-to-md v4 ├── mdx-converter.mjs # Markdown → MDX with Astro components ├── post-processor.mjs # Markdown post-processing ├── package.json # Dependencies and scripts ├── env.example # Environment variables template ├── input/ # Configuration │ └── pages.json # Notion pages to convert └── output/ # Results ├── *.md # Intermediate Markdown ├── *.mdx # Final MDX for Astro └── media/ # Downloaded media files ``` ## ✨ Key Features ### 🎯 **Advanced Media Handling** - **Local download**: Automatic download of all Notion media (images, files, PDFs) - **Path transformation**: Smart path conversion for web accessibility - **Figure components**: Automatic conversion to Astro `Figure` components with zoom/download - **Media organization**: Structured media storage by page ID ### 🧮 **Interactive Components** - **Callouts → Notes**: Notion callouts converted to Astro `Note` components - **Enhanced tables**: Tables wrapped in styled containers - **Code blocks**: Enhanced with copy functionality - **Automatic imports**: Smart component and image import generation ### 🎨 **Smart Formatting** - **Link fixing**: Notion internal links converted to relative links - **Artifact cleanup**: Removal of Notion-specific formatting artifacts - **Frontmatter generation**: Automatic YAML frontmatter from Notion properties - **Astro compatibility**: Full compatibility with Astro MDX processing ### 🔧 **Robust Pipeline** - **Notion preprocessing**: Advanced page configuration and media strategy - **Post-processing**: Markdown cleanup and optimization - **MDX conversion**: Final transformation with Astro components - **Auto-copy**: Automatic copying to Astro content directory ## 📊 Example Workflow ```bash # 1. Configure your Notion pages # Edit input/pages.json with your page IDs # 2. Complete automatic conversion NOTION_TOKEN=your_token node index.mjs --clean # 3. Generated results ls output/ # → getting-started.md (Intermediate Markdown) # → getting-started.mdx (Final MDX for Astro) # → media/ (downloaded images and files) ``` ### 📋 Conversion Result The pipeline generates MDX files optimized for Astro with: ```mdx --- title: "Getting Started with Notion" published: "2024-01-15" tableOfContentsAutoCollapse: true --- import Figure from '../components/Figure.astro'; import Note from '../components/Note.astro'; import gettingStartedImage from './media/getting-started/image1.png'; ## Introduction Here is some content with a callout: This is a converted Notion callout. And an image:
``` ## ⚙️ Required Astro Configuration To use the generated MDX files, ensure your Astro project has the required components: ```astro // src/components/Figure.astro --- export interface Props { src: any; alt?: string; caption?: string; zoomable?: boolean; downloadable?: boolean; layout?: string; id?: string; } const { src, alt, caption, zoomable, downloadable, layout, id } = Astro.props; ---
{alt} {caption &&
{caption}
}
``` ## 🛠️ Prerequisites - **Node.js** with ESM support - **Notion Integration**: Set up an integration in your Notion workspace - **Notion Token**: Copy the "Internal Integration Token" - **Shared Pages**: Share the specific Notion page(s) with your integration - **Astro** to use the generated MDX ## 🎯 Technical Architecture ### 4-Stage Pipeline 1. **Notion Preprocessing** (`notion-converter.mjs`) - Configuration loading from `pages.json` - Notion API client initialization - Media download strategy configuration 2. **Notion-to-Markdown** (notion-to-md v4) - Page conversion with `NotionConverter` - Media downloading with `downloadMediaTo()` - File export with `DefaultExporter` 3. **Markdown Post-processing** (`post-processor.mjs`) - Notion artifact cleanup - Link fixing and optimization - Table and code block enhancement 4. **MDX Conversion** (`mdx-converter.mjs`) - Component transformation (Figure, Note) - Automatic import generation - Frontmatter enhancement - Astro compatibility optimization ## 📊 Configuration Options ### Pages Configuration (`input/pages.json`) ```json { "pages": [ { "id": "your-notion-page-id", "title": "Page Title", "slug": "page-slug" } ] } ``` ### Environment Variables Copy `env.example` to `.env` and configure: ```bash cp env.example .env # Edit .env with your actual Notion token ``` Required variables: ```bash NOTION_TOKEN=secret_your_notion_integration_token_here ``` ### Command Line Options ```bash # Full workflow node index.mjs --clean --token=your_token # Notion to Markdown only node index.mjs --notion-only # Markdown to MDX only node index.mjs --mdx-only # Custom paths node index.mjs --input=my-pages.json --output=converted/ ``` ## 📊 Conversion Statistics For a typical Notion page: - **Media files** automatically downloaded and organized - **Callouts** converted to interactive Note components - **Images** transformed to Figure components with zoom/download - **Tables** enhanced with proper styling containers - **Code blocks** enhanced with copy functionality - **Links** fixed for proper internal navigation ## ✅ Project Status ### 🎉 **Complete Features** - ✅ **Notion → MDX Pipeline**: Full end-to-end functional conversion - ✅ **Media Management**: Automatic download and path transformation - ✅ **Component Integration**: Seamless Astro component integration - ✅ **Smart Formatting**: Intelligent cleanup and optimization - ✅ **Robustness**: Error handling and graceful degradation - ✅ **Flexibility**: Modular pipeline with step-by-step options ### 🚀 **Production Ready** The toolkit is now **100% operational** for converting Notion pages to MDX/Astro with all advanced features (media handling, component integration, smart formatting). ## 🔗 Integration with notion-to-md v4 This toolkit leverages the powerful [notion-to-md v4](https://notionconvert.com/docs/v4/guides/) library with: - **Advanced Media Strategies**: Download, upload, and direct media handling - **Custom Renderers**: Block transformers and annotation transformers - **Exporter Plugins**: File, buffer, and stdout output options - **Database Support**: Full database property and frontmatter transformation - **Page References**: Smart internal link handling ## 📚 Additional Resources - [notion-to-md v4 Documentation](https://notionconvert.com/docs/v4/guides/) - [Notion API Documentation](https://developers.notion.com/) - [Astro MDX Documentation](https://docs.astro.build/en/guides/integrations-guide/mdx/) - [Media Handling Strategies](https://notionconvert.com/blog/mastering-media-handling-in-notion-to-md-v4-download-upload-and-direct-strategies/) - [Frontmatter Transformation](https://notionconvert.com/blog/how-to-convert-notion-properties-to-frontmatter-with-notion-to-md-v4/)