MDX Cheatsheet
14 May 2025

Salman Alfarisi
Fullstack Engineer
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:
Frontmatter
MDX supports YAML frontmatter at the top of the file for metadata:
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.
Features
- VS Code theme support (dark/light mode aware)
- Line highlighting and line numbers
- Word-level highlights
- Diff indicators (
++
,--
)
Code Highlights
Code Diffs
Word Highlights
Code Block Annotations
With rehype-pretty-code
, you can annotate code in several ways:
Syntax | Effect |
---|---|
[!code highlight] | Highlights a line |
[!code highlight:n] | Highlights a line in range(n) |
[!code ++] | Shows as added in diff mode |
[!code --] | Shows as removed in diff mode |
[!code word:X] | Highlights the word X |
[!code word:X:n] | Highlights the word X in range(n) |
You can also combine multiple annotations into 1 (one).
Custom Components
MDX allows embedding React components directly:
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
:
Or wrap content with Tailwind's typography styles:
Embedding Media
You can embed images, iframes, and videos like normal HTML:
Velite
Collections
For complex MDX systems, consider using:
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