docs agent failed parsing jsx in mdx examples

Not specified by the original author.

TL;DR

Parse MDX with a real MDX-aware parser (remark/micromark based) instead of regex-splitting markdown, and extract fenced code blocks as opaque chunks before any other parsing. Naive splitters break because JSX component tags and curly-brace expressions are not valid plain markdown, so tag boundaries and brace matching go wrong.

The error

docs agent failed parsing jsx in mdx examples

Steps to fix

1. Reproduce: run the agent's parser on the failing .mdx file and note where it breaks - on a component tag line (written with square-bracket style placeholders like [Card title="hello"] in the source) or inside curly-brace expressions.

   • Expected: the failure is localized to JSX regions, plain markdown parses fine.

2. Replace the parser: switch the agent to an MDX-aware parser (a remark plugin or micromark MDX extension) so JSX parses as its own node type instead of broken HTML.

   • Expected: the failing file parses with JSX nodes correctly identified.

3. Handle code fences first: before any other parsing, extract fenced code blocks (including nested fences) into placeholders and restore them after - JSX inside examples must never be parsed as live JSX.

   • Expected: example code comes back byte-identical to the source.

4. Re-run the parser over all .mdx files in the repo.

   • Expected: zero parse errors and no mangled component regions.

Use this when

• A docs agent reads .mdx files and fails or mangles pages containing JSX examples.
• The agent splits markdown with regexes or a markdown-only parser.
• Example code blocks contain JSX that must be preserved exactly.

Not for this skill when

• The MDX site build itself fails (that's a Docusaurus/Next config problem).
• The files are plain .md with no JSX (a markdown-only parser is fine there).
• The issue is the agent generating bad JSX, not parsing it.

Variant phrasings

• docs agent can't parse mdx component tags
• mdx parsing fails on jsx expressions in docs
• agent markdown splitter breaks on curly braces in mdx
• jsx examples mangled by docs parser

Why it happens

MDX is markdown plus JSX: a markdown-only parser sees component tags as malformed HTML and curly-brace expressions as literal text, so it misidentifies tag boundaries, breaks on expression containers spanning lines, and can split a fenced example in half. Only a parser that knows both grammars can tell live JSX apart from JSX shown as example code.

Edge cases

• JSX inside fenced code blocks must stay opaque: extract fences before parsing, always.
• Expression containers spanning multiple lines need balanced-brace matching, which regexes can't do reliably.
• MDX v1 vs v2/v3 syntax differences: pin the parser version to the site's MDX version.
• Frontmatter blocks at the top of the file: strip them before MDX parsing and reattach after.

Provenance

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

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

Thread query: docs agent failed parsing jsx in mdx examples

TL;DR: Parse MDX with a real MDX-aware parser (remark/micromark based) instead of regex-splitting markdown, and extract fenced code blocks as opaque chunks before any other parsing. Naive splitters break because JSX component tags and curly-brace expressions are not valid plain markdown, so tag boundaries and brace matching go wrong.

Not specified by the original author.

TL;DR

Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Error

Error: MDX compilation failed: Expected corresponding JSX closing tag

Steps

1. Read the MDX error; it names the file and line with the unclosed tag. Expected: the offending line located.
2. If the tag was meant as a component, add its closing tag. If it was prose (e.g. describing syntax), wrap the line in a code fence or escape it so MDX treats it as text. Expected: MDX no longer parses it as a component.
3. Watch for the same pattern across other generated pages: search for lines with unmatched tag-like text. Expected: no sibling pages with the same flaw.
4. Rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX compilation fails on an unclosed or unexpected tag
• A docs agent wrote prose containing tag-like text
• Code samples were pasted as prose instead of fenced blocks

When not to use

• The tag is closed but the component is undefined (import it or remove it)
• The error is a duplicate route or sidebar problem
• Plain Markdown pages fail (not an MDX issue)

Tool compatibility

Docusaurus 2.x and 3.x MDX handling. The rule is the same in both.

Variant phrasings

MDX error on a code sample showing HTML

Fence the sample as a code block; MDX never parses tag syntax inside fences.

agent keeps generating unclosed tags

Add a lint step (e.g. an MDX check) to the agent's write loop before the build.

Why it happens

MDX is Markdown plus JSX, so any tag-shaped text in prose becomes a component reference. Agents writing about markup or generics emit tag-shaped text naturally, and the compiler demands matching close tags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Thread query: docs agent's docusaurus build broke on unclosed MDX tag

TL;DR: Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Not specified by the original author.

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.