## 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
```text
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