MDX Cheatsheet

What is MDX?

MDX lets you write JSX in Markdown. It blends the simplicity of Markdown with the power of React components. You can embed custom UI, interactivity, and dynamic content directly inside your .mdx files.

MDX is great for:

• Documentation
• Developer blogs
• Component previews
• Interactive examples

Basic Syntax

MDX supports standard Markdown:

# Heading 1
 
## Heading 2
 
- Lists
- Like
- These
 
**Bold**, _Italic_, and `Inline code`
 
> Blockquotes work too

Frontmatter

MDX supports YAML frontmatter at the top of the file for metadata:

---
title: My Post
description: This is a description.
tags: ["mdx", "blog"]
published: true
date: 2025-07-16
---

This is often used in blogs or documentation systems to generate pages with dynamic content.

Rehype Pretty Code

rehype-pretty-code is a Rehype plugin powered by shiki. It enables syntax highlighting at build time, resulting in faster page loads and consistent styles across themes.

npm install rehype-pretty-code

Features

• VS Code theme support (dark/light mode aware)
• Line highlighting and line numbers
• Word-level highlights
• Diff indicators (++, --)

Code Highlights

import { useFloating } from "@floating-ui/react";
 
function MyComponent() {
  const { refs, floatingStyles } = useFloating(); // [!code highlight]
 
  return (
    <>
      // [!code highlight:2]
      <div ref={refs.setReference} />
      <div ref={refs.setFloating} style={floatingStyles} />
    </>
  );
}

Code Diffs

radius = 2 # [!code --]
radius = 5 # [!code ++]
area = math.pi * radius**2 
print(area)

Word Highlights

// [!code word:console:2]
console.log("1");
console.log("2");
console.log("3");
console.log("4");

Code Block Annotations

With rehype-pretty-code, you can annotate code in several ways:

You can also combine multiple annotations into 1 (one).

Custom Components

MDX allows embedding React components directly:

import Alert from "@/components/Alert";
 
<Alert type="info">This is an info alert with **markdown** inside!</Alert>

Use this to create reusable UI for documentation:

• Note, Warning, Callout
• Tabs, Accordion, VideoPlayer, etc.
• Interactive playgrounds with live code

Custom Styling

Tailwind CSS or any other CSS framework can be applied by wrapping content in styled components or using prose classes.

Example with a custom Note:

<Note title="Heads up!">
  You can use `rehype-pretty-code` for beautiful code blocks.
</Note>

Or wrap content with Tailwind's typography styles:

<div className="prose prose-zinc dark:prose-invert">{children}</div>

Embedding Media

You can embed images, iframes, and videos like normal HTML:

<img src="/images/demo.png" alt="Demo" width="600" />
 
<iframe
  allow="accelerometer *; camera *; encrypted-media *; geolocation *; microphone *"
  style={{ width: "100%", height: 400 }}
  src="https://codesandbox.io/embed/new"
/>

Velite Collections

For complex MDX systems, consider using:

• Velite - Type-safe content system for Next.js
• Remark - Plugin that turn your HTML into Markdown

These tools let you:

• Query MDX content like a database
• Add custom rehype/remark plugins
• Automatically type MDX frontmatter and metadata

Summary

MDX lets you write Markdown with embedded components, code highlighting, and React interactivity — all while maintaining readability and performance. Whether you're building a blog, docs site, or design system, MDX gives you the tools to scale content and code together.

• Image by Nahid Hatami