Introduction

NotCMS connects the Notion databases your team edits to the website you build. Writers work in Notion; developers use a TypeScript SDK to read properties and Markdown content from NotCMS.

How content reaches your site

Connect Notion in the dashboard, register a database, and wait for its initial synchronization to finish.
Generate a schema with the CLI. It gives your code database and property names, types, and known select options.
Fetch synchronized content on your server or during your site’s build.

Later Notion edits become available after synchronization completes. A statically built site also needs a rebuild and deployment; a server-rendered site may need its cache refreshed. Synchronization and your site’s publication are separate steps. See the Astro guide for a concrete example.

Read content with types

After setup, import the generated client. This example assumes that your database is called blog and has a published checkbox:

import { nc } from "./notcms/schema";

const [posts, error] = await nc.query.blog.list({
  where: { published: true },
});
if (error) throw error;

for (const post of posts) {
  console.log(post.title, post.properties.published);
}

The schema describes the content shape captured by the last pull. It enables editor completion and compile-time checks; it does not validate every value at runtime. Synchronize and pull again after changing your Notion database.

Choose what to publish

NotCMS does not give a property named published special meaning. Decide which pages your application should expose and apply that rule to both lists and individual pages. Keep the secret key on the server. See the publication recipes for scheduled publication, languages, and detail-page checks.

Choose a query

List pages to retrieve properties with optional filters and sorting.
Fetch one page to retrieve Markdown content by ID or a property such as a slug.
Handle errors by checking the SDK’s error tuple before using data.

This documentation targets the published NotCMS 0.5.0 API. Older projects can use the migration guide. Start with the quickstart, then choose the Next.js or Astro integration.

Getting Started

Usage

CLI Commands

Examples

How content reaches your site

Read content with types

Choose what to publish

Choose a query

​How content reaches your site

​Read content with types

​Choose what to publish

​Choose a query

How content reaches your site

Read content with types

Choose what to publish

Choose a query