šŸ“˜ MDX Tutorial ā€“ Write JSX Inside Markdown

šŸš€ What is MDX?

MDX is an extension of Markdown that allows you to useJSX components directly inside your Markdown files.

It combines the simplicity of Markdown with the power of React components, making it perfect for documentation websites, blogs, portfolios, and learning platforms.

>>"MDX = Markdown + JSX"

āœØ Why Use MDX?

  • šŸ“ Write content using Markdown.
  • āš›ļø Embed React components directly.
  • šŸ“Š Add charts, alerts, tabs, and custom UI.
  • šŸ“š Perfect for documentation.
  • šŸš€ Used by Docusaurus, Next.js, Astro, Gatsby, and many more.

šŸ“¦ Installing MDX

For a React Project

Install MDX

npm install @mdx-js/react @mdx-js/loader @mdx-js/mdx

šŸ“„ Your First MDX File

Create a file named:

hello.mdx

hello.mdx

# Hello World

This is **Markdown**.

<button>Click Me</button>

Everything above is valid MDX.

šŸ“ Markdown Features

Headings

Headings

# Heading 1
## Heading 2
### Heading 3

Bold & Italic

Formatting

**Bold**

*Italic*

~~Strikethrough~~

Lists

Lists

- Apple
- Mango
- Orange

1. Learn
2. Build
3. Deploy

Links

Links

[OpenAI](https://openai.com)

Images

Images

![Logo](/logo.png)

āš›ļø Using React Components

The biggest feature of MDX is embedding React components.

Alert.jsx

export default function Alert({children}) {
  return (
    <div style={{background:"#ffeeba",padding:20}}>
      {children}
    </div>
  );
}

Using Alert

import Alert from "./Alert"

# Welcome

<Alert>
This is an alert box.
</Alert>

šŸ“„ Passing Props

Props Example

<Button
  color="blue"
  text="Click Here"
/>

šŸŽÆ JavaScript Expressions

You can use JavaScript inside curly braces.

Expressions

export const name = "John"

# Hello {name}

The value is {10 + 5}.

šŸ“¦ Importing Components

Import Example

import Card from "./Card"

<Card title="MDX">
Learning MDX is fun.
</Card>

šŸ“ Typical Project Structure

Folder Structure

project/

ā”œā”€ā”€ components/
ā”‚   ā”œā”€ā”€ Alert.jsx
ā”‚   ā””ā”€ā”€ Card.jsx
ā”‚
ā”œā”€ā”€ docs/
ā”‚   ā”œā”€ā”€ intro.mdx
ā”‚   ā””ā”€ā”€ guide.mdx
ā”‚
ā””ā”€ā”€ package.json

šŸŒ MDX in Next.js

Install

npm install @next/mdx

next.config.js

const withMDX = require('@next/mdx')()

module.exports = withMDX({
  pageExtensions: ['js','jsx','md','mdx'],
})

šŸ“š MDX in Docusaurus

Docusaurus uses MDX by default. Simply create:

docs/tutorial.mdx

and start writing Markdown mixed with React components.

šŸ”„ MDX Components Example

Multiple Components

import Card from "./Card"
import Alert from "./Alert"

# Dashboard

<Alert>
Important update!
</Alert>

<Card title="Users">
1500 Active Users
</Card>

šŸ’” Advantages

  • āš” Easy to write.
  • āš›ļø Full React support.
  • šŸ“š Great for documentation.
  • šŸŽØ Beautiful UI using components.
  • šŸ“ˆ Reusable content blocks.

āš ļø Limitations

  • Requires a build setup.
  • Needs JSX knowledge.
  • Can become harder to read if overloaded with components.

Note

šŸ’” Use Markdown for content and React components only when interactive or reusable UI is needed. This keeps your MDX files clean and maintainable.

šŸŽÆ Best Practices

  1. Keep Markdown simple.
  2. Reuse components instead of repeating markup.
  3. Organize components in a dedicated folder.
  4. Prefer small, focused components.
  5. Use syntax highlighting for code blocks.

šŸ“– Quick Cheat Sheet

FeatureSyntax
Heading# Hello
Bold**Bold**
Italic*Italic*
List- Item
Link[Text](URL)
Image![Alt](image.png)
Component<Alert />
Importimport Card from "./Card"
JavaScript{2 + 2}

šŸ”— Learn More

For the official documentation, visit:

MDX Official Documentation
>>šŸš€ MDX empowers developers to create rich, interactive documentation by blending the readability of Markdown with the flexibility of React components.