Create Your First MDX File

Time to write some MDX. You're going to create a file from scratch, drop a couple of React components into it, and see it render in the browser. By the end of this page, you'll get how MDX actually works in practice.

What You'll Build

We're making a simple page that has:

Normal Markdown text (headings, paragraphs, lists)
A custom React component rendered right in the middle of it
An interactive counter with buttons that work
Some styled content using JSX

Nothing fancy — just enough to see the pieces fit together.

Step 2: Create Your First MDX File

Make a new file at app/hello/page.mdx (App Router) or pages/hello.mdx (Pages Router).

File Structure

Here's what your project looks like now:

my-mdx-project/ ├── app/ │ ├── hello/ │ │ └── page.mdx ← Your first MDX file! │ ├── layout.js │ └── page.js ├── components/ │ ├── Greeting.jsx ← Custom component │ └── Counter.jsx ← Interactive component ├── next.config.mjs └── package.json

The MDX File Content

Here's what goes in app/hello/page.mdx:

Example

# Hello, MDX World! 🎉 Welcome to your **first MDX file**. This is regular Markdown, but watch what happens when we add React components below. ## This is Markdown Everything you know about Markdown works here: - **Bold text** and *italic text* - [Links](https://mdxjs.com) work perfectly - Lists, blockquotes, and code blocks all work > MDX is a superset of Markdown — all valid Markdown is valid MDX! ## Now, Here's the Magic ✨ Below this paragraph, we're importing and using a real React component right inside our Markdown content: import Greeting from '../../components/Greeting'; <Greeting name="Developer" /> ## Adding Interactivity We can even add interactive components: import Counter from '../../components/Counter'; <Counter initialCount={0} /> ## Mixing Markdown and JSX You can weave between Markdown and JSX smoothly. This paragraph is Markdown, and right below it is a styled JSX div: <div style={{ padding: '1rem', backgroundColor: '#f0f9ff', borderRadius: '8px', border: '1px solid #0ea5e9' }}> <strong>🎨 This is JSX!</strong> You can use inline styles, className, and all the React features you're used to. </div> And now we're back to regular Markdown again. Simple as that! --- ## Summary You just learned that MDX lets you: 1. Write standard Markdown content 2. Import React components 3. Use those components inline with your text 4. Mix and match freely throughout the file

Look at that — imports and JSX right in the middle of Markdown. That's the whole idea.

Step 3: Create the React Components

Now let's build the two components we imported.

Greeting Component

Create components/Greeting.jsx:

jsx example

export default function Greeting({ name }) {
  return (
    <div style={{
      padding: '1.5rem',
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      borderRadius: '12px',
      color: 'white',
      fontSize: '1.25rem',
      textAlign: 'center',
      margin: '1rem 0',
    }}>
      <h3 style={{ margin: 0 }}>👋 Hello, {name}!</h3>
      <p style={{ margin: '0.5rem 0 0' }}>
        Welcome to the world of MDX. This component was rendered
        from inside a Markdown file!
      </p>
    </div>
  );
}

Counter Component

Create components/Counter.jsx:

Example

'use client'; import { useState } from 'react'; export default function Counter({ initialCount = 0 }) { const [count, setCount] = useState(initialCount); return ( <div style={{ padding: '1.5rem', border: '2px solid #e2e8f0', borderRadius: '12px', textAlign: 'center', margin: '1rem 0', }}> <p style={{ fontSize: '2rem', margin: '0 0 1rem' }}> Count: <strong>{count}</strong> </p> <div style={{ display: 'flex', gap: '0.5rem', justifyContent: 'center' }}> <button onClick={() => setCount(count - 1)} style={{ padding: '0.5rem 1rem', fontSize: '1rem', borderRadius: '6px', border: '1px solid #cbd5e1', cursor: 'pointer', }} > - Decrease </button> <button onClick={() => setCount(count + 1)} style={{ padding: '0.5rem 1rem', fontSize: '1rem', borderRadius: '6px', border: 'none', backgroundColor: '#3b82f6', color: 'white', cursor: 'pointer', }} > + Increase </button> </div> </div> ); }

⚠️ Warning: That 'use client' at the top of Counter.jsx is required in the App Router. Without it, useState and click handlers won't work — server components can't do interactivity.

Step 4: Run Your Project

Fire up the dev server:

bash example

npm run dev

Then open your browser to:

Example

http://localhost:3000/hello

Step 5: Understanding the Output

Here's what you'll see on that page:

The Markdown — headings, paragraphs, lists, all rendered as normal HTML
The Greeting component — a purple gradient card saying hello
The Counter — buttons that actually increment and decrement a number
The inline JSX div — a styled blue box

What happened behind the scenes? The MDX compiler took your .mdx file and turned the whole thing into a React component. Markdown became HTML elements. Your imports and JSX rendered just like they would in any .jsx file.

How MDX Compilation Works

Here's the short version of what happens when you save that .mdx file:

The compiler:

Parses your Markdown into an AST (Abstract Syntax Tree)
Finds the JSX and import statements
Wraps everything into a single React component
Exports it as the default export

So your MDX file basically becomes this behind the scenes:

jsx example

import Greeting from '../../components/Greeting';
import Counter from '../../components/Counter';

export default function MDXContent() {
  return (
    <>
      <h1>Hello, MDX World! 🎉</h1>
      <p>Welcome to your <strong>first MDX file</strong>...</p>
      {/* ... more HTML elements from Markdown ... */}
      <Greeting name="Developer" />
      <Counter initialCount={0} />
      {/* ... rest of content ... */}
    </>
  );
}

Quick Experiments to Try

Now that it's working, mess around with it:

1. Change Component Props

mdx example

<Greeting name="World" />
<Counter initialCount={10} />

2. Use JavaScript Expressions

mdx example

The current year is {new Date().getFullYear()}.

Here's a calculated value: {2 + 2 === 4 ? '✅ Math works!' : '❌ Uh oh'}

3. Export Variables

mdx example

export const metadata = {
  title: 'My MDX Page',
  date: '2024-01-15',
};

# {metadata.title}

Published on {metadata.date}.

Common Beginner Mistakes

Forgetting Blank Lines Around JSX

MDX needs blank lines to tell where Markdown stops and JSX starts:

mdx example

{/* ❌ Wrong — no blank lines */}
Some text
<MyComponent />
More text

{/* ✅ Correct — blank lines separate Markdown from JSX */}
Some text

<MyComponent />

More text

Using Curly Braces in Regular Text

Curly braces mean "JavaScript expression" in MDX. If you want literal braces in your text, escape them:

mdx example

{/* ❌ This will be interpreted as a JS expression */}
The object has keys {name, age}

{/* ✅ Escape curly braces with backslash or use code */}
The object has keys \{name, age\}
The object has keys `{name, age}`

Summary

You just built your first MDX file. Here's what you now know:

MDX files use .mdx and mix Markdown with JSX
Import statements bring React components into your content
Components render inline — right between your paragraphs
Interactive components need 'use client' in the App Router
JavaScript expressions go in curly braces {}
The MDX compiler turns the whole file into a normal React component

Next up: how to organize your MDX project so it doesn't become a mess as it grows.

What You'll Build

We're making a simple page that has:

Normal Markdown text (headings, paragraphs, lists)
A custom React component rendered right in the middle of it
An interactive counter with buttons that work
Some styled content using JSX

Nothing fancy — just enough to see the pieces fit together.

Step 2: Create Your First MDX File

Make a new file at app/hello/page.mdx (App Router) or pages/hello.mdx (Pages Router).

File Structure

Here's what your project looks like now:

The MDX File Content

Here's what goes in app/hello/page.mdx:

Example

Look at that — imports and JSX right in the middle of Markdown. That's the whole idea.

Step 3: Create the React Components

Now let's build the two components we imported.

Greeting Component

Create components/Greeting.jsx:

jsx example

export default function Greeting({ name }) {
  return (
    <div style={{
      padding: '1.5rem',
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      borderRadius: '12px',
      color: 'white',
      fontSize: '1.25rem',
      textAlign: 'center',
      margin: '1rem 0',
    }}>
      <h3 style={{ margin: 0 }}>👋 Hello, {name}!</h3>
      <p style={{ margin: '0.5rem 0 0' }}>
        Welcome to the world of MDX. This component was rendered
        from inside a Markdown file!
      </p>
    </div>
  );
}

Counter Component

Create components/Counter.jsx:

Example

⚠️ Warning: That 'use client' at the top of Counter.jsx is required in the App Router. Without it, useState and click handlers won't work — server components can't do interactivity.

Step 4: Run Your Project

Fire up the dev server:

bash example

npm run dev

Then open your browser to:

Example

http://localhost:3000/hello

Step 5: Understanding the Output

Here's what you'll see on that page:

The Markdown — headings, paragraphs, lists, all rendered as normal HTML
The Greeting component — a purple gradient card saying hello
The Counter — buttons that actually increment and decrement a number
The inline JSX div — a styled blue box

How MDX Compilation Works

Here's the short version of what happens when you save that .mdx file:

The compiler:

Parses your Markdown into an AST (Abstract Syntax Tree)
Finds the JSX and import statements
Wraps everything into a single React component
Exports it as the default export

So your MDX file basically becomes this behind the scenes:

jsx example

import Greeting from '../../components/Greeting';
import Counter from '../../components/Counter';

export default function MDXContent() {
  return (
    <>
      <h1>Hello, MDX World! 🎉</h1>
      <p>Welcome to your <strong>first MDX file</strong>...</p>
      {/* ... more HTML elements from Markdown ... */}
      <Greeting name="Developer" />
      <Counter initialCount={0} />
      {/* ... rest of content ... */}
    </>
  );
}

Quick Experiments to Try

Now that it's working, mess around with it:

1. Change Component Props

mdx example

<Greeting name="World" />
<Counter initialCount={10} />

2. Use JavaScript Expressions

mdx example

The current year is {new Date().getFullYear()}.

Here's a calculated value: {2 + 2 === 4 ? '✅ Math works!' : '❌ Uh oh'}

3. Export Variables

mdx example

export const metadata = {
  title: 'My MDX Page',
  date: '2024-01-15',
};

# {metadata.title}

Published on {metadata.date}.

Common Beginner Mistakes

Forgetting Blank Lines Around JSX

MDX needs blank lines to tell where Markdown stops and JSX starts:

mdx example

{/* ❌ Wrong — no blank lines */}
Some text
<MyComponent />
More text

{/* ✅ Correct — blank lines separate Markdown from JSX */}
Some text

<MyComponent />

More text

Using Curly Braces in Regular Text

Curly braces mean "JavaScript expression" in MDX. If you want literal braces in your text, escape them:

mdx example

{/* ❌ This will be interpreted as a JS expression */}
The object has keys {name, age}

{/* ✅ Escape curly braces with backslash or use code */}
The object has keys \{name, age\}
The object has keys `{name, age}`

Summary

You just built your first MDX file. Here's what you now know:

MDX files use .mdx and mix Markdown with JSX
Import statements bring React components into your content
Components render inline — right between your paragraphs
Interactive components need 'use client' in the App Router
JavaScript expressions go in curly braces {}
The MDX compiler turns the whole file into a normal React component

Next up: how to organize your MDX project so it doesn't become a mess as it grows.

Create Your First MDX File

What You'll Build

Step 2: Create Your First MDX File

File Structure

The MDX File Content

Step 3: Create the React Components

Greeting Component

Counter Component

Step 4: Run Your Project

Step 5: Understanding the Output

How MDX Compilation Works

Quick Experiments to Try

1. Change Component Props

2. Use JavaScript Expressions

3. Export Variables

Common Beginner Mistakes

Forgetting Blank Lines Around JSX

Using Curly Braces in Regular Text

Summary

Continue learning this concept

Create Your First MDX File

What You'll Build

Step 2: Create Your First MDX File

File Structure

The MDX File Content

Step 3: Create the React Components

Greeting Component

Counter Component

Step 4: Run Your Project

Step 5: Understanding the Output

How MDX Compilation Works

Quick Experiments to Try

1. Change Component Props

2. Use JavaScript Expressions

3. Export Variables

Common Beginner Mistakes

Forgetting Blank Lines Around JSX

Using Curly Braces in Regular Text

Summary

Continue learning this concept