Concepts
Why not MDX?
MDX embeds components. Content Blocks defines a content protocol.
MDX is excellent when trusted developers want arbitrary JSX inside content.
Content Blocks solves a different problem:
- content may be generated by LLMs
- content may be localized or edited in a CMS
- content should remain Markdown-shaped and portable
- authors should not need React or JSX knowledge
- teams want validation before render
- teams want renderer choice instead of React lock-in
MDX embeds components. Content Blocks defines a content protocol.
Use MDX when
- authors are developers
- content lives close to app code
- arbitrary React power is desired
- build-time JSX execution is acceptable
Use Content Blocks when
- content is generated, imported, translated, or CMS-managed
- strict block schemas matter
- line-level content errors are valuable
- content should render outside React
- LLMs or agent skills need clear authoring instructions
The practical differences
| MDX | Content Blocks | |
|---|---|---|
| Authoring surface | JSX + Markdown | Markdown + constrained directives |
| Validation | None (compile errors at best) | Schemas with file:line:col diagnostics |
| Execution | Compiles to JS, runs code | Never executes code |
| Render targets | React | React, static HTML, plain Markdown |
| Safe for LLM output | Risky | Designed for it |
A document written with Content Blocks stays readable in any plain-text editor and degrades gracefully: strip the renderer and the content still makes sense as Markdown.
The system can interoperate with MDX later (an MDX plugin or renderer is on the roadmap), but it does not depend on MDX as the primary model.