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.

kerwanp/contentlayer-source-notion