Notion 統合説明文書#
この文書では、Astro ブログプロジェクトで Notion を CMS として設定および使用する方法を紹介します。この実装は、NotionNext の主要機能を完全にコピーしており、コンテンツの取得、キャッシュ、ISR（増分静的再生成）および自動更新メカニズムを含んでいます。
コア機能#
- Notion データベースとして CMS - Notion で全てのブログ記事を作成、管理
- ISR メカニズム - 混合レンダリングモード、静的生成とサーバーレンダリングを組み合わせ
- キャッシュシステム - 高性能キャッシュにより API 呼び出しを削減
- 増分更新 - webhook と再検証 API を通じて増分更新をサポート
- 完全互換性 - 既存のブログの Markdown front matter 形式と完全に互換性あり
環境変数設定#
プロジェクトのルートディレクトリに.envファイルを作成し、以下の設定を追加します：
# 必須項目
NOTION_TOKEN=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id
# オプション設定項目
NOTION_CACHE_SECONDS=300 # キャッシュ時間（秒）
USE_CACHE_IN_DEV=false # 開発環境でキャッシュを有効にするか
NOTION_WEBHOOK_SECRET=your_secret # Webhookキー
REVALIDATE_TOKEN=NOTION_ISR_SECRET # 再検証APIのトークン
ENABLE_ISR=true # ISR機能を有効にするか
NOTION_ACTIVE_USER=your_user_id # NotionユーザーID（特定の機能が必要な場合あり）
VERCEL_DEPLOY_HOOK_URL=your_hook_url # VercelデプロイフックURL
Notion データベース設定#
Notion でデータベースを作成し、ブログの front matter 形式に一致する以下の属性を追加します：
| 属性名 | タイプ | 説明 | 対応 front matter フィールド |
|---|---|---|---|
| Title | タイトル | 記事のタイトル | title |
| Slug | テキスト | URL パス（オプション、未記入の場合はタイトルから生成） | slug |
| Date | 日付 | 公開日 | published |
| UpdatedDate | 日付 | 更新日（オプション） | updated |
| Description | テキスト | 記事の説明 | description |
| Tags | 複数選択 | 記事のタグ | tags |
| Category | 選択 | 記事のカテゴリ | category |
| Image | ファイル / リンク | カバー画像 | image |
| Published | チェックボックス | 公開するか | draft（反転） |
| Draft | チェックボックス | 草稿かどうか（オプション） | draft |
| Lang | 選択 | 記事の言語（オプション） | lang |
Notion API 統合設定#
- Notion 統合を作成: https://www.notion.so/my-integrations
- 統合トークンを取得し、
NOTION_TOKEN環境変数に設定 - Notion データベース ID をコピー（データベース共有リンクから取得）し、
NOTION_DATABASE_ID環境変数に設定 - あなたの統合をデータベースに共有
デプロイ設定#
Vercel デプロイ#
- Vercel で全ての環境変数を設定
- 混合 SSG+SSR モードを有効にする
- Vercel デプロイフックを作成し、
VERCEL_DEPLOY_HOOK_URL環境変数に設定
Webhook の設定（オプションだが推奨）#
- カスタム Notion 統合を作成
- Webhook エンドポイントを設定:
https://your-domain.com/api/notion/webhook - コールバックイベントを設定:
page_updated,page_created - セキュリティキーを設定し、環境変数に追加
使用方法#
設定が完了したら、以下のページにアクセスできます：
/notion- すべての Notion 記事のリストを表示/notion/post/[slug]- 特定の記事の詳細を表示
API エンドポイント#
システムは以下の API エンドポイントを提供します：
GET /api/notion/posts- 記事リストを取得、ページネーションとフィルタリングをサポートGET /api/notion/post/[slug]- 特定の記事の詳細を取得POST /api/notion/revalidate- キャッシュを再検証（REVALIDATE_TOKEN を提供する必要あり）POST /api/notion/webhook- Notion 更新イベントを受信
NotionNext vs 本実装#
私たちは NotionNext のコア機能を完全に移植しましたが、主な違いは以下の通りです：
- アーキテクチャの違い：Next.js の ISR ではなく、Astro の混合レンダリングを使用
- パフォーマンス最適化：ISR を模倣するカスタムキャッシュシステムを実装
- 互換性：属性マッピングが既存のブログの Markdown 形式に適合
- デプロイモード：Vercel アダプターを使用してエッジ関数をサポート
トラブルシューティング#
問題が発生した場合：
- 環境変数の設定を確認
- Notion 統合がデータベースに正しく共有されていることを確認
- データベース構造が上記の要件に合致しているか確認
- コンソールエラーログを確認
/api/notion/revalidateエンドポイントを通じて手動でキャッシュを更新してみる