Debugging MDX Errors

When you’re writing content in Flowershow, most of the time Markdown “just works.” But if you start using MDX — which lets you include JSX blocks, e.g. Flowershow components like <List> — you might run into error messages like this one:

Unexpected character `'` in attribute name

Don’t worry — you didn’t break anything.

It just means MDX needs a clearer hint about what you’re trying to do.

This guide walks you through what the most common MDX errors actually mean — in plain language — and how to fix them.

Why does MDX error sometimes?

Markdown treats everything as text.

MDX is Markdown plus the ability to write JSX inside your content.

So when MDX sees:

<Something>

it assumes you’re trying to use a component — just like you would in React.

That’s powerful, but it also means MDX needs to interpret things more strictly than Markdown. Sometimes it gets confused and needs us to be explicit.

Most common errors

"Unexpected character 'x' in attribute name"

Plain English explanation:

You probably used < in your writing as a normal character — for math, notation, or emphasis — but MDX thought you were trying to create a component.

Example — you meant to write math or notation:

The set <a, b> has two members

But MDX sees <a and thinks:

“Oh, the user is trying to create a JSX component called <a… but , or other symbols appeared before a valid attribute name.”

So it panics and shows this error.

✅ Fix: escape literal angle brackets

If you’re not trying to use a component, escape < and >:

The set \<a, b\>; has two members

or like this:

The set <a, b> has two members

or add some spaces:

The set < a, b > has two members

or wrap the entire expression in backticks:

The set `<a, b>` has two members

Both tell MDX: “Relax, it’s just text.”

“Expected closing tag” / “Unterminated tag”

Plain English explanation:

MDX saw something like <div> and expected you to eventually write </div>, but never saw it.

Or you meant to make it self-closing but forgot />.

For example:

<div className="text-red">
This is useful information

MDX keeps scanning the file waiting for </div> — and never finds it.

Fix

Close the tag:

<div className="text-red">
This is useful information
</div>

Or if it’s just a standalone component:

<List />

“xyz is not defined”

Plain English explanation:

Anything inside {…} in MDX is treated as JavaScript, not text.

So if MDX sees {word}, it tries to evaluate it — and errors if it’s not valid JS (e.g. word variable is not defined).

This often happens when you’re trying to literally show something in braces, like set notation:

{a, b, c}

MDX thinks you’re trying to run JavaScript and says:

“I don’t know what a is!”

Fix

Tell MDX it’s not code, just text:

Option A — wrap in backticks:

`{a, b, c}`

Option B — escape braces:

{a, b, c}

MDX rendering errors

Sometimes your MDX content will parse correctly but still fail when the page tries to render it.

In plain English:

The file is valid MDX, but something inside the JSX / JavaScript part crashed when the page tried to run it.

This is different from syntax errors like unclosed tags — these are runtime errors.

A common example:

You reference a value that doesn’t exist:

{a}

To MDX/React, {a} means “take the variable a and render its value here.” If a isn’t defined anywhere, the page tries to run that code and crashes.

Fix

Escape the curly brackets:

\{a\}

or wrap in backticks:

`{a}`

When does this happen?

Any time MDX thinks you’re writing JavaScript, but you actually meant text, for example:

• Set notation / math
• Curly braces used for emphasis

Other things that can cause MDX to fail at render time

Besides undefined values like {a}, runtime MDX errors can also happen if:

• An unknown component is used (e.g. <Something/>)
• Your JavaScript expression inside {} throws an error (e.g. const = 2)

Disabling MDX rendering

Flowershow is designed to feel like writing in a modern digital notebook — where you can write normal Markdown and, when you want, sprinkle in JSX blocks styled with Tailwind or add interactive components like:

<List dir="blog" />

That’s why Flowershow parses all files as MDX by default.

It means you can always use components without having to rename files or remember a special syntax.

But here’s the good news:

If you’re writing simple Markdown (like a blog or notes), and MDX feels extra or confusing, you can tell Flowershow to skip MDX entirely and treat everything as plain Markdown.

Just update your config.json:

{
  "markdownRenderer": "md"
}

Now your site behaves just like a classic Markdown blog — no MDX parsing, no JSX rules, no angle bracket surprises.

Want the best of both worlds?

If you sometimes want MDX but also want regular .md files to stay simple, use:

{
  "markdownRenderer": "auto"
}

This means .md files will be parsed as plain Markdown, but .mdx files will be parsed as MDX. So you can choose per file, naturally.

Summary

Still stuck? We’re here to help!

If you ran into an error that isn’t covered here — or something just doesn’t make sense — we’d love to help you out.

• ✅ Leave a comment below
• ✅ Or ask a question in our Flowershow Discord community
• ✅ Share a snippet of what you were trying — we genuinely enjoy debugging with users!