MDX Features Showcase: Complete Guide

This post demonstrates every feature available in MDX, from basic markdown to advanced component imports and interactive elements.

What is MDX?

MDX is Markdown for the component era. It lets you write JSX embedded inside markdown. That’s a powerful combination that allows you to:

• Use React/Astro components in your content
• Create interactive documentation
• Build dynamic blog posts
• Embed visualizations and charts

---

Table of Contents

1. Text Formatting
2. Headings and Structure
3. Lists
4. Links and Images
5. Code Blocks
6. Tables
7. Blockquotes
8. Component Imports
9. Advanced Features

---

Text Formatting

Basic Formatting

You can use bold text, italic text, bold and italic, strikethrough, and inline code.

Subscript and Superscript

You can write H2O for chemical formulas or E=mc^2^ for equations.

Keyboard Keys

Press Ctrl + C to copy and Ctrl + V to paste.

Highlighting

This is ==highlighted text== for emphasis.

---

Headings and Structure

MDX supports all markdown heading levels:

# Heading 1 (Reserved for page title)

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Rendered examples:

Heading 2 Example

Heading 3 Example

Heading 4 Example

Heading 5 Example

Heading 6 Example

---

Lists

Unordered Lists

• Item one
• Item two
  • Nested item 2.1
  • Nested item 2.2
    • Double nested item
• Item three

Ordered Lists

1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

Task Lists

• Complete MDX setup
• Write blog posts
• Add more features
• Test on production

Definition Lists

Term 1 : Definition of term 1

Term 2 : First definition of term 2 : Second definition of term 2

---

Links and Images

Links

• External link: Visit Cloudflare
• Internal link: Go to Blog
• Email link: Contact us
• Reference link: CloudTodo

Images

Figure 1: Beautiful productivity workspace

---

Code Blocks

Inline Code

Use the console.log() function to debug your code.

JavaScript/TypeScript

// JavaScript example with syntax highlighting
async function fetchTodos(userId) {
  const response = await fetch(`/api/todos?userId=${userId}`);
  const data = await response.json();
  return data.todos;
}

// ES6+ features
const todos = await fetchTodos(123);
const completed = todos.filter((t) => t.status === "completed");
console.log(`You have ${completed.length} completed tasks!`);

TypeScript with Types

interface Todo {
  id: number;
  title: string;
  status: "pending" | "in_progress" | "completed";
  priority: "low" | "medium" | "high";
  createdAt: Date;
  userId: number;
}

class TodoManager {
  private todos: Todo[] = [];

  addTodo(todo: Omit<Todo, "id" | "createdAt">): Todo {
    const newTodo: Todo = {
      ...todo,
      id: this.todos.length + 1,
      createdAt: new Date(),
    };
    this.todos.push(newTodo);
    return newTodo;
  }

  getTodosByPriority(priority: Todo["priority"]): Todo[] {
    return this.todos.filter((t) => t.priority === priority);
  }
}

SQL Queries

-- Get all todos for a user with statistics
SELECT
  u.id,
  u.name,
  COUNT(t.id) as total_todos,
  SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END) as completed_todos,
  AVG(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END) * 100 as completion_rate
FROM users u
LEFT JOIN todos t ON u.id = t.user_id
WHERE u.created_at >= DATE('now', '-30 days')
GROUP BY u.id, u.name
HAVING COUNT(t.id) > 0
ORDER BY completion_rate DESC
LIMIT 10;

Shell Commands

# Install dependencies
npm install @astrojs/mdx

# Start development server
npm run dev

# Build for production
npm run build && npm run deploy

# Database migrations
npm run db:generate
npm run db:push
npm run db:migrate:prod

Python

# Python example
class TodoAnalyzer:
    def __init__(self, todos):
        self.todos = todos

    def get_productivity_score(self):
        """Calculate productivity score based on completion rate"""
        if not self.todos:
            return 0

        completed = sum(1 for t in self.todos if t['status'] == 'completed')
        return (completed / len(self.todos)) * 100

    def suggest_priorities(self):
        """AI-powered priority suggestions"""
        urgent = [t for t in self.todos if t['due_date'] < datetime.now()]
        return sorted(urgent, key=lambda x: x['importance'], reverse=True)

JSON

{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "[email protected]",
    "plan": "pro",
    "settings": {
      "theme": "dark",
      "notifications": true,
      "timezone": "America/New_York"
    }
  },
  "todos": [
    {
      "id": 1,
      "title": "Complete project proposal",
      "status": "in_progress",
      "priority": "high",
      "tags": ["work", "urgent"]
    }
  ]
}

Code with Line Numbers and Highlighting

// Line 1 is highlighted
const API_URL = "https://api.cloudtodo.app";
// Lines 3-5 are highlighted
async function createTodo(title, priority) {
  return await fetch(`${API_URL}/todos`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    // Line 8 is highlighted
    body: JSON.stringify({ title, priority }),
  });
}

Diff Syntax

  function calculateTotal(items) {
-   return items.reduce((sum, item) => sum + item.price, 0);
+   return items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
  }

+ // New feature: Apply discount
+ function applyDiscount(total, discountPercent) {
+   return total * (1 - discountPercent / 100);
+ }

---

Tables

Basic Table

Feature	Free	Pro	Enterprise
Tasks	100	Unlimited	Unlimited
Storage	10 MB	1 GB	100 GB
Team Members	1	10	Unlimited
Support	Community	Email	Priority + Phone
Price	$0/mo	$9/mo	Custom

Alignment Options

Left Aligned	Center Aligned	Right Aligned
Text	Text	Text
More text	More text	More text
Even more	Even more	Even more

Complex Table with Formatting

Metric	Q1 2026	Q2 2026	Change	Status
Active Users	10,000	15,000	+50%	✅ Growing
Revenue	$45K	$67K	+49%	✅ On Track
Churn Rate	5%	3%	-40%	✅ Improved
NPS Score	45	58	+29%	✅ Excellent

Comparison Table

Aspect	Traditional Apps	CloudTodo
Deployment	Complex server setup	One-click deploy
Scaling	Manual provisioning	Auto-scales globally
Latency	150ms+ from distant servers	<50ms worldwide
Cost	$1000+/month	$10/month
Maintenance	High, requires DevOps	Zero, fully managed

---

Blockquotes

Simple Blockquote

“The best time to plant a tree was 20 years ago. The second best time is now.”

Nested Blockquotes

This is a top-level quote.

This is a nested quote.

And this is a double-nested quote!

Blockquote with Attribution

Productivity isn’t about time management. It’s about attention management.

— CloudTodo Team, 2026

Alert-Style Blockquotes

💡 Pro Tip: Use keyboard shortcuts to speed up your workflow. Press ? to see all available shortcuts.

⚠️ Warning: Always backup your data before performing destructive operations.

✅ Success: Your changes have been saved automatically.

ℹ️ Info: CloudTodo runs on Cloudflare’s global network with 275+ locations worldwide.

---

Component Imports

Using Astro Components in MDX

You can import and use Astro components directly in your MDX content!

Custom JSX Elements

You can write inline JSX directly in MDX:

Interactive Elements

Click to expand: How does CloudTodo achieve 15ms latency?

CloudTodo leverages Cloudflare’s edge network with 275+ data centers worldwide. When you make a request, it’s handled by the nearest edge location, resulting in dramatically reduced latency compared to traditional centralized servers.

---

Advanced Features

Footnotes

Here’s a sentence with a footnote¹. And here’s another one².

Horizontal Rules

You can create horizontal rules in multiple ways:

---

---

---

Escaped Characters

Use backslash to escape special characters: * _ # [ ] ( )

HTML Entities

© 2026 CloudTodo | ™ | ® | ♥ | ♣

Emoji Support

🚀 Rocket | 📝 Note | ✅ Check | ❌ Cross | 🎉 Party | 💡 Idea | ⚡ Lightning | 🔥 Fire

Math Expressions (if supported)

The quadratic formula: x = (-b ± √(b² - 4ac)) / 2a

Abbreviations

The HTML specification is maintained by the W3C.

_[HTML]: HyperText Markup Language _[W3C]: World Wide Web Consortium

---

Code Features Comparison

Let’s compare different approaches to the same problem:

Approach 1: Callback Hell ❌

// Old way: Callback hell
fetchUser(userId, (user) => {
  fetchTodos(user.id, (todos) => {
    fetchStats(todos, (stats) => {
      renderDashboard(user, todos, stats);
    });
  });
});

Approach 2: Promises ✅

// Better: Promises
fetchUser(userId)
  .then((user) => fetchTodos(user.id))
  .then((todos) => fetchStats(todos))
  .then((stats) => renderDashboard(stats))
  .catch((error) => handleError(error));

Approach 3: Async/Await ✨

// Best: Async/Await
async function loadDashboard(userId) {
  try {
    const user = await fetchUser(userId);
    const todos = await fetchTodos(user.id);
    const stats = await fetchStats(todos);
    renderDashboard(user, todos, stats);
  } catch (error) {
    handleError(error);
  }
}

---

Performance Metrics Table

Operation	Traditional Server	CloudTodo (Edge)	Improvement
Cold Start	500ms - 2s	0ms (always warm)	∞
API Response	150ms - 500ms	15ms - 45ms	10x faster
Page Load	2s - 5s	300ms - 800ms	6x faster
Database Query	50ms - 200ms	5ms - 15ms	10x faster
Global Reach	Single region	275+ locations	Global

---

Feature Checklist

What You’ve Learned

• Text formatting (bold, italic, strikethrough)
• Headings and document structure
• Lists (ordered, unordered, task lists)
• Links and images
• Code blocks with syntax highlighting
• Tables with alignment
• Blockquotes and nested quotes
• Component imports
• Inline JSX elements
• Custom styled components
• Interactive elements
• Footnotes
• HTML entities and emoji
• Diff syntax
• Math expressions

---

Real-World Example: API Documentation

Authentication Endpoint

Endpoint: POST /api/auth/login

Request Body:

{
  "email": "[email protected]",
  "otp": "123456"
}

Response (Success):

{
  "success": true,
  "user": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpc2lzYXJlZnJlc2h0b2tlbg=="
}

Response (Error):

{
  "success": false,
  "error": "Invalid OTP",
  "code": "AUTH_INVALID_OTP"
}

Status Codes:

Code	Meaning
200	Success
400	Invalid request
401	Invalid credentials
429	Rate limit exceeded
500	Server error

---

Conclusion

This showcase demonstrates the incredible flexibility of MDX. You can:

1. Write beautiful documentation with rich formatting
2. Embed live components for interactive content
3. Mix markdown and JSX seamlessly
4. Create engaging blog posts with custom styling
5. Build dynamic content that’s both readable and powerful

---

This guide was created to help you understand all the possibilities with MDX. Experiment, create, and build amazing content!

Questions? Reach out at [email protected]

Footnotes

1. This is the first footnote with additional context and links. ↩

2. This is the second footnote explaining something important. ↩