Publishing from Notion

Linkfor renders Notion pages live — we don't copy your content into our database, we fetch it from Notion every time a visitor hits the URL (with smart caching at the edge so it's fast). For that to work, the page has to be published to web so the unauthenticated Notion public API can read it.

This page covers the publish flow, the URL format we accept, and the list of block types we render today.

1. Make the page public in Notion

Open the page in Notion. Click Share in the top right, then Publish to web. Confirm the toggle is on.

Notion gives you a public URL like:

https://www.notion.so/Your-Page-Title-3e1d7c8b1f4a4c5e9b6e7a8b9c0d1e2f

The trailing 32-character hex string is the page ID. Linkfor accepts either form when you add the route — paste the full URL, the bare ID, or the dashed-UUID form.

2. Add a Notion route

In the dashboard, open the site's Routes tab and Add route. Pick type notion, paste the URL or page ID, and click Validate. We hit the Notion API to confirm the page is reachable and grab the title for display in the dashboard.

If validation fails:

• Page is not public — go back to Notion and confirm Publish to web is on, not just Share with link.
• Page not found — the ID is wrong, or the page was moved / deleted.

3. Permitted block types

These block types render cleanly today:

• Headings (H1, H2, H3)
• Paragraphs (with inline formatting: bold, italic, strikethrough, code, links, color)
• Bulleted and numbered lists
• To-do checkboxes
• Toggles
• Callouts
• Quotes
• Dividers
• Code blocks (syntax-highlighted via Prism — language picker matters)
• Tables
• Columns
• Images (Notion-hosted or unsplash.com)
• Videos (Notion-hosted or YouTube / Vimeo embeds)
• Files and PDFs
• Math equations (KaTeX)
• Tweet embeds (when enabled in Settings → Features)
• Bookmarks
• Sub-pages (when also published to web)

These render with reduced fidelity:

• Synced blocks — the content shows up, but real-time sync isn't guaranteed (we cache the record map for ~30 seconds at the edge).
• Database views — table, gallery, and list views render read-only. Calendar, board, and timeline views fall back to a list.

These don't render:

• Forms — Notion's form blocks require their own auth flow.
• AI blocks — non-deterministic output, opt-in only on Notion's side.
• Comments and discussions — private to the workspace.
• Page mentions to private pages — they show up as broken links.

4. Updating the page

Edit in Notion as normal. Linkfor keeps the rendered record map in a stale-while-revalidate Redis cache:

• Fresh window (0 – 10 min): the cached copy is served and no background fetch is triggered.
• Stale window (10 – 60 min): the cached copy is served immediately and a background fetch refreshes it for the next visitor.
• Expired (> 60 min or missing): Linkfor fetches Notion synchronously before responding — this is the only case where a slow Notion API response adds latency for a visitor.

In practice, edits are visible within ten minutes without any action on your part. There's nothing to redeploy and no cache to bust manually.

If you need an instant invalidation (e.g. removing legally-sensitive content), the dashboard's Settings → Cache panel has a Purge button that drops the cached record map immediately, forcing the next request to fetch fresh from Notion.

5. URL format quirks

We accept all of these as input when you add a route:

https://www.notion.so/Your-Page-Title-3e1d7c8b1f4a4c5e9b6e7a8b9c0d1e2f
https://yourworkspace.notion.site/Your-Page-Title-3e1d7c8b1f4a4c5e9b6e7a8b9c0d1e2f
3e1d7c8b1f4a4c5e9b6e7a8b9c0d1e2f
3e1d7c8b-1f4a-4c5e-9b6e-7a8b9c0d1e2f

We don't accept private workspace URLs (/myworkspace/) — those require workspace-level auth that Linkfor never holds.

The rootNotionPageId and rootNotionSpaceId fields

When you add a Notion route at /, that page's ID becomes the site's root Notion page ID — the anchor that the renderer uses to build the site map (the hierarchy of sub-pages reachable from the root).

A related optional field, rootNotionSpaceId, tells the renderer which workspace the root page belongs to. It is used as an access guard: if a fetched page belongs to a different workspace than the one configured, the renderer refuses to display it.

The key gotcha: workspace-level pages are not enumerable through Notion's public API without rootNotionSpaceId. If your root Notion page is a top-level workspace page (not a nested child page), the site map builder can't walk its children without the space ID. Set it in Settings → General using the 32-character hex ID visible in your Notion workspace URL.

For most users — where the root page is an ordinary nested page shared to web — this field can be left blank.

Performance notes

Notion's public API is rate-limited per page. Linkfor uses a stale-while-revalidate cache layer (Redis SWR, fresh for 10 min / stale up to 60 min) so a single page-view burst doesn't hammer Notion. A page that gets, say, 10k requests an hour against Linkfor maps to approximately 6 actual Notion fetches an hour — well below any rate-limit threshold.