Contentlayer Source Notion

⚠️ Alpha test • 🎲 Features • 🚀 Get started • 🔧 Configure • ✍ Contribute

Contentlayer Source Notion is a Contentlayer plugin to use Notion.so as a content source.

⚠️ Alpha test

This plugin is actually under heavy-development, use it at your own risks or for testing purposes only.

You can contribute to this project by listing bugs and giving ideas in the issues of this repository.

Do not report bugs related to contentlayer-source-notion in the official repository.

🎲 Features

• Generate your content from Notion Databases
• Automatically infer the type of your properties
• Render HTML from your Rich Text properties and pages content (@notion-render/client)
• Filter and sorts pages queried from your databases
• Use Rollup and Relation properties with ease
• Recompute values to create new fields (computed fields)
• Iteration and cache system to work safely with ton of pages

🚀 Getting started

1. Install Contentlayer, Notion source plugin and dependencies

$ npm install contentlayer contentlayer-source-notion @notionhq/client
$ yarn add contentlayer contentlayer-source-notion @notionhq/client

2. Create a database

Save your database ID, it should be available in the url: /myworkspace/fe26b972ec3f4b32a1882230915fe111?v=b56e97ee99a74f3f8c3ee80543fe22c6

3. Get a Notion Token

To interact with Notion you need to create an integration and give it the correct permissions. Create a new integration by heading to the following link.

You should then have your Notion Token, also called Internal Integration Token.

4. Add the integration to your databases

By default, your integration does not have any permissions. On each databases you want to query, click on the ••• in the top right corner.

Click on Add connection and select your Integration. Your token should now have access to your database.

5. Configure and build Contentlayer

You can configure your content source in the contentlayer.config.js file and then run contentlayer build.

import { makeSource, defineDatabase } from 'contentlayer-source-notion'
import * as notion from '@notionhq/client'

const client = new notion.Client({
  auth: '<notion_token>',
})

const Post = defineDatabase(() => ({
  name: 'Post',
  databaseId: '<database_id>',
}))

export default makeSource({
  client,
  databaseTypes: [Category, Post],
})

ℹ Read more on how to configure contentlayer-source-notion here

6. Use generated content

Contentlayer will generate your content and typings in the .contentlayer folder.

import { allPosts } from './.contentlayer/generated/index.mjs'

const postIds = allPosts.map((post) => post._id)

🔧 Configure

Source plugin options

import { makeSource } from 'contentlayer-source-notion'

export default makeSource({
  client,
  renderer,
  databaseTypes: [],
})

The PluginOptions supports the following parameters. Thoses options are defined when using makeSource.

Option	Default value	Type	Description
client	undefined	Client	The Notion Client used to query the Notion API.
renderer	undefined	NotionRenderer	The renderer used to transform Notion Blocks into HTML
databaseTypes		DatabaseType[] | Record<string, DatabaseType>	The databases definitions.

Database definition options

import { defineDatabase } from 'contentlayer-source-notion'

const Post = defineDatabase(() => ({
  name: 'Post',
  databaseId: '<database_id>',
  importContent: false,
  automaticImport: true,
  properties: {
    email: {
      name: 'Email',
      description: 'The author email',
      isRequired: true,
    },
  },
}))

The DatabaseTypeDef supports the following parameters. Thoses options are defined when using defineDatabase.

Option	Default value	Type	Description
name		string	The name of this content used to generate types and constants names.
description	undefined	string	The description of this content used to generate comments
databaseId		string	The database ID where your pages will be queried from
automaticImport	undefined	bool	By default, all your properties will be generated. By disabling automatic import you can whitelist the properties you want to use. Useful when you have sensitive content in your page properties
importContent	undefined	bool	By default, your page content will be generated. Disable it if you only want to use the properties.
query	undefined	QueryDatabaseParameters	Filter and sorts the page queried from the Notion API. More information on the @notionhq/client repository
properties	undefined	Record<string, DatabasePropertyTypeDef> | DatabasePropertyTypeDef[]	The properties definitions. When using Record<string, DatabasePropertyTypeDef> the key will be used as the key option.
computedFields	undefined	Record<string, ComputedField>	Create computed fields by using existing database properties.

Field definition options

The DatabasePropertyTypeDef supports the following parameters. Thoses options are defined when using defineDatabase.

Option	Default value	Type	Description
id|name		string	The id or name of the property you want to configure.
key	undefined	string	Map this property to a specific key. Defaults to the property name.
description	undefined	string	Field description used to generate comments.
isRequired	false	bool	When required, pages without this property defined will not be generated.

Configure the Notion Client

This plugin depends on the official Notion JS SDK, you can find more information on how to configure it on the following repository.

import { makeSource, defineDatabase } from 'contentlayer-source-notion'
import * as notion from '@notionhq/client'

const client = new notion.Client({
  auth: '<notion_token>',
})

export default makeSource({
  client,
  renderer,
  databaseTypes: [],
})

Configure the Notion Renderer

Rich text properties and your pages content must be renderer, you can find more information on how to configure it on the following repository.

import { makeSource, defineDatabase } from 'contentlayer-source-notion'
import { NotionRenderer } from '@notion-render/client'
import * as notion from '@notionhq/client'

const client = new notion.Client({
  auth: '<notion_token>',
})

const renderer = new NotionRenderer({ client })

export default makeSource({
  client,
  renderer,
  databaseTypes: [],
})

✍ Contribute

Wether it is a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from the community.

You can :

• Report Bugs/Reafture Requests directly in the issues.
• Contribute via Pull Requests

If you have any questions, feel free to join the Official Contentlayer Discord.