谢懿Shine

Notion Integration Documentation#

This document explains how to configure and use Notion as a CMS in an Astro blog project. This implementation fully replicates the main features of NotionNext, including content fetching, caching, ISR (Incremental Static Regeneration), and an automatic update mechanism.

Core Features#

• Notion Database as CMS - Create and manage all blog posts in Notion
• ISR Mechanism - Hybrid rendering mode combining static generation and server rendering
• Caching System - High-performance caching reduces API calls
• Incremental Updates - Supports incremental updates via webhooks and revalidation API
• Full Compatibility - Fully compatible with the existing Markdown front matter format of the blog

Environment Variable Setup#

Create a .env file in the root directory of the project and add the following configuration:

# Required fields
NOTION_TOKEN=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id

# Optional configuration
NOTION_CACHE_SECONDS=300           # Cache time (seconds)
USE_CACHE_IN_DEV=false             # Enable caching in development environment
NOTION_WEBHOOK_SECRET=your_secret   # Webhook secret
REVALIDATE_TOKEN=NOTION_ISR_SECRET  # Token for revalidation API
ENABLE_ISR=true                     # Enable ISR functionality
NOTION_ACTIVE_USER=your_user_id     # Notion user ID (some features may require)
VERCEL_DEPLOY_HOOK_URL=your_hook_url # Vercel deployment hook URL

Notion Database Configuration#

Create a database in Notion and add the following properties to match the blog's front matter format:

Notion API Integration Setup#

1. Create a Notion integration: https://www.notion.so/my-integrations
2. Obtain the integration token and set it to the NOTION_TOKEN environment variable
3. Copy the Notion database ID (obtained from the database share link) and set it to the NOTION_DATABASE_ID environment variable
4. Share your integration with the database

Deployment Configuration#

Vercel Deployment#

1. Configure all environment variables in Vercel
2. Enable hybrid SSG+SSR mode
3. Create a Vercel deployment hook and set it to the VERCEL_DEPLOY_HOOK_URL environment variable

Set Up Webhook (Optional but Recommended)#

1. Create a custom Notion integration
2. Configure the webhook endpoint: https://your-domain.com/api/notion/webhook
3. Configure callback events: page_updated, page_created
4. Set a security key and add it to the environment variables

Usage#

Once the configuration is complete, you can access the following pages:

• /notion - Displays a list of all Notion articles
• /notion/post/[slug] - Displays details of a specific article

API Endpoints#

The system provides the following API endpoints:

• GET /api/notion/posts - Fetch the list of articles, supports pagination and filtering
• GET /api/notion/post/[slug] - Fetch details of a specific article
• POST /api/notion/revalidate - Revalidate cache (requires REVALIDATE_TOKEN)
• POST /api/notion/webhook - Receive Notion update events

NotionNext vs This Implementation#

We have fully ported the core features of NotionNext, with the main differences being:

1. Architectural Differences: Uses Astro's hybrid rendering instead of Next.js's ISR
2. Performance Optimization: Implemented a custom caching system to simulate ISR
3. Compatibility: Property mapping adapts to the existing Markdown format of the blog
4. Deployment Mode: Uses Vercel adapter to support edge functions

Troubleshooting#

If you encounter issues:

1. Check the environment variable configuration
2. Ensure the Notion integration is correctly shared with the database
3. Verify that the database structure meets the above requirements
4. Check the console error logs
5. Try manually refreshing the cache via the /api/notion/revalidate endpoint