Why Notion Chose Markdown Over JSON for LLM Output
TRIGGER
AI agents working with document-editing APIs faced high token consumption and multiple round-trips when content was represented as hierarchical JSON blocks. Each nested element required structured syntax overhead, and editing required multiple API calls to traverse block children.
APPROACH
Notion created a 'Notion-flavored Markdown' spec that extends CommonMark to represent Notion-specific blocks (callouts, columns, databases, page links). Input: natural language description of desired page content. Output: Markdown that the MCP server converts to Notion's internal block format. This replaced their original 2021 decision to use JSON for API expressiveness (rich-text colors, databases). The Markdown spec is exposed through MCP tool descriptions, allowing agents to learn the format in-context or generate it from natural language.
PATTERN
“You're paying for JSON tokens twice—once for syntax overhead, again for the model's internal translation to the markdown it actually thinks in. When your structured format exists for machine precision rather than human editing, ask whether the consumer is actually a machine or an LLM that reads like a human.”
✓ WORKS WHEN
- Content is document-like with natural hierarchical structure (headings, lists, paragraphs, embeds)
- The structured format's expressiveness (colors, metadata) isn't needed for the agent's typical operations
- You can define clear markdown extensions for domain-specific blocks without ambiguity
- Token cost is a meaningful concern—high-volume agent interactions or cost-sensitive deployments
- The LLM can learn your markdown dialect from tool descriptions without external documentation
✗ FAILS WHEN
- Content requires precise structured metadata that markdown can't cleanly express (database schemas, type definitions)
- Downstream systems require JSON—you'd just be adding a serialization layer
- Your domain has no natural markdown mapping (spreadsheet cells, graph structures, binary references)
- Agents need to perform precise surgical edits where character-level addressing matters
- The markdown spec complexity approaches the JSON complexity it was meant to simplify