Publishing Model

Publishing Model

The docs workflow should favor review, repeatability, and traceability over instant publish.

Recommended flow

1. A writer updates a page in the Notion docs database.
2. The page is marked as publishable through metadata such as Status = Published.
3. A local script or scheduled GitHub Action runs the Notion sync.
4. The sync script converts the page into MDX, downloads assets, and rewrites internal links.
5. If generated content changed, automation opens or updates a pull request.
6. The team reviews both the content and the generated output.
7. Merging the PR deploys the site.

Why not publish directly from Notion

Direct runtime reads from Notion make the docs site harder to test and harder to trust:

• a broken Notion block can break production without review
• expiring asset URLs can create unstable pages
• content changes are harder to diff and roll back
• page titles can accidentally alter URLs if slugs are not explicit

Operating principle

The GitHub pull request is the editorial checkpoint. Notion makes writing pleasant, but the repository makes publishing safe.