Astro Notion Loader

A simple and efficient loader for fetching content from Notion databases and converting it to markdown format. Perfect for Astro static site generators and other content management workflows.

Features

• 🚀 Easy Integration: Simple API for loading Notion content
• 📝 Markdown Conversion: Automatically converts Notion pages to markdown
• 🔧 Flexible Filtering: Support for Notion database filters
• ⚡ Fast Performance: Efficient batch processing of pages
• 🛡️ Error Handling: Robust error handling for failed conversions
• 📦 TypeScript Support: Full TypeScript definitions included

Installation

npm install astro-notion-loader

Setup

1. Create a Notion Integration

1. Go to Notion Integrations
2. Click "New integration"
3. Give it a name and associate it with your workspace
4. Copy the Internal Integration Token (this is your API key)

2. Share Your Database

1. Open your Notion database
2. Click the "Share" button in the top right
3. Click "Invite" and search for your integration name
4. Select your integration and click "Invite"

3. Get Your Database ID

Your database ID is the 32-character string in your database URL:

https://notion.so/your-workspace/DATABASE_ID?v=...

Usage

Basic Usage

import { loader } from 'astro-notion-loader';

const pages = await loader({
  notionAPIKey: 'your-notion-api-key',
  notionDatabaseId: 'your-database-id'
});

console.log(pages);

With Astro Content Collections (Recommended)

// src/content/config.ts
import { defineCollection } from 'astro:content';
import { getCollection } from 'astro-notion-loader';

const blog = defineCollection(
  getCollection({
    notionAPIKey: process.env.NOTION_API_KEY,
    notionDatabaseId: process.env.NOTION_DATABASE_ID
  })
);

export const collections = { blog };

Manual Astro Content Collections Setup

// src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { loader } from 'astro-notion-loader';

const blog = defineCollection({
  loader: () => loader({
    notionAPIKey: process.env.NOTION_API_KEY,
    notionDatabaseId: process.env.NOTION_DATABASE_ID
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    status: z.string(),
    content: z.string(), // HTML content
  }),
});

export const collections = { blog };

With Filtering

import { loader } from 'astro-notion-loader';

// Only fetch published posts
const publishedPosts = await loader({
  notionAPIKey: 'your-notion-api-key',
  notionDatabaseId: 'your-database-id',
  filter: {
    property: 'Status',
    status: {
      equals: 'Published'
    }
  }
});

Environment Variables

Create a .env file in your project root:

NOTION_API_KEY=your_notion_integration_token
NOTION_DATABASE_ID=your_database_id

Then use in your code:

import { loader } from 'astro-notion-loader';

const pages = await loader({
  notionAPIKey: process.env.NOTION_API_KEY,
  notionDatabaseId: process.env.NOTION_DATABASE_ID
});

API Reference

loader(options)

Parameters

• options (object): Configuration object
  • notionAPIKey (string): Your Notion integration token
  • notionDatabaseId (string): The ID of your Notion database
  • filter (object, optional): Notion database filter object

Returns

Promise that resolves to an array of page objects:

interface NotionPage {
  id: string;           // Notion page ID
  title: string;        // Page title from Title property
  description: string;  // Description from Description property
  pubDate: Date;        // Date from "Published Date" property
  status: string;       // Status from Status property
  content: string;      // HTML content converted from markdown
}

getCollection(options)

Returns a pre-configured Astro content collection with the loader and schema already set up.

Parameters

• options (object): Configuration object
  • notionAPIKey (string): Your Notion integration token
  • notionDatabaseId (string): The ID of your Notion database
  • filter (object, optional): Notion database filter object

Returns

Content collection configuration object that can be used directly with defineCollection().

Database Schema Requirements

Your Notion database should have these properties (case-sensitive):

• Title (Title): The page title
• Description (Rich Text): Page description/summary
• Published Date (Date): Publication date
• Status (Status): Page status (e.g., "Draft", "Published")

Error Handling

The loader includes robust error handling:

• Pages that fail to convert will still be included with empty content
• Errors are logged to console for debugging
• Missing properties are handled gracefully with default values

Examples

Blog with Astro (Using getCollection)

// src/content/config.ts
import { defineCollection } from 'astro:content';
import { getCollection } from 'astro-notion-loader';

const blog = defineCollection(
  getCollection({
    notionAPIKey: process.env.NOTION_API_KEY,
    notionDatabaseId: process.env.NOTION_DATABASE_ID,
    filter: {
      property: 'Status',
      status: { equals: 'Published' }
    }
  })
);

export const collections = { blog };

Filtering Examples

// Only published posts
const filter = {
  property: 'Status',
  status: { equals: 'Published' }
};

// Posts from last month
const filter = {
  property: 'Published Date',
  date: {
    after: '2024-01-01'
  }
};

// Combine multiple filters
const filter = {
  and: [
    {
      property: 'Status',
      status: { equals: 'Published' }
    },
    {
      property: 'Published Date',
      date: { after: '2024-01-01' }
    }
  ]
};

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• 📖 Notion API Documentation
• 🚀 Astro Documentation
• 🐛 Report Issues