
**Ever wanted to use Notion as a blog CMS? This guide will walk you through how to setup Notion for blogging and how to access the data using Notions public API.**

Notions public API is finally here! I put together [an example repo](https://github.com/samuelkraft/notion-blog-nextjs) on creating a blog using **Notion as a CMS** hours after the release and was blown away by the interest so here's a guide explaining how to set it up yourself using the new api & Next.js.

## Getting started

If you're new to the notion API the first thing you need to do in order to start using it is to retrieve a `NOTION_TOKEN` by following their [Getting Started guide](https://developers.notion.com/docs/getting-started). When following the guide create either a table or a list as the database for your content. After finishing you should have a `NOTION_TOKEN` as well as a database id.

Create a Next.js project by following the [Next.js app setup](https://nextjs.org/learn/basics/create-nextjs-app/setup). The neat thing about using Next.js is that you can statically render all blog posts, while still updating them with *incremental static generation* making your blog super snappy ⚡️.

<Warning type="info">
  This guide assumes you are using Next.js but you can use plain javascript or whatever framework you wish, the Notion code is the same.
</Warning>

Save your `NOTION_TOKEN` and `NOTION_TABLE_ID` to a `.env.local` file in your projects root directory, then install their javascript client by running `yarn add @notionhq/client` .

## Fetching data using Notions javascript client

Let's create a new file called `lib/notion.js` which will contain all our API usage. To fetch our data we first need to create a client and supply it with the token we received earlier

```jsx
import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});
```

Then we need to add the functions we need. To get a list of our posts we need to be able to query a specific database (`getDatabase`), to get the information for a specific post we need to get a specific page (`getPage`), and to actually get the content of the page we need get its blocks (`getBlocks`).   

```jsx{7-25}
import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

export const getDatabase = async (databaseId) => {
  const response = await notion.databases.query({
    database_id: databaseId,
  });
  return response.results;
};

export const getPage = async (pageId) => {
  const response = await notion.pages.retrieve({ page_id: pageId });
  return response;
};

export const getBlocks = async (blockId) => {
  const response = await notion.blocks.children.list({
    block_id: blockId,
    page_size: 50,
  });
  return response.results;
};
```

## Showing a list of posts

Add a function called `getInitialProps` to `pages/index.js` where you use the getDatabase function to fetch all posts. The response will contain a [Database Object](https://developers.notion.com/reference/database) containing information like the database title, when it was last edited as well as its properties (in our case blogposts).

<Warning type="info">
  If you're new to Next.js getStaticProps allows you to pre-render the page at build time using the props returned by the function. Combining this with the revalidate prop will allow the page to get updated in the background as new traffic comes in without the need to rebuild your entire site. Learn more about <a href="https://nextjs.org/docs/basic-features/data-fetching#incremental-static-regeneration">Incremental Static Generation</a>.
</Warning>

```jsx
import Link from "next/link";
import { getDatabase } from "../lib/notion";
import { Text } from "./[id].js";

export const databaseId = process.env.NOTION_DATABASE_ID

export default function Home({ posts }) {
  return (  
    <ol className={styles.posts}>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/${post.id}`}>
             <Text text={post.properties.Name.title} />
          </Link>
        </li>
      ))}
    </ol> 
  );
}

export const getStaticProps = async () => {
  const database = await getDatabase(databaseId);

  return {
    props: {
      posts: database,
    },
		// Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every second
    revalidate: 1, // In seconds
  };
};
```

<Warning type="info">
We're using the post id as slug for sake of simplicity in this tutorial. For SEO purposes it would be better to use a prettier slug based on the title. You can do this by either manually adding a slug property to each post in Notion or generating a slug with a package like <a href="https://www.npmjs.com/package/slugify">slugify</a>.
</Warning>

Uhm, what is that `<Text />` component you might ask? Notion has a lot of rich text tools allowing you to **format** <ins>text</ins> ~~like~~ *this,* so instead of just returning a plain text value each text-like field returns an array of [Rich text objects](https://developers.notion.com/reference/rich-text) like this:

```jsx
{
  annotations: {
    bold: false,
    italic: false,
    strikethrough: false,
    underline: false,
    code: false,
    color: 'default'
  },
  href: null,
  plain_text: "Hello world!",
  text: {
    content: "Hello world!",
    link: null
  },
  type: "text"
}
```

In order to handle links and annotations let's create a component that we can re-use for all types of text:

```jsx
import styles from './text.module.css'

export const Text = ({ text }) => {
  if (!text) {
    return null;
  }
  return text.map((value) => {
    const {
      annotations: { bold, code, color, italic, strikethrough, underline },
      text,
    } = value;
    return (
      <span
        className={[
          bold ? styles.bold : "",
          code ? styles.code : "",
          italic ? styles.italic : "",
          strikethrough ? styles.strikethrough : "",
          underline ? styles.underline : "",
        ].join(" ")}
        style={color !== "default" ? { color } : {}}
      >
        {text.link ? <a href={text.link.url}>{text.content}</a> : text.content}
      </span>
    );
  });
};
```

```css
.bold {
  font-weight: bold;
}

.code {
  font-family: monospace;
  background-color: rgb(242, 242, 242);
  padding: 2px 4px;
  border-radius: 2px;
}

.italic {
  font-style: italic;
}

.strikethrough {
  text-decoration: line-through;
}

.underline {
  text-decoration: underline;
}
```

## Showing a specific post

Let's create a `pages/[id].js` page that will show the content of each blog post

```jsx
import { Fragment } from "react";
import { getDatabase, getPage, getBlocks } from "../lib/notion";
import { databaseId } from "./index.js";
import Text from 'components/text'

const renderBlock = (block) => {
  const { type, id } = block;
  const value = block[type];

  switch (type) {
    case "paragraph":
      return (
        <p>
          <Text text={value.text} />
        </p>
      );
    case "heading_1":
      return (
        <h1>
          <Text text={value.text} />
        </h1>
      );
    case "heading_2":
      return (
        <h2>
          <Text text={value.text} />
        </h2>
      );
    case "heading_3":
      return (
        <h3>
          <Text text={value.text} />
        </h3>
      );
    case "bulleted_list_item":
    case "numbered_list_item":
      return (
        <li>
          <Text text={value.text} />
        </li>
      );
    case "to_do":
      return (
        <div>
          <label htmlFor={id}>
            <input type="checkbox" id={id} defaultChecked={value.checked} />{" "}
            <Text text={value.text} />
          </label>
        </div>
      );
    case "toggle":
      return (
        <details>
          <summary>
            <Text text={value.text} />
          </summary>
          {value.children?.map((block) => (
            <Fragment key={block.id}>{renderBlock(block)}</Fragment>
          ))}
        </details>
      );
    case "child_page":
      return <p>{value.title}</p>;
    case "image":
      const src =
        value.type === "external" ? value.external.url : value.file.url;
      const caption = value.caption ? value.caption[0].plain_text : "";
      return (
        <figure>
          <img src={src} alt={caption} />
          {caption && <figcaption>{caption}</figcaption>}
        </figure>
      );
    default:
      return `❌ Unsupported block (${
        type === "unsupported" ? "unsupported by Notion API" : type
      })`;
  }
};

export default function Post({ page, blocks }) {
  if (!page || !blocks) {
    return <div />;
  }
  return (   
    <article>
      <h1>
        <Text text={page.properties.Name.title} />
      </h1>
      <section>
        {blocks.map((block) => (
          <Fragment key={block.id}>{renderBlock(block)}</Fragment>
        ))}
      </section>
    </article>
  );
}

export const getStaticPaths = async () => {
  const database = await getDatabase(databaseId);
  return {
    paths: database.map((page) => ({ params: { id: page.id } })),
    fallback: true,
  };
};

export const getStaticProps = async (context) => {
  const { id } = context.params;
  const page = await getPage(id);
  const blocks = await getBlocks(id);

  // Retrieve block children for nested blocks (one level deep), for example toggle blocks
  // https://developers.notion.com/docs/working-with-page-content#reading-nested-blocks
  const childBlocks = await Promise.all(
    blocks
      .filter((block) => block.has_children)
      .map(async (block) => {
        return {
          id: block.id,
          children: await getBlocks(block.id),
        };
      })
  );
  const blocksWithChildren = blocks.map((block) => {
    // Add child blocks if the block should contain children but none exists
    if (block.has_children && !block[block.type].children) {
      block[block.type]["children"] = childBlocks.find(
        (x) => x.id === block.id
      )?.children;
    }
    return block;
  });

  return {
    props: {
      page,
      blocks: blocksWithChildren,
    },
    revalidate: 1,
  };
};
```

That's a lot, so let's break it down starting from the bottom.

Just as on the index page we are using getStaticProps to get the data so the page can be statically rendered. In order to know which post to render we'll use the `context` parameter which contains route parameters for the current page. With the post id we can then use our two notion functions `getPage()` and `getBlocks()` and return the results as props to our component.

For performance reasons any nested child blocks won't be returned with the original call. If you need to get a complete representation including child blocks (for example toggle blocks) then you need to run the getBlocks function for each block containing the `has_children` property. When you have received all the children you can then merge the original blocks array with the childblock data (`blocksWithChildren`).


When using dynamic routes we also need to specify a list of availables routes and we'll do that with `getStaticPaths` by mapping over the pages and returning the page id's.

## Rendering Notion blocks

The `blocks` prop contains a list of all the blocks as [Block Objects](https://developers.notion.com/reference/block). We have created a `renderBlock()` function that will take care of displaying the different blocks.

```jsx
switch (type) {
  case "paragraph":
    return (
      <p>
        <Text text={value.text} />
      </p>
    );
  case "heading_1":
    return (
      <h1>
        <Text text={value.text} />
      </h1>
    );
  case "heading_2":
		…
```

Open up the index page in your browser and click a post and you should see a working page displaying your content!

## Notion API unsupported blocks

During the Notion API beta unfortunately not all block types are supported. The supported block types are:

- `paragraph`
- `heading_1`
- `heading_2`
- `heading_3`
- `bulleted_list_item`
- `numbered_list_item`
- `to_do`
- `toggle`

*Update 2020/08/24* - New media block types added:
- `child_page`
- `image`
- `embed`
- `video`
- `file`
- `pdf`
- `bookmark`

If you use a block that is not supported the page will display `❌ Unsupported block`. At this time there's no way of getting around this other than using their private API which is not recommended and can change at any time. If you need more blocks than those available right now I would wait a little bit longer until all block types are available.

## Styling

This guide intentionally comes without any styles as you would probably just rip it out anyways. If you want inspiration I put together some very bare-bones styles [in my example repo at GitHub](https://github.com/samuelkraft/notion-blog-nextjs).

## That's it!

You now have a blog powered by Notion! If you add a new blogpost or edit a post then the page will automatically get updated on the second hit thanks to Next.js incremental static regeneration. Check out my [live example here](https://notion-blog-nextjs-coral.vercel.app) and let me know if you enjoyed this post by pressing ❤️ below or pinging me [on twitter](https://twitter.com/samuelkraft)

<Image
  alt="Blog powered by Notion and Next.js"
  caption="Blog powered by Notion and Next.js"
  src={'/blog/building-a-notion-blog-with-public-api/screenshot.png'}
  width={2216}
  height={1504}
/>



When deciding to build a website in 2021 there's a bit of a double edged sword, the choices are really endless, with new frameworks and tools getting released almost daily. For this website I wanted to try out [Next.js](https://nextjs.org), a javascript framework built on React that handles all the hard parts about server side rendering & configs. (If you've ever debugged webpack configs you'll appreciate not having to worry about that stuff anymore).

The reason I chose Next.js is how easily you can create really performant websites. With [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) you can build super fast completely static pages which can also update periodically without needing to rebuild your whole site. In getStaticProps you can call any type of api or fetch data from the filesystem (like this blog), and then forward the data as props to your component. getStaticProps is run at build-time so the visitors will always get served a fast static page.

```js
export async function getStaticProps(context) {
  return {
    props: {}, // will be passed to the page component as props
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every second
    revalidate: 1, // In seconds
  }
}
```

My initial idea for this website was to have four sections:

- Portfolio
- About me
- Blog
- Book reviews

I knew I wanted to build the blog based on MDX and the Next.js team have a really good [example repo](https://github.com/vercel/next.js/tree/canary/examples/with-mdx-remote) settings this up so I won't go through that part in further detail.

## Fetching data from Notion

Last year I started using [Notion](https://www.notion.so/) and I've grown very fond of it. It's now pretty much my [second brain](https://email.aliabdaal.com/issues/how-to-build-a-second-brain-271393), containing everything from work related things to personal health goals. I read a lot of books which I've just started reviewing and add thoughts to in Notion. It's setup as a simple table containing some pages with reviews. Why not share this on my website?

<Image
  alt="Books section in Notion"
  caption="My books section in Notion"
  src={'/blog/building-my-personal-website-with-nextjs-backed-by-notion/books-table.png'}
  width={1672}
  height={700}
/>

Notion doesn't have a public api ([yet](https://www.notion.so/api-beta)), but we can use an unofficial wrapper called [notion-api-worker](https://github.com/splitbee/notion-api-worker) or roll your own thing like Guillermo Rauch does [here](https://github.com/rauchg/blog/blob/master/lib/notion.js).

<Warning>Note: notion-api-worker uses notion's private api which could change whenever - use at your own risk</Warning>

You can host the api yourself or use the hosted one provided by splitbee like we'll be doing in the example below. Loading our list of books is as simple as creating a new file inside our pages folder, adding getStaticProps and calling the id of our table.

```jsx
export async function getStaticProps() {
  const books = await fetch('https://notion-api.splitbee.io/v1/table/<NOTION_TABLE_ID>').then(res => res.json())

  return {
    props: {
      books,
    },
  }
}
```

<Warning>
  Note: Using their hosted api will only work on published notion pages. Publishing your page on notion will obviously make it public to
  everyone. If you're not ok with keeping non-finished stuff public you can access private pages by adding your NOTION_TOKEN as described{' '}
  <Link href="https://github.com/splitbee/notion-api-worker#authentication-for-private-pages">here</Link>
</Warning>

Our books prop will contain a list of items containing all properties of your subpages. In my example I have a few properties like author, rating, date finished, genres etc.

<Image
  alt="A book in Notion"
  caption="Book properties in Notion"
  src={'/blog/building-my-personal-website-with-nextjs-backed-by-notion/book-properties.png'}
  width={1330}
  height={1052}
/>

Which maps to these types:

```jsx
export type Book = {
    Author: string
    Date: string
    Fiction: boolean
    Genres: Array<string>
    Name: string
    Rating: number
    Published: boolean
    Image: Array<{
        name: string
        rawUrl: string
        url: string
    }>
    Link: string
    id: string
}
```

To render our list of books we'll map over all the books and add some styling:

```jsx
import Link from 'next/link'
import Image from 'next/image'
import Rating from 'components/rating'
import slugifiy from 'slugify'
import styles from './books.module.scss'

<ul className={styles.grid}>
    {books.map(({ Name: title, Author: author, Rating: rating, Image: image, id }) => {
        const slug = slugifiy(title, { lower: true })
            return (
                <li className={styles.book} key={id}>
                    <Link href={books/${slug}}>
                        <a>
                            <Image src={image[0].url} width={218} height={328} className={styles.cover} />
                            <strong className={styles.title}>{title}</strong>
                            <p className={styles.author}>{author}</p>
                            <Rating rating={rating} />
                        </a>
                    </Link>
                </li>
            )
    })}
</ul>
```

We can use Next/Image in order to automatically render an optimised image. When building our specific book pages which will show our reviews and notes I'd like to have pretty slugs instead of using the notion id directly. We can do this either by adding a slug property directly in notion, or use a package like slugify to generate one for us.

For building our book pages we'll use [Next.js dynamic routes](https://nextjs.org/docs/routing/dynamic-routes). We can do this by matching our folder stucture to our url structure. For this example we'll create a "book" folder inside "pages" and create a new file called [slug].js.

```jsx
pages/book/[slug].js → /boom/:slug (/book/vagabonding)
```

Inside [slug].js we need to specify exactly which slugs we have. We do this with the function [getStaticPaths](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation). We'll fetch our books table like before, mapping over the values to create list of possible paths including our custom slugs.

```jsx
export const getStaticPaths: GetStaticPaths = async () => {
    const bookRes = await fetch(https://notion-api.splitbee.io/v1/table/[NOTION_TABLE_ID])
    const bookData = await bookRes.json()
    const paths = bookData.map(b => /books/${slugify(b.Name, { lower: true })})
    return {
        paths,
        fallback: false,
    }
}
```

Moving on to getStaticProps we need to get our list of books again, in order to find out the notion page id for our specific slug. We can get our current page slug from context, which is the first parameter of the function. We'll use it to find the specific book from our list and then fetch that books details by it's id

```jsx
export const getStaticProps: GetStaticProps = async context => {
    const bookRes = await fetch(https://notion-api.splitbee.io/v1/table/[NOTION_TABLE_ID])
    const bookData = await bookRes.json()

    if (!bookData) {
        return {
            notFound: true,
        }
    }

    const { slug } = context.params
    const book = bookData.find(b => slugify(b.name, { lower: true }) === slug)

    const pageRes = await fetch(`https://notion-api.splitbee.io/v1/page/${book.id}
    const pageData = await pageRes.json()

      return {
        props: {
          book,
          page: pageData,
        },
        revalidate: 1,
      }
    }
```

The pageData variable contains json which you can render however you want, or you can simply use the [react-notion](https://github.com/splitbee/react-notion) package created by the same authors as notion-api-worker.

```jsx
import 'react-notion/src/styles.css'
import { NotionRenderer } from 'react-notion'

export default ({ pageData }) => (
  <div style={{ maxWidth: 768 }}>
    <NotionRenderer blockMap={pageData} />
  </div>
)
```

This will in turn render your content pretty much exactly like it appears in Notion. What's really great is that thanks to Next.js static rendering this page will be much faster than notion itself 😅

If you want to tweak the styling simply wrap NotionRenderer in a div and apply any custom styling. On my website I'm using this to tweak a few font-sizes and font-weights and set the text color to a custom variable so my site works in dark mode.

```css
.post {
    h1,
    h2,
    h3,
    h4,
    h5,
    h6,
    p,
    ul,
    li,
    ol {
        color: var(--text);
}
```

That's it, check out an example of this on [/books](/books) and [/books/vagabonding](/books/vagabonding) or the source code available on [GitHub](https://github.com/samuelkraft/samuelkraft-next).

Let me know if you have any questions or feedback by emailing samuelkraft [at] me.com.

✌️
