How I Integrated Notion into My New Blog

Previously, I created a blog at https://blog.qu1etboy.dev using AstroJS and Markdown. While it worked, writing in Markdown and committing to Git every time felt inconvenient and slow.

I’ve always used Notion to jot down what I’ve learned, so for my new blog, I wanted to fetch content directly from a Notion database and display it on my website. In short, I wanted to use Notion as a CMS (Content Management System).

Thankfully, Notion provides an official API and a JavaScript SDK that make this possible.

Step 1: Set up your Notion database

First, you need to create a database that stores the content pages you want to display on your blog.

Then, head over to Notion integrations and create a new integration.

After filling out the form and clicking save, select the integration you just created. From there, you can view your integration secret, which is essentially the API key your app will use to communicate with Notion. Make sure to select only read-only capabilities — follow the least privilege principle.

Step 2: Connect your database to the integration

Next, go to your Notion database page, click the ... menu at the top right, then select Connections. You should see a list of integrations — choose the one you just created to link it.

Step 3: Handling Notion blocks

The trickiest part was rendering the page content. Notion structures content as blocks, not just plain text. When you query a page, you’ll receive something like this:

{
  "object": "block",
  "id": "380c78c0-e0f5-4565-bdbd-c4ccb079050d",
  "type": "paragraph",
  "created_time": "",
  "last_edited_time": "",
  "has_children": false,

  "paragraph": {
    "text": [/* details omitted */]
  }
}

Rendering these blocks manually can be a bit of a hassle.

Step 4: Rendering with astro-notion

Fortunately, there’s a library called astro-notion by @jcha0713. It provides components that help convert Notion blocks into HTML elements that Astro can render.

However, since the library is no longer maintained and has a few bugs, I decided to fork the code and tweak it to better fit my needs.

If you're curious about the source code for this blog, you can check it out here: https://github.com/Qu1etboy/portfolio