Notion Sync

The sync script should live in this repository as ordinary application code, not as opaque workflow logic.

Responsibilities

query the Notion database for pages eligible to publish
fetch page blocks recursively
convert blocks to Markdown or MDX
add frontmatter required by Starlight
rewrite internal page links to local doc routes
mirror remote assets into the repo-controlled public directory
delete generated pages that no longer exist upstream
validate the output before CI opens a pull request

Recommended implementation

Use @notionhq/client to talk to the API and notion-to-md as the conversion baseline. Expect to add custom transforms for callouts, tables, asset handling, and page-link rewriting.

Output target

Write generated documents into apps/web/src/content/docs and mirrored assets into apps/web/public/docs-assets.

This keeps the Starlight app self-contained and ensures the production deployment does not depend on live Notion URLs.