Is this a full MDX compiler?
No. It is a fast browser-side checker for the handful of mistakes that most often break a docs build. A clean result here is a good sign, not a guarantee that MDX will compile.
MDX Validator
Find common MDX syntax issues before publishing docs.
Line 3: MDX JSX uses className instead of class.
Replace class= with className=.
Line 3: Brace expressions inside Markdown/JSX need deliberate MDX syntax.
Escape literal braces as \{ and \}, or make the expression valid JSX.
Line 5: HTML comments can break MDX parsing.
Use JSX comments: {/* comment */}.
How to Use
- Paste an
.mdxfile — or Markdown you are about to rename to.mdx— into the left pane - Read the issue list on the right; each entry gives the line number and a concrete fix
- Apply the fixes in your editor, then paste again until the pane reports no issues
Why Valid Markdown Can Still Break MDX
MDX looks like Markdown with components mixed in, but it compiles as JSX. That means markup a Markdown renderer happily accepts can fail the build the moment the file becomes .mdx — and the resulting error usually points at a line number rather than explaining the rule. These are the four mismatches that account for most of those failures:
classinstead ofclassName— JSX usesclassName; the HTML spelling is not carried through- HTML comments —
<!-- ... -->is not valid JSX, so use{/* ... */} - Unescaped braces —
{opens a JavaScript expression, so a literal brace must be written\{ - Unclosed JSX tags — Markdown tolerates a stray
<div>; JSX requires every element to be closed or self-closing
What this checker deliberately does not do
It is not a compiler. It will not resolve imports, type-check props, or evaluate expressions, and it will not catch a component that is used but never imported. What it does is give you an instant read on the mechanical syntax problems, before you push a commit and wait on a docs build to tell you the same thing. Everything runs locally in your browser.
Frequently Asked Questions
Does it ignore code fences?
Yes. Fenced code blocks are skipped, so example JSX or HTML inside triple backticks is never reported as page syntax. YAML frontmatter delimiters are skipped too.
Why does MDX reject the class attribute?
MDX compiles JSX, and in JSX the attribute is className. Writing class= works in plain Markdown-with-HTML but is dropped or errors once the file is treated as MDX.
What is wrong with HTML comments in MDX?
An HTML comment is not valid JSX, so it can break parsing depending on where it appears. Use a JSX comment inside braces instead: {/* comment */}.
Why is a brace expression flagged?
In MDX, curly braces open a JavaScript expression. A literal brace next to JSX is ambiguous, so it needs to be escaped as \{ and \} or written as a valid expression.
Is my MDX uploaded?
No. Validation runs entirely in your browser and your draft is autosaved only to this browser local storage.