Why Do I Need MDX? From Static Documents to Interactive Applications

MDXReactAstroTech Stack

Table of Contents

This article itself is rendered by MDX.

We often ask: “If Markdown can already do so much, why introduce MDX?”

The answer lies in this: Markdown is for ‘reading’, MDX is for ‘interacting’.

Below, I’ll demonstrate the differences directly on this page.

1. Static vs Dynamic

Plain Markdown (Static)

Plain Markdown is great for displaying code, lists, and text. It’s static—readers can only view it.

// This is just static code
const greet = "Hello World";
console.log(greet);

MDX (Dynamic)

But in MDX, I can embed a living React component. Try clicking the buttons below:

Current count: 0

👆 What just happened?

This isn’t a GIF, nor an embedded iframe. This is React code (with State) running directly on this page. A plain .md file can never achieve this.

2. Passing Parameters (Props)

The most powerful aspect of MDX is that we can pass data to components just like writing HTML. This makes maintaining repetitive UI incredibly simple.

For example, I’ve defined a <Callout /> component, and I can freely change its title and style:

💡Core Concept

MDX treats articles as Data, but also treats articles as a Component Tree.

⚠️Warning: Complexity Reminder

While powerful, remember: if you don’t need interactivity, stick with plain Markdown to keep your build lightweight.

✨Pro Tip

You can mix Markdown syntax and React components in MDX—they coexist perfectly.

3. Data-Driven Content

Suppose I’m writing a team introduction document. In plain Markdown, I’d have to hand-write HTML tables. But in MDX, I can reuse components:

A

Alice

Frontend Engineer

B

Bob

Product Designer

C

Charlie

DevOps

D

Diana

Backend Engineer

This means your Design System can work directly in your blog posts.

4. Dynamic Calculations

MDX can also execute JavaScript logic. For example, showing how many days until a certain date:

Days until 2030

1490 days

This number is calculated in real-time—it updates every time you reload the page. This is completely impossible in plain Markdown.

When Should You Use MDX?

Let’s return to the initial decision point:

RequirementRecommendation
Pure text + images + code✅ Use .md
Mermaid diagrams✅ Use .md + remark plugin
Chart.js / ECharts✅ Use .md + global scripts
Embedded interactive components🔥 Use .mdx
Passing Props to components🔥 Use .mdx
Dynamic content calculations🔥 Use .mdx

Analogy Summary

“When using Markdown, you’re writing an article; when using MDX, you’re writing an application.”

  • Markdown is a “printed book”—information is static, written once
  • MDX is an “interactive e-book”—readers can operate and experience

If you just want to “display”—then stick with Markdown. It’s lighter, faster, and simpler.

Only when you truly need to “make parts of your article move, connect to APIs, manage state”—then open the door to MDX.

Conclusion

This article itself is the best proof:

  1. ✅ You saw an interactive counter
  2. ✅ You saw configurable callout boxes
  3. ✅ You saw data-driven user cards
  4. ✅ You saw dynamically calculated dates

These are all things only MDX can do.

But remember: with great power comes great responsibility. Don’t use MDX just to show off—only use it when you truly need interactivity.