What is MDX?
MDX is a shorthand for 'Markdown eXtended', and it is a format that allows you to use JSX in your markdown content, giving you the ability to add interactivity to your content
MDX gives makes you write markdown with embedded components through JSX.
Why use MDX?
- to add interactivity to your content
- often feels more natural to type than HTML or JSX for common things like emphasis or headings.
- typically looks more like what's intended and is terser.
MDX in short
❤️ Powerful: MDX blends markdown and JSX syntax to fit perfectly in JSX-based projects
💻 Everything is a component: Use existing components in your MDX and import other MDX files as components
🔧 Customizable: Decide which component is rendered for each markdown construct
📚 Markdown-based: The simplicity and elegance of markdown remain, you use JSX only when you want to
🔥 Blazingly blazing fast: MDX has no runtime, all compilation occurs during the build stage
Markdown features that don't work in MDX
- Indented code does not work in MDX.
cosnsole.log("so you can nicely indent your components");
- Autolinks do not work in MDX.
The reason is that they can be indistinguishable from JSX (for example: <svg:rect>) and we prefer being explicit. If you want links, use full links: [descriptive text](https://and-the-link-here.com)
- HTML syntax doesn't work in MDX as it's replaced by JSX
(<img> to <img />).
Instead of HTML comments, you can use JavaScript comments in braces: {/* comment! */}
- invalid characters
{
/*Unescaped left angle bracket / less than (<) and left curly brace ({) have to be escaped: \< or \{ (or use expressions: {'<'}, {'{'})*/
}
How to define components in mdx
You can import them, define them locally, or pass them in later (see § Using MDX):
Notes
- markdown is whitespace sensitive and forgiving (what you type may not exactly work but it won’t crash) whereas JavaScript is whitespace insensitive and unforgiving (it does crash on typos).
- MDX supports standard markdown by default (CommonMark):
- Nonstandard markdown features (such as GFM, frontmatter, math, syntax highlighting) can be enabled with plugins (see ¶ Using plugins).
- components must be defined to be used in mdx.
- MDX supports JSX syntax.
- MDX also supports JavaScript expressions inside curly braces:
Two 🍰 is: {Math.PI \* 2}
- Expressions can be empty or contain just a comment:
- Expressions can contain whole JavaScript programs as long as they're (wrapped in) an expression that evaluates to something that can be rendered. You can use an IIFE like so: