Docs/Publishing

Publish to Notion

Push posts into a Notion database as fully formatted pages.

Notion is best thought of as a content hub rather than a live blog — use it to keep your team's workspace in sync with what you're writing.

Create an integration

  • Go to notion.so/my-integrations and hit New integration.
  • Give it a name, pick the workspace, and create it.
  • Copy the Internal Integration Token.

Share your database with it

  • Open the Notion database you want posts to land in.
  • Click the ··· menu at the top right, choose Connections, and add the integration you just made.
  • Skipping this step is the single most common mistake — the token alone grants no access to anything.

Find your database ID

Open the database as a full page and look at the URL. The database ID is the 32-character block of letters and numbers before the question mark.

The bold section is your database IDhttps://notion.so/workspace/a1b2c3d4e5f67890a1b2c3d4e5f67890?v=... ^--------- 32 characters ---------^

Connect it

  • Integration token — the internal token you copied.
  • Database ID — the 32-character id. Dashes are fine, we strip them.

What gets published

  • The post title goes into your database's title property — whatever you've named it. We detect it automatically, so it doesn't have to be called Name.
  • The body becomes real Notion blocks: headings, paragraphs, bulleted and numbered lists, quotes, code blocks, images and dividers.
  • Bold, italic, inline code and links are preserved inside paragraphs.
  • Your featured image becomes the page cover.

Limits worth knowing

  • Notion supports three heading levels, so anything deeper is flattened to the third.
  • Very long posts are capped at 400 blocks.
  • Other database properties beyond the title aren't filled in.

Publishing again

Notion has no way to cleanly replace a page's contents, so republishing archives the old page and creates a new one. The old version isn't lost — it goes to your Notion trash and can be restored.

Troubleshooting

  • Couldn't read the Notion database — the database almost certainly hasn't been shared with your integration. Redo the Connections step above.
  • Database ID should be the 32-character id — you've likely pasted the whole URL or a page id rather than a database id.
  • Notion rejected the token — the token was regenerated or the integration was deleted.
  • The database has no title property — point at a database rather than a plain page.