# Fix Docusaurus "MDX compilation failed" unexpected character errors

## TL;DR

MDX treats curly braces as JavaScript expressions, so a literal { or } in prose (or one unclosed code fence) breaks parsing at the reported line. Wrap literal braces in code spans or escape them as {'{'}  {'}'} style expressions, close the fence, then rebuild. The file compiles because the parser no longer sees stray expression syntax.

## The error

```text
[MDXCompilationError] Docusaurus MDX loader failed to parse markdown content in docs/guide.md:
Unexpected character `{` (1:42)
```

## Steps

1. Read the error: it names the file and the exact line and column of the offending character.
   Expected: you can point at the specific character in the source file.

2. Fix the character: wrap literal braces in backtick code spans, or escape them as MDX expressions like {'{'} and {'}'}. Bare braces only survive inside code spans, fenced code blocks, or real JSX expressions.
   Expected: no bare curly braces remain in prose.

3. Check for an unclosed code fence above the error line: one missing closing fence makes the rest of the file parse as code and the error surfaces far from the real problem. Count the fences.
   Expected: every opening fence has a matching closing fence.

4. Rebuild: `npm run build`.
   Expected: MDX compiles the file and the build continues past it.

## Use this when

- MDXCompilationError naming a file, line, and column
- docs showing JSON snippets or template syntax with literal braces
- a page that broke right after a code block was edited

## Not for this skill when

- 'broken markdown link' (the file parses fine; a link target is wrong)
- 'plugin not found' (dependency/config problem)
- a blank page with no build error (rendering problem, not a parse problem)

## Variant phrasings

- docusaurus MDX compilation failed
- docusaurus unexpected character MDX
- docusaurus could not parse markdown content
- mdx loader failed docusaurus curly brace

## Why it happens

Docusaurus pages are MDX, which is Markdown plus JSX: the compiler scans prose for { } expression boundaries and JSX-style tags. A literal brace in normal text - common in JSON examples, config snippets, or template placeholders - opens an expression the parser cannot close, so it reports an unexpected character. An unclosed code fence is the sneakier variant: everything after it is treated as code until the next fence, and the parse error lands far from the missing fence.

## Edge cases

- import and export statements are only allowed at the top of an MDX file; one buried mid-page throws a different MDX error.
- JSX-style tags in prose must be valid or wrapped in code spans; an unclosed tag swallows the following paragraphs.
- If a page needs lots of literal braces, prefer a fenced code block over inline escapes - it is easier to read and cannot break parsing.

## Provenance

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