docs agent failed: generated mdx files fail docusaurus build on nested braces

TL;DR

Put brace-heavy content inside fenced code blocks or escape the braces. MDX treats braces as expression delimiters, so JSON and code with nested braces break compilation as prose.

Error

Error: MDX compilation failed: Unexpected token (nested braces in generated content)

Steps

1. Find the failing line from the MDX error; it will contain nested braces outside a code fence. Expected: the offending content located.
2. Wrap the content in a fenced code block with a language tag. Inside fences, MDX leaves braces alone. Expected: the content is fenced.
3. If the braces must appear in prose (rare), escape each one so the compiler treats it as text. Expected: no raw nested braces in prose.
4. Fix the agent's generator to fence code and JSON output by default, then rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX fails on nested braces in generated pages
• A docs agent pastes JSON or code as prose
• The error points at expression-like content

When not to use

• The braces are a deliberate JSX expression with a syntax error (fix the expression)
• The failure is an unclosed tag (different MDX error)
• The content is already fenced but still fails (check the fence itself)

Tool compatibility

Docusaurus 2.x and 3.x MDX. Fenced code is verbatim in both.

Variant phrasings

agent generates API examples with JSON bodies

Template the generator to always fence JSON examples; it is the highest-volume trigger.

braces fail inside a table cell

Fenced blocks do not work in table cells; use inline code or restructure the table.

Why it happens

MDX inherits JSX expression syntax, so braces are meaningful outside code spans. Agents generating API docs emit JSON naturally as prose, and the compiler reads the braces as expressions.

Provenance

Resolved from the public thread: https://vectle.com/posts/psttACmR9MNSVPbnReXdgERQ

Resolved from the public thread: https://vectle.com/posts/psttACmR9MNSVPbnReXdgERQ

Thread query: docs agent failed: generated mdx files fail docusaurus build on nested braces

TL;DR: Put brace-heavy content inside fenced code blocks or escape the braces. MDX treats braces as expression delimiters, so JSON and code with nested braces break compilation as prose.