Writing in Notion, publishing on your site

Notion is a comfortable place to write. It is on every device, it saves as you type, and a post can start as three bullet points and grow into an essay without moving anywhere. What it is not is a good place to publish. A public Notion page is slow to load, looks like every other Notion page, and lives on someone else's domain.

The usual answer is to keep writing in Notion and build the site from it: one database holds the posts, each row is a post, and the site turns rows into pages.

The pieces

1. A database with a title, a date and whatever else you want to show, such as tags or a summary.
2. An integration that can read it. Create one in Notion's settings, give it only the Read content capability, and connect it to the database.
3. A site that asks the API for the rows and the blocks of each page, and renders them.

The first two take five minutes. The third is where the work is, and where notion-kit comes in.

Fetching

@yokinist/notion-fetch does the talking to Notion. It reads every row of the database, fetches a page's blocks with their nested children in one call, and keeps requests under Notion's rate limit, which a site build easily exceeds.

const rows = await queryDatabase(notion, databaseId, { limit });
const blocks = await fetchBlockTree(notion, rows[0].id, { limit });

Rendering

@yokinist/notion-rsc turns the blocks into HTML with React Server Components. Code is highlighted, equations are typeset and embeds become cards, all on the server, so readers get a page that is mostly HTML and loads fast.

<NotionBlocks blocks={blocks} />