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.

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