Preview: Notion-flavored Markdown with markdown_version
By Steven Van ·
Enhanced markdown remains the default, and the opt-in v2 preview does not yet support include_transcript.
Developers can opt into Notion’s new Markdown format by setting the optional markdown_version parameter to v2 on markdown endpoints. The preview supports reading and writing Notion-flavored Markdown, while v1, enhanced markdown, remains the default. Requests without the parameter continue to work as before.
A format for Notion content
Notion-flavored Markdown combines CommonMark with GFM tables, task lists and strikethrough, plus syntax for custom emoji, math and Notion-specific XML tags. Those tags represent content such as callouts, columns, mentions and synced blocks. The format reference shares its specification with the Notion MCP server and is written for AI agents.
Preview limits and validation
v2 does not yet support include_transcript, and synchronous v2 updates return parser warnings. Sending markdown_version without markdown on POST /v1/pages or the comment endpoints returns a 400 validation_error.