MDX for Beginners: Write Content Like a Developer
Muhammad Bilal Azhar
Co-Founder & Technical Lead · Google Cloud Certified Professional
MDX for Beginners: Write Content Like a Developer
If you're migrating from WordPress to a static site, you'll encounter MDX. It sounds technical, but it's actually simpler than WordPress's block editor once you understand it.
This guide teaches you MDX from scratch.
What Is MDX?
MDX = MarkDown + JSX
It's Markdown that lets you use React components. Best of both worlds:
- Markdown's simplicity for writing
- React's power for interactive elements
Start with Markdown
Before MDX, you need Markdown. It's a way to write formatted text using simple symbols.
Basic Syntax
This is a Heading 1
This is a Heading 2
This is a Heading 3
Regular paragraph text. You can make text bold or italic.
- Bullet point 1
- Bullet point 2
- Bullet point 3
1. Numbered item
2. Another item
3. Third item
What It Produces
This is a Heading 1
This is a Heading 2
This is a Heading 3
Regular paragraph text. You can make text bold or italic.
- Bullet point 1
- Bullet point 2
- Bullet point 3
Quick Reference
| Element | Markdown | Result |
| Bold | text | text |
| Italic | text | text |
| Link | text | text |
| Image | !alt | Image displayed |
| Code | ` code | code |
| Heading | # text | Heading |
| Quote | > text | Blockquote |
MDX Adds Components
Here's where MDX shines. You can use React components inside your Markdown:
My Blog Post
Regular Markdown content here.
This is a custom callout component!
More Markdown content...
And you can keep writing in Markdown.
The components (Callout, VideoEmbed) are React components you define once and use anywhere.
Frontmatter: Your Post's Metadata
MDX files start with frontmatter—YAML data between --- marks:
------title: "My Amazing Blog Post"
date: "2026-02-05"
author: "Jane Doe"
excerpt: "A short preview of your post"
tags: ["react", "tutorial"]
featuredImage: "/images/hero.jpg"
My Amazing Blog Post
Content starts after the second
Frontmatter is like WordPress post settings:
- title → Post title
- date → Publish date
- author → Author name
- excerpt → Post excerpt/description
- tags → Categories/tags
- featuredImage → Featured image
Your website code reads this data to display posts correctly.
Code Blocks
One of Markdown/MDX's best features—beautiful code formatting:
function greet(name) {
return Hello, ${name}!;
}
console.log(greet('World'));
Renders as:
function greet(name) {
return
Hello, ${name}!;
}
console.log(greet('World'));
Supports any language:
javascript, python, html, css, bash, etc.
Creating Custom Components
This is MDX's superpower. Create a component once, use it everywhere.
Example: Custom Callout
Define the component:
// components/Callout.jsx
export function Callout({ type = 'info', children }) {
const styles = {
info: 'bg-blue-100 border-blue-500',
warning: 'bg-yellow-100 border-yellow-500',
error: 'bg-red-100 border-red-500',
};
return (
p-4 border-l-4 ${styles[type]}}>
{children}
);
}
Use it in any MDX file:
Important: Back up your data before proceeding!
More Component Ideas
Component Purpose
Embed a tweet
Embed YouTube video
Interactive code demo
Product comparison
Collapsible sections
Email signup form
Related articles
MDX vs WordPress Blocks
WordPress Block Editor
- Visual, click-and-drag
- Blocks stored as weird HTML comments
- Hard to version control
- Vendor-specific format
MDX
- Text-based, keyboard-friendly
- Clean, readable source files
- Perfect for Git version control
- Standard format, works anywhere
Example: Same Content
WordPress block output:
Welcome
Hello world!
MDX:
Welcome
Hello world!
MDX is dramatically cleaner.
Common MDX Patterns
1. Import and Use Components
import { Button } from '../components/Button'
Get Started
Click below to begin:
2. Pass Props to Components
plan="pro"
annual={true}
features={['Feature 1', 'Feature 2']}
/>
3. Use JavaScript Expressions
export const year = new Date().getFullYear()
Copyright © {year} My Company
4. Combine Markdown and Components
Note: You can use Markdown inside components too!
- List item 1
- List item 2
File Organization
Typical MDX content structure:
content/
├── blog/
│ ├── my-first-post.mdx
│ ├── second-post.mdx
│ └── third-post.mdx
├── docs/
│ ├── getting-started.mdx
│ └── api-reference.mdx
└── pages/
├── about.mdx
└── contact.mdx
Each
.mdx file becomes a page on your site.
MDX Setup in Next.js
Quick setup overview:
1. Install Dependencies
npm install @next/mdx @mdx-js/loader @mdx-js/react
2. Configure next.config.js
import createMDX from '@next/mdx'
const withMDX = createMDX({
extension: /\.mdx?$/,
})
export default withMDX({
pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
})
3. Create MDX Content
// app/blog/my-post.mdx
title: "My First MDX Post"
Hello MDX!
This is my first post using MDX.
Tips for WordPress Migrants
1. Think in Files, Not Database
Each post = one
.mdx file. No database.
2. Use Frontmatter for Settings
Everything you'd set in WordPress sidebar goes in frontmatter.
3. Replace Shortcodes with Components
WordPress:
[gallery ids="1,2,3"]
MDX:
4. Images Go in Public Folder
public/
├── images/
│ ├── hero.jpg
│ └── thumbnail.png
Reference as
/images/hero.jpg` in your MDX.
5. Version Control Everything
Every change is tracked in Git. Undo mistakes, see history, collaborate easily.
Migrating WordPress Content to MDX
Our tool converts WordPress posts to MDX automatically:
WordPress HTML:
Introduction
Welcome to my blog post.
- Point one
- Point two
Converted MDX:
---
title: "My Blog Post"
date: "2026-01-15"
Introduction
Welcome to my blog post.
- Point one
- Point two
FAQ
Q: Do I need to know React to use MDX?
Not for basic usage. Write Markdown as usual. Components are optional extras.
Q: Can non-developers use MDX?
Yes, though there's a learning curve. Alternatively, use a headless CMS that writes MDX for you.
Q: How is MDX different from regular Markdown?
MDX adds the ability to import and use React components. Regular Markdown is text-only.
Q: Can I preview my MDX while writing?
Yes! Many editors (VS Code, Obsidian) have MDX preview. Or run your dev server for live preview.
Q: What framework works best with MDX?
Next.js and Astro both have excellent MDX support out of the box.
Conclusion
MDX might seem intimidating at first, but it's actually simpler than WordPress's block editor:
- Plain text files you can read and edit anywhere
- Markdown for writing - just text with simple formatting
- Components for power - reusable, interactive elements
- Git-friendly - version control built-in
Start with basic Markdown. Add components as you need them. You'll wonder why you ever used WordPress's visual editor.
Related guides:
Related Articles
View allGit for WordPress Developers: Getting Started
Learn Git version control coming from WordPress. Track changes, collaborate, and never lose work again.
TypeScript for JavaScript Developers: A Practical Guide
Learn TypeScript to write safer code. Types, interfaces, and practical patterns that make JavaScript development better.
Tailwind CSS for WordPress Developers: Complete Guide
Learn Tailwind CSS coming from WordPress. Utility-first CSS explained for theme developers making the switch to modern frameworks.
React vs Vue vs Svelte for WordPress Developers
Confused by JavaScript frameworks? This guide explains React, Vue, and Svelte from a WordPress developer's perspective.