ww-notion-docs

The problem: Notion’s block editor doesn’t speak standard markdown, and it fails quietly. A pipe table just doesn’t render. An escaped \n shows up as a literal backslash-n instead of a line break. Curly braces meant to set a block color turn into visible text if they’re escaped wrong. None of it throws an error. You just find out later, when you look at the live page and something’s broken.

This documents Notion’s actual markdown flavor (HTML

tags instead of pipes, tags, {color="yellow_bg"} for backgrounds, for the vertical space Notion otherwise strips) plus the update patterns that keep an edit from silently failing: always fetch the page before update_content, since a stale old_str just won’t match, and default to update_content over replace_content, since a full rewrite destroys whatever a reviewer already left on the page. The other half is the comments-based review cycle itself: comments aren’t optional decoration, they’re the only way a reviewer can see what changed without re-reading the whole document, so every content update gets one, anchored to the exact text it touched.

Key principles

Fetch before you edit, always; a stale old_str fails silently, not loudly
Default to update_content; replace_content blows away everything already on the page, including reviewer edits
Newlines have to be real newlines; an escaped \n renders as literal text
Every change gets a comment anchored to it; without one, the reviewer has to re-read the whole document to find what moved
Set a real icon on every page you create; Notion’s default blank icon is not a real default

Part of Operator Skills, a collection of skills for running a real Claude Code setup.