Notion Astro Rev - A Notion-Astro Blog Template

Base Blog Template: fuwari

This doc is generated by Claude 3.7 & Windsurf based on project info

If you are looking for @chlorinec-pkgs/notion-astro-loader, please check out notion-astro-loader.

A modern blog template built with Astro and powered by notion-astro-loader for seamless Notion integration.

🌏 中文文档

README version: 2025-04-17

🌟 Introduction

This project serves as a template blog for the notion-astro-loader package, allowing you to create a beautiful, fast, and SEO-friendly blog using Notion as your CMS. With this template, you can:

• Write and manage your blog content in Notion
• Automatically sync content to your Astro-powered blog
• Enjoy a modern, responsive design with smooth animations
• Customize the appearance to match your personal style
• Easily deploy to platforms like Vercel, Netlify, or GitHub Pages

✨ Features

• Notion Integration: Use Notion as your CMS with notion-astro-loader
• Modern Design: Built with Astro and Tailwind CSS
• Performance: Static site generation for optimal speed
• Smooth Transitions: Page transitions and animations
• Theming: Light/dark mode and customizable theme colors
• Responsive: Mobile-friendly design
• Search: Built-in search functionality
• URL Migration: Tools for migrating from other blog platforms
• E2E Testing: Playwright tests for URL redirects and functionality

🚀 Getting Started

Prerequisites

• Node.js (v18 or later)
• pnpm (recommended package manager)
• A Notion account with a database for your blog posts

Setup

1. Clone this repository:

   git clone https://github.com/KiritoKing/notion-astro-rev.git
   cd notion-astro-rev

2. Install dependencies:

   pnpm install
   pnpm add sharp

3. Create a .env file in the root directory with your Notion credentials:

   NOTION_TOKEN=your_notion_integration_token
   NOTION_DATABASE_ID=your_notion_database_id

4. Start the development server:

   pnpm dev

5. Open your browser and navigate to http://localhost:4321

Tech Stack

• Astro: Fast, modern static site generator
• Tailwind CSS: Utility-first CSS framework
• Svelte: Component framework for interactive elements
• notion-astro-loader: Notion integration for Astro
• Playwright: End-to-end testing framework
• TypeScript: Type-safe JavaScript

🛠️ Customization

Configuration

The main configuration files are located in the src directory:

• config.ts: General site configuration (title, theme, navigation, etc.)
• content.config.ts: Notion integration configuration

Notion Database Setup

Your Notion database should include the following properties for optimal compatibility:

• title (Title): The title of your post
• date (Date): Publication date
• status (Select): Publication status (e.g., "Published", "Draft")
• tags (Multi-select): Post tags
• category (Select): Post category
• description (Text): Brief description for SEO and previews
• image (URL or Files & Media): Cover image

Theme Customization

Edit the src/config.ts file to customize:

• Site title and subtitle
• Theme colors and appearance
• Navigation links
• Profile information
• Banner images
• License information

🚀 Advanced Features

URL Migration

This template includes tools for migrating from other blog platforms by setting up URL redirects. The migration system works as follows:

1. Define your URL mappings in migration/url-map.json
2. The format is {"new-url": ["old-url-1", "old-url-2", ...]}
3. The system automatically creates redirects from all old URLs to the new URL
4. E2E tests in tests/e2e/url-redirects.spec.ts verify that redirects work correctly

Example URL mapping:

{
  "my-new-post": ["2023/01/01/old-post", "post/category/old-post", "/old-post", "/blog/old-post"]
}

Testing

The project includes Playwright tests to verify URL redirects and other functionality:

pnpm test:e2e

🧞 Commands

All commands are run from the root of the project:

Command	Action
pnpm install AND pnpm add sharp	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
pnpm test:e2e	Run Playwright E2E tests
pnpm lint	Run ESLint to check code quality
pnpm format	Format code with Prettier
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro --help	Get help using the Astro CLI