Building a Blog with Notion as Your CMS

If you’ve ever wished you could just write in Notion and have your blog update automatically, you’re not alone. Notion’s rich editor, database features, and collaborative tools make it an ideal CMS — if you can bridge the gap to your static site.

In this guide, we’ll walk through setting up Notion as a headless CMS for an Astro blog.

Why Notion as a CMS?#

Most headless CMS platforms (Contentful, Sanity, Strapi) are powerful but come with a learning curve and often a price tag. Notion offers something different:

Familiar interface — If you already use Notion for notes, you know the editor
Rich content — Tables, callouts, toggles, embedded media
Database views — Filter by status, category, or publish date
Free tier — More than enough for a personal blog
Collaboration — Invite editors without teaching them a new tool

Architecture Overview#

Here’s how the pieces fit together:

1
┌─────────┐     Webhook     ┌──────────────┐     Dispatch     ┌─────────┐
2
│  Notion  │ ──────────────► │  CF Worker   │ ───────────────► │ GitHub  │
3
│   DB     │                 │  (validate)  │                  │ Actions │
4
└─────────┘                 └──────────────┘                  └────┬────┘
5
                                                                   │
6
                                                              sync + build
7
                                                                   │
8
                                                              ┌────▼────┐
9
                                                              │   CF    │
10
                                                              │  Pages  │
11
                                                              └─────────┘

When you change a page’s status to “Publishing” in Notion, a webhook fires. A Cloudflare Worker validates the request and triggers a GitHub Actions workflow that syncs content and deploys.

Setting Up the Notion Database#

Create a new database in Notion with these properties:

Property	Type	Purpose
Title	Title	Post title
Status	Select	Publishing workflow
Category	Select	Blog category
Tags	Multi-select	Post tags
Publish Date	Date	When to publish
Description	Text	SEO description
Hero Image	Files & Media	Cover image
Slug	Text	URL slug

The Status property drives the entire workflow:

1
Draft → Ready → Publishing → Synced
2
                    ↓
3
              Sync Failed (on error)

Connecting Notion to Your Blog#

First, create a Notion integration and grab your API token:

1
import { Client } from '@notionhq/client';
2

3
const notion = new Client({ auth: process.env.NOTION_TOKEN });
4

5
const response = await notion.databases.query({
6
  database_id: process.env.NOTION_DATABASE_ID,
7
  filter: {
8
    property: 'Status',
9
    select: { equals: 'Publishing' },
10
  },
11
});

For each page, we convert Notion blocks to Markdown:

1
async function pageToMarkdown(pageId: string): Promise<string> {
2
  const blocks = await notion.blocks.children.list({
3
    block_id: pageId,
4
  });
5

6
  return blocks.results
7
    .map(block => blockToMarkdown(block))
8
    .join('\n\n');
9
}

The Webhook Handler#

The Cloudflare Worker validates incoming webhooks using HMAC-SHA256:

1
async function verifySignature(
2
  body: string,
3
  signature: string,
4
  secret: string,
5
): Promise<boolean> {
6
  const encoder = new TextEncoder();
7
  const key = await crypto.subtle.importKey(
8
    'raw',
9
    encoder.encode(secret),
10
    { name: 'HMAC', hash: 'SHA-256' },
11
    false,
12
    ['verify'],
13
  );
14

15
  const sig = hexToBytes(signature);
16
  return crypto.subtle.verify('HMAC', key, sig, encoder.encode(body));
17
}

Security note: Always validate webhook signatures. Without verification, anyone could trigger rebuilds on your site.

What’s Next#

In the next post of this series, we’ll cover the developer tools that make this workflow even smoother — from CLI scaffolding to automated deployments.

TL;DR: Notion + Cloudflare Workers + GitHub Actions = a free, fast, and familiar blogging workflow. Write where you think, publish where you want.

Ink & Bytes