@prkedia81/notion-blogs

notion-blogs

Turn a Notion database into a production-ready, SEO-friendly blog — with zero CMS to host and zero markdown to write.

@prkedia81/notion-blogs lets you write blog posts in Notion — the editor you already love — and pull them into any React, Next.js, or Node.js app as clean, structured data and ready-to-render HTML. Authors, tags, cover images, SEO descriptions, "similar posts", and rich content blocks all come parsed and typed out of the box.

import { NotionBlog } from '@prkedia81/notion-blogs';

const blog = new NotionBlog();              // reads NOTION_KEY + NOTION_BLOG_ID from env
const posts = await blog.getAllPosts();     // fully-typed BlogPost[]
const post  = await blog.getBlogBySlug('hello-world'); // includes rendered HTML

---

Table of contents

• Why notion-blogs?
• Features
• Installation
• Notion setup (5 minutes)
  • 1. Create a Notion integration
  • 2. Create your databases
  • 3. Share the databases with your integration
  • 4. Grab the database IDs
• Quick start
• Configuration
• API reference
  • NotionBlog
  • Standalone functions
  • parseBlocksToHTML
• Data types
• Rendering & styling the HTML
• Supported Notion blocks
• Framework recipes
  • Next.js (App Router)
  • Next.js (Pages Router)
  • Express / Node API
• Error handling & rate limits
• FAQ
• Roadmap
• Contributing
• License

---

Why notion-blogs?

Most "Notion as a CMS" solutions hand you back the raw, deeply-nested Notion API response and leave the hard parts to you. This package does the heavy lifting:

You get	Instead of
A clean BlogPost object with title, slug, author[], tags[], coverImage[], seoDescription…	Hundreds of lines of nested properties.title.title[0].plain_text access
Rendered, semantic HTML for the post body	A flat list of block objects you have to walk yourself
Resolved author and tag relations	Bare relation IDs you'd have to fetch and join manually
Built-in slug routing, "similar posts", and published/draft filtering	Custom query + filter plumbing
First-class TypeScript types for everything	any everywhere
Automatic pagination and rate-limit retries (429 backoff)	Manual cursor loops and retry logic

Write in Notion. Ship a blog. That's it.

---

Features

• Author in Notion — your writers never touch code or markdown.
• Block-to-HTML parser — paragraphs, headings, images, callouts, columns, tables, nested lists, to-dos, video (incl. YouTube embeds), files, dividers and rich-text annotations (bold, italic, code, color, links).
• Relations resolved — authors and tags are joined into each post automatically.
• Routing-ready — fetch by numeric ID or by URL slug.
• "Similar posts" — surface related content by shared author/tag with one flag.
• Drafts vs. published — only isPublished posts are returned by listings.
• Resilient — exponential-backoff retries on Notion rate limits and full pagination of long posts.
• TypeScript-first — ships its own .d.ts; zero @types needed.
• Framework-agnostic — works in Next.js (App & Pages Router), Remix, Astro, Express, or any Node runtime.

---

Installation

npm install @prkedia81/notion-blogs
# or
yarn add @prkedia81/notion-blogs
# or
pnpm add @prkedia81/notion-blogs

React is an optional peer dependency — you only need it if you use the bundled UI components. The core data/HTML APIs are pure Node and run anywhere.

# only if you use the React components
npm install react react-dom

---

Notion setup (5 minutes)

1. Create a Notion integration

1. Go to notion.so/my-integrations → New integration.
2. Give it a name (e.g. My Blog) and pick the workspace.
3. Copy the Internal Integration Secret — this is your NOTION_KEY.

2. Create your databases

You need one blog database (required) and, optionally, author and tag databases. Create the properties below — names are case-sensitive and must match exactly (note the space in AI summary).

Blog database (required)

Property	Notion type	Required	Notes
title	Title		Post title.
isPublished	Checkbox		Only true posts appear in listings.
ID	Unique ID		Auto-incrementing; used by getBlogById.
slug	Text	–	URL slug. Falls back to a slugified title if empty.
author	Relation → Author DB	–	One or more authors.
tags	Relation → Tag DB	–	One or more tags.
publishedDate	Date	–	Display/publish date.
coverImage	Files & media	–	Hero image(s).
seoDescription	Text	–	Meta description for <head>.
AI summary	Text	–	Optional short summary (note the space).
featured	Checkbox	–	Flag for highlighting a post.
createdDate	Created time	–	Auto-managed by Notion.
lastEditedDate	Last edited time	–	Auto-managed by Notion.

The body of each Notion page becomes the post content and is parsed to HTML when you fetch a single post.

Author database (optional)

Property	Notion type	Notes
name	Title	Author name.
slug	Formula → string	e.g. lower(replaceAll(prop("name"), " ", "-")). Used by getPostsByAuthor.
authorBio	Text	Short bio.
authorImage	Files & media	Avatar(s).
ID	Unique ID
createdDate	Created time
lastEditedDate	Last edited time

Tag database (optional)

Property	Notion type	Notes
name	Title	Tag name.
slug	Formula → string	Used by getPostsByTag.
ID	Unique ID
createdDate	Created time
lastEditedDate	Last edited time

If you don't configure an author or tag database, those relations simply resolve to empty arrays — the blog still works.

3. Share the databases with your integration

Open each database in Notion → ••• menu → Connections → add the integration you created. Without this step the API returns nothing.

4. Grab the database IDs

The database ID is the 32-character hash in the database URL:

https://www.notion.so/workspace/8a4b1c2d3e4f5061728394a5b6c7d8e9?v=...
                                └──────────── database ID ────────────┘

---

Quick start

The fastest path is environment variables. Create a .env:

NOTION_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_BLOG_ID=8a4b1c2d3e4f5061728394a5b6c7d8e9
NOTION_TAG_ID=...      # optional
NOTION_AUTHOR_ID=...   # optional

Then:

import { NotionBlog } from '@prkedia81/notion-blogs';

const blog = new NotionBlog();

// List every published post (no body content, ideal for index pages)
const posts = await blog.getAllPosts();

// Fetch one post by slug — includes rendered HTML in `post.content`
const post = await blog.getBlogBySlug('my-first-post');
console.log(post?.title);
console.log(post?.content); // -> "<h1>…</h1><p>…</p>"

Prefer explicit config over env vars? Pass it to the constructor:

const blog = new NotionBlog({
  notionKey: process.env.NOTION_KEY,
  blogDatabaseId: process.env.NOTION_BLOG_ID,
  authorDatabaseId: process.env.NOTION_AUTHOR_ID, // optional
  tagDatabaseId: process.env.NOTION_TAG_ID,       // optional
});

---

Configuration

Configuration is resolved from the constructor first, then falls back to environment variables. Credentials are cached on a singleton client, so initialize once and reuse.

Constructor option	Environment variable	Required	Description
notionKey	NOTION_KEY		Notion integration secret.
blogDatabaseId	NOTION_BLOG_ID		Blog database ID.
authorDatabaseId	NOTION_AUTHOR_ID	–	Author database ID.
tagDatabaseId	NOTION_TAG_ID	–	Tag database ID.

Setting NODE_ENV=development enables verbose [notion-blogs]: debug logging.

---

API reference

class NotionBlog

The recommended entry point. Construct it once and call its async methods.

const blog = new NotionBlog(config?);

Method	Returns	Description
getAllPosts()	Promise<BlogPost[]>	All published posts with authors and tags resolved. Body content is not included (fast — perfect for index/listing pages).
getBlogById(id, includeSimilarBlogs?)	Promise<BlogPost | null>	Fetch a single post by its numeric ID. Includes rendered HTML in content. Returns null if not found.
getBlogBySlug(slug, includeSimilarBlogs?)	Promise<BlogPost | null>	Fetch a single post by its slug. Includes rendered HTML in content. Returns null if not found.
getAllAuthors()	Promise<Authors[]>	Every author. Returns [] if no author DB is configured.
getPostsByAuthor(authorSlug)	Promise<{ author: Authors | null; filteredBlogs: BlogPost[] }>	The author plus all their published posts.
getAllTags()	Promise<Tags[]>	Every tag. Returns [] if no tag DB is configured.
getPostsByTag(tagSlug)	Promise<BlogPost[]>	All published posts carrying that tag.

Pass includeSimilarBlogs = true to populate post.similarPosts with up to 5 related posts (matched by shared author or tag, falling back to other recent posts).

const post = await blog.getBlogBySlug('scaling-notion', true);
post?.similarPosts?.forEach((p) => console.log(p.title));

Standalone functions

If you'd rather manage the Notion Client yourself (e.g. for DI or testing), every operation is exported as a standalone function that takes a Client as its first argument:

import {
  getClient,
  getAllPosts,
  getBlogById,
  getBlogBySlug,
  getPageById,
  getAllAuthors,
  getPostsByAuthor,
  getAllTags,
  getPostsByTag,
} from '@prkedia81/notion-blogs';

const client = getClient(); // singleton @notionhq/client, configured from env
const posts = await getAllPosts(client);

parseBlocksToHTML(blocks)

Convert an array of Notion block objects into a semantic HTML string. Useful if you fetch blocks yourself but still want this package's renderer.

import { parseBlocksToHTML } from '@prkedia81/notion-blogs';

const html = parseBlocksToHTML(blocks); // -> string of HTML

There's also a formatDate(isoString) helper that returns a friendly date (e.g. "June 25, 2026").

import { formatDate } from '@prkedia81/notion-blogs';
formatDate(post.publishedDate); // "June 25, 2026"

---

Data types

Everything is fully typed. The core shapes:

interface BlogPost {
  ID: number;
  title: string;
  slug: string;
  content?: string;          // rendered HTML (single-post fetches only)
  author: Authors[];
  tags: Tags[];
  coverImage: string[];
  seoDescription: string;
  'AI summary': string;
  featured: boolean;
  isPublished: boolean;
  publishedDate: string;     // ISO date
  createdDate: string;       // ISO date
  lastEditedDate: string;    // ISO date
  similarPosts?: BlogPost[]; // when includeSimilarBlogs = true
}

interface Authors {
  uuid: string;
  id: number;
  name: string;
  slug: string;
  image: string[];
  bio: string;
  createdDate: string;
  lastEditedDate: string;
}

interface Tags {
  uuid: string;
  id: number;
  name: string;
  slug: string;
  createdDate: string;
  lastEditedDate: string;
}

The lower-level Block, RichText, and per-block-type interfaces are exported too, for anyone building a custom renderer.

---

Rendering & styling the HTML

getBlogById / getBlogBySlug return ready-to-render HTML in content. Drop it in with dangerouslySetInnerHTML (or your framework's equivalent):

export default function Post({ post }: { post: BlogPost }) {
  return (
    <article className="notion-content">
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content ?? '' }} />
    </article>
  );
}

The generated HTML uses stable, predictable class names so you can style it however you like. Key hooks:

Class	Applied to
.notion-heading	<h1>/<h2>/<h3>
.notion-image	image <figure>
.notion-callout	callout box
.notion-column-list / .notion-column	multi-column layouts
.notion-table / .notion-table-container	tables
.notion-video / .notion-video-container	video & YouTube embeds
.notion-file	file attachments
.notion-todo-item (.checked)	to-do items
.notion-hr	dividers
.color-<name>	Notion text/background colors

Style these classes in your own CSS, or scope a .prose / Tailwind Typography wrapper around the rendered content for instant, attractive defaults.

---

Supported Notion blocks

Supported	Notes
Paragraph	with bold, italic, strikethrough, underline, inline code, color, links
Heading 1 / 2 / 3
Bulleted list	nested children supported
Numbered list	nested children supported
To-do	rendered with a disabled checkbox reflecting checked state
Image	external & uploaded, with captions, lazy-loaded
Callout	emoji icon + color
Columns	multi-column layouts (column_list / column)
Table	header rows, multi-column
Video	direct files and YouTube → responsive iframe embed
File	download link with filename
Divider

Unsupported block types are skipped gracefully rather than throwing.

---

Framework recipes

Next.js (App Router)

// app/blog/[slug]/page.tsx
import { NotionBlog } from '@prkedia81/notion-blogs';

const blog = new NotionBlog();

export async function generateStaticParams() {
  const posts = await blog.getAllPosts();
  return posts.map((p) => ({ slug: p.slug }));
}

export async function generateMetadata({ params }: { params: { slug: string } }) {
  const post = await blog.getBlogBySlug(params.slug);
  return { title: post?.title, description: post?.seoDescription };
}

export default async function BlogPostPage({ params }: { params: { slug: string } }) {
  const post = await blog.getBlogBySlug(params.slug, true);
  if (!post) return <p>Not found</p>;

  return (
    <article>
      <h1>{post.title}</h1>
      {post.coverImage[0] && <img src={post.coverImage[0]} alt={post.title} />}
      <div dangerouslySetInnerHTML={{ __html: post.content ?? '' }} />
    </article>
  );
}

Next.js (Pages Router)

// pages/blog/[slug].tsx
import type { GetStaticPaths, GetStaticProps } from 'next';
import { NotionBlog, type BlogPost } from '@prkedia81/notion-blogs';

const blog = new NotionBlog();

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await blog.getAllPosts();
  return { paths: posts.map((p) => ({ params: { slug: p.slug } })), fallback: 'blocking' };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const post = await blog.getBlogBySlug(params!.slug as string);
  if (!post) return { notFound: true };
  return { props: { post }, revalidate: 60 };
};

export default function Post({ post }: { post: BlogPost }) {
  return <div dangerouslySetInnerHTML={{ __html: post.content ?? '' }} />;
}

Express / Node API

import express from 'express';
import { NotionBlog } from '@prkedia81/notion-blogs';

const app = express();
const blog = new NotionBlog();

app.get('/api/posts', async (_req, res) => {
  res.json(await blog.getAllPosts());
});

app.get('/api/posts/:slug', async (req, res) => {
  const post = await blog.getBlogBySlug(req.params.slug);
  post ? res.json(post) : res.status(404).json({ error: 'Not found' });
});

app.listen(3000);

---

Error handling & rate limits

• Rate limits (HTTP 429): requests are automatically retried with exponential backoff (3 attempts, doubling delay) — you don't need to handle 429s yourself.
• Pagination: long posts are fully paginated; you always get the complete body, no matter the length.
• Missing posts: getBlogById / getBlogBySlug return null (and log a warning) rather than throwing, so guarding with if (!post) is enough.
• Missing config: constructing without a key (and no NOTION_KEY) throws a clear, actionable error.

const post = await blog.getBlogBySlug('does-not-exist');
if (!post) {
  // render your 404
}

---

FAQ

Do I need the author and tag databases? No. They're optional. Without them, author and tags resolve to empty arrays.

Why is content empty on getAllPosts()? By design — listing pages don't need full bodies, so listings skip the (expensive) block fetch. Use getBlogBySlug / getBlogById for the rendered HTML.

Are drafts exposed? No. Only posts with isPublished = true are returned by the listing methods.

Is it server-side only? Treat it as server-side. Your NOTION_KEY must never reach the browser — call these methods in server components, route handlers, getStaticProps, or your backend.

Does it work with TypeScript? Yes — types ship with the package, no @types/... needed.

---

Roadmap

• Richer, themeable React components (cards, lists, full post renderer)
• Pluggable custom block renderers
• Code blocks with syntax highlighting
• Audio & toggle block support
• Built-in flex/grid layout presets
• Incremental cache / revalidation helpers

Have a request? Open an issue.

---

Contributing

Contributions, issues, and feature requests are welcome!

git clone https://github.com/prkedia81/notion-blog-package.git
cd notion-blog-package
npm install
npm run build   # compile TS + build CSS
npm test

Please run npm run lint and npm run format before opening a PR.

---

License

ISC Prannay Kedia

---

_{Built for people who'd rather write in Notion than wrestle a CMS.}