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

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

2. Share Your Database

Open your Notion database
Click the "Share" button in the top right
Click "Invite" and search for your integration name
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

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

License

MIT License - see LICENSE file for details.