Astro Notion Blog

Astro Notion Blog

Astro Notion Blog is an open-source starter template that turns a Notion database into a static blog built with Astro and deployed on Cloudflare Pages. It uses the official Notion API to pull posts from a Notion database, generates static HTML, and offers a local development workflow for customization.

What is Astro Notion Blog?

Astro Notion Blog is a blog starter that uses Notion as its content management system and Astro as the static site generator. It takes a Notion database (duplicated from the provided blog template) as input and produces a fully static blog that can be hosted on Cloudflare Pages. The project is maintained by GitHub user otoyo and is available on GitHub.

Key Features

• Notion as CMS — Write and manage blog content directly in Notion; duplicate the provided blog template into your workspace to start.
• Official Notion API — Uses the official Notion API with an internal integration token, set as the NOTION_API_SECRET environment variable.
• Static site generation with Astro — Astro compiles the content into static pages, which keeps page views fast.
• Cloudflare Pages deployment — The README includes step-by-step instructions for connecting a forked GitHub repo to Cloudflare Pages with an Astro framework preset.
• Local customization — Run npm install and npm run dev to preview changes at http://localhost:4321 before deploying.
• Environment variable configuration — Requires NODE_VERSION, NOTION_API_SECRET, and DATABASE_ID for deployment; NODE_VERSION must be 20.18.1 or higher.
• Live demo — A working example is available at https://astro-notion-blog.pages.dev.

Who is it for?

• Bloggers who already use Notion — They can keep writing in Notion and get a static blog without learning a separate CMS.
• Developers looking for an Astro starter — They get a ready-made Astro project wired to Notion's API, saving setup time.
• Cloudflare Pages users — Anyone wanting a free static hosting workflow can connect the repo and deploy using the provided preset.

What can you do with Astro Notion Blog?

• Publish a blog from a Notion database — Duplicate the template, set your database ID and API secret, and the site pulls posts from Notion.
• Customize the site locally — Run npm run dev to preview changes at localhost:4321 before deploying.
• Deploy to Cloudflare Pages — Fork the repo, connect it to Cloudflare Pages, set the three environment variables, and deploy.

How does Astro Notion Blog work?

The setup workflow is: duplicate the Notion blog template, create a Notion integration to get an API token, share the database with that integration, fork the repo, connect it to Cloudflare Pages, and set environment variables. After deployment, you publish posts by adding content to the Notion database and triggering a new deployment manually or via CI.

FAQ

Do I need to redeploy manually every time I publish a post?

Yes. The README notes that astro-notion-blog requires manual deployment every time you publish a new post or make updates. You can deploy manually from the Cloudflare Pages dashboard or set up a scheduled deploy using CI tools such as GitHub Actions.

What environment variables are required?

You need NOTION_API_SECRET (your Notion internal integration token), DATABASE_ID (the ID from your duplicated Notion database URL), and NODE_VERSION set to 20.18.1 or higher.

Can I customize the blog's appearance?

Yes. After installing dependencies with npm install, run npm run dev to start a local server at http://localhost:4321 and make changes to the site's icons, title, description, and layout.

Is there a demo?

Yes. A live demo is available at https://astro-notion-blog.pages.dev.

What Node.js version is required?

Node.js v20.18.1 or higher is required for local customization.