publish where your site already lives
Connect Notion to PilotDeck
Connect Notion to PilotDeck with OAuth or an internal integration token, pick a database and publish approved articles as pages.
What connecting Notion does#
PilotDeck researches, drafts and queues content for review. A CMS connection is the last hop: once you approve a draft, PilotDeck sends it to your CMS for you. With Notion, each approved article becomes a new page in a Notion database that you choose. The example below uses a PilotDeck site named pilotdeck-testwebsite and your workspace.
Sign in with Notion
The default path is an OAuth sign-in through the Authenticate with Notion button. Notion shows its own consent screen and you pick which databases to share. There is nothing to paste.
You choose the database
PilotDeck never creates a database. It publishes into one you already have, and only into databases you shared with it.
Pages, not a website
Notion is a workspace, not a public site. Pages are created inside your database and PilotDeck does not publish them to the web.
Before you start#
| You need | Details |
|---|---|
| A Notion workspace with a database | A table or board database in your workspace. It needs a title column, which every Notion database has. PilotDeck cannot create the database for you. |
| Optional columns | A multi-select column for tags, a text column for the meta description, and a text or select column named like Author, Writer or Byline. Each is optional, see Property mapping. |
| A Notion login | Permission in your workspace to share the database with an integration. |
| A PilotDeck login | Permission to change integrations for the site. Without it the connect controls are unavailable. |
Overview#
- 1Create or pick the Notion database you want to publish intoYou
- 2Open Settings > Integrations in PilotDeck and pick NotionYou
- 3Click Authenticate with Notion and select the databases to share on Notion's consent screenYou
- 4Return to PilotDeck. We list the databases you sharedPilotDeck
- 5Choose the target database, add an optional category and click ConfirmYou
- 6Send a test draft and check the page in NotionVerify
If your PilotDeck server has no Notion sign-in configured, the Notion form asks for an internal integration token instead. See Connect with an internal integration token.
In your workspace, open the database you want PilotDeck to publish into, or create a new table database. Keep its title column. Add the optional columns from Before you start if you want tags, a meta description or an author name filled in.
In PilotDeck, make sure the correct site is selected in the top-left site switcher (here, pilotdeck-testwebsite). Go to Settings > Integrations and find the CMS Connection card. With nothing connected it reads "No CMS connected".
Click the Notion tile. The Notion panel opens with a Connect Notion heading and an Authenticate with Notion button.
Click Authenticate with Notion. Your browser goes to Notion's own screen, Connect with the PilotDeck app. It lists what the app can do: view, edit and create content in the pages you select, and view workspace users and their emails. Check the workspace in the top right, then click Select pages.
On the page picker, tick the page or teamspace that holds your database, then click Allow access. Sharing a page also shares the databases inside it: in the test for this guide, ticking the teamspace home made the blog table inside it available.
Notion sends you back to PilotDeck. PilotDeck saves the connection under your workspace name. Connecting the same workspace again refreshes the existing connection instead of adding a duplicate.
A Finish setup panel appears with a Choose a database list. It holds every database you shared. Pick one.
- Select the database in Choose a database.
- Optionally type a Category. It is applied to every post sent through this connection. In Notion it lands in the database's multi-select column (see Property mapping).
- Click Confirm. The connection card turns green with an ACTIVE badge.
If the list says no databases were found, none was selected during authorization. Reconnect and pick one on Notion's screen.
On the connected card, click Send test draft. You see "Test draft created." with a view link when Notion returns the page address. Open the database in Notion and look for the new page.
Connect with an internal integration token#
This path is shown when Notion sign-in is not configured on your PilotDeck server. The Notion panel then shows a note that OAuth is not configured and a manual form instead of the Authenticate with Notion button.
- In Notion, create an internal integration for your workspace and copy its secret. Notion shows the secret as a long string. Keep it private.
- Open the target database in Notion, open its ... menu, choose Connections and add your integration. An integration can only see databases shared with it.
- In PilotDeck, open Settings > Integrations, click Notion and paste the secret into Internal Integration Secret (shown as
<your-integration-token>in these docs). The field shows dots. - Optionally set a Category and pick a Publish mode. The publish mode has no effect for Notion, see Publish behaviour.
- Click Test connection. You should see "Looks good, credentials work." Then click Connect.
Property mapping#
Notion has no blog post type. A page is a set of properties plus content blocks. PilotDeck reads your database's columns each time it publishes and maps the article onto them.
| Article field | Goes to | Notes |
|---|---|---|
| Title | The database's title column | Required. If the database has no title column, publishing fails with a validation error. |
| Tags and category | A multi-select column | Prefers a column whose name contains tag, topic or categor. Your connection category is added as a tag. Each name is cut to 100 characters. Skipped when there is no multi-select column. |
| Meta description | A text column | Prefers a column named like summary, meta, desc or excerpt. Cut to 2000 characters. Skipped when there is no text column. |
| Author name | A text or select column named like Author, Writer or Byline | People columns are left alone. When no such column exists, an author box closes the page body instead. |
| Featured image | The page cover | Set from the image web address, no upload. If Notion rejects the address, the page is created without a cover. |
| Article body | Page blocks | See What converts to Notion blocks. |
Other columns in your database, including a status column, are not filled in. They stay empty on new pages.
What converts to Notion blocks#
PilotDeck writes articles as HTML and converts them to Notion blocks. The converter handles the common elements the content generator produces.
| In the article | In Notion |
|---|---|
| Headings 1 to 3 | Heading 1, 2 and 3 blocks |
| Headings 4 to 6 | Heading 3 blocks |
| Paragraphs | Paragraph blocks |
| Bulleted and numbered lists | Bulleted and numbered list items |
| Quotes | Quote blocks |
| Images with a full http or https address | Image blocks, with the alt text as the caption |
| FAQ and conclusion | Added as visible blocks at the end |
| Author details | A short box at the end, with links printed as plain addresses |
Long text is split to fit Notion's 2000 character limit per text run. Pages with more than 100 blocks are created with the first 100 and the rest are appended in batches, paced to stay under Notion's request limit.
Publish behaviour#
Notion has no draft or published state in this flow, and PilotDeck does not publish pages to the web. The Draft only and Publish live modes make no difference: both create the page, and it is visible to anyone in your workspace who can see that database.
| Behaviour | Detail |
|---|---|
| Page address | PilotDeck stores the Notion page address that Notion returns, which opens the page inside Notion. |
| Updates | Each approval creates a new page. PilotDeck does not update a page it created earlier. |
| Scheduling and media upload | Not supported. |
| SEO and structured data | Not written. Notion pages are not a public SEO surface. |
Disconnecting#
On the connected card click Disconnect and confirm. Approved content stops publishing to Notion right away. Pages already created stay in your database. To reconnect, repeat the steps above. To fully remove access, also remove the integration's connection from the database or workspace in Notion.
Troubleshooting#
No databases found after authenticating
You did not select a database on Notion's consent screen. Disconnect if needed, click Authenticate with Notion again and select at least one database.
The sign-in returns with an error
PilotDeck shows the reason with "(notion)" after it, for example when you cancel on Notion's screen. Try again. If your server shows that OAuth is not configured, use the internal integration token form.
Test connection says no database is shared
The integration has no database. In Notion, open the database, open its ... menu, choose Connections and add the integration. Then test again.
Publishing fails with a validation error
The database may have no title column, or a column was changed. Notion answers with 400 or 422 in that case. Check that the database still has a title column and was not replaced.
Publishing fails with an authorization error
A 401 means the token is invalid or revoked. A 403 means the integration lacks permission. A 404 means the database is no longer shared. Reconnect, and share the database again if needed.
Publishing fails with a rate limit or server error
Notion answers 429 when requests come too fast and 5xx on its own errors. Wait a moment and retry.
Tags, meta description or author are missing
Those fields only fill when the database has a matching column type. Add a multi-select column for tags, a text column for the meta description, and a text or select column named like Author. See Property mapping.
Formatting or a table is missing in the page
The converter keeps headings, paragraphs, lists, quotes and images only. Bold, links and tables are flattened or dropped. See What converts to Notion blocks.
The cover image is missing
Notion rejected the image address, so the page was created without a cover. Check that the featured image uses a public https address.
The Draft and Live choice does nothing
That is expected. Notion has no draft state here, so every page is created the same way. See Publish behaviour.