Notion is a great writing surface but doesn't render a public blog on its own. Tools like Super.so, Potion, and Feather.so turn a Notion database into a public site. Mentionwell pushes articles into that database; those tools render them.
What you need
- A Notion workspace.
- A database to receive articles (we'll set up the schema).
- An internal integration token.
Setup
1. Create the integration
- Go to notion.so/my-integrations.
- New integration → choose Internal → workspace.
- Capabilities: enable Read content, Update content, Insert content.
- Copy the Internal Integration Secret — this is your Notion token.
2. Set up the database
Create a Notion database with these properties (names must match exactly, types must match):
| Property name | Type |
|---|---|
| Title | Title |
| Slug | Text |
| Excerpt | Text |
| Published | Date |
| Tags | Multi-select |
| Category | Select |
| Cover URL | URL |
| Status | Status |
3. Invite the integration to the database
Open the database as a full page → click ... in the top right → Connections → Add connections → pick your Mentionwell integration. Without this step every API call returns 401.
4. Hand the credentials to Mentionwell
- Integration token — the secret you copied above.
- Database ID — copy it from the database URL:
notion.so/<workspace>/<DATABASE_ID>?v=...(a 32-character hex string).
What gets pushed
| Mentionwell field | Notion location |
|---|---|
| Title | Title property |
| Slug, excerpt | Slug, Excerpt properties |
| Tags, category, published date | Tags, Category, Published properties |
| Featured image | Cover URL property |
| Article body | Page content as native Notion blocks (heading, paragraph, list, image, quote, code) |
| Status | Status property — set to Published |
The body is converted from Markdown to Notion blocks via @tryfabric/martian so headings, lists, images, and code blocks render cleanly inside Notion.
Caveats
- No raw HTML. Notion's API only accepts block JSON. Mentionwell converts; some custom HTML (like callout cards) will fall back to plain paragraphs.
- No JSON-LD. Notion strips it. Super.so / Feather handle SEO metadata separately — surface it via their own settings.
- 100 blocks per request. Long articles are appended in batches.
- Images must be public URLs (Notion proxies them when viewed).
- Don't edit articles in Notion. If Mentionwell updates the same article later, your Notion edits get overwritten. Treat Notion as a sync target, not a primary editor.
Common failures
- 401 Unauthorized — the integration was not invited to the database. Re-check Connections.
- 400 Invalid property — property name or type doesn't match the schema above.
- 429 — exceeded ~3 req/sec. Mentionwell retries with backoff.
Reference: developers.notion.com.