MDX

a mad scientist mixing the content of a bottle labeled markdown with the content of another bottle labeled JSX into a big bowl labeled MDX

MDX is an extension of markdown, MDX means markdown + JSX, markdown is a markup language that can be used to format raw text, it was developed in 2004 by John Gruber in collaboration with Aaron Swartz and JSX is a syntax extension for JavaScript that lets you write HTML-like markup inside a JavaScript file

For an in-depth tutorial about how to use MDX with Next.js, check out my Tutorial: Next.js static MDX blog

What is MDX (behind the scenes)

MDX supports all markdown formatting elements that are also supported markdown, and even more formatting elements are available if you use plugins that add new elements like, for example, GFM (github flavored markdown) plugins

The big difference between markdown and MDX, is that MDX allows you to use JSX in your markdown content, meaning you can import and add JSX components (in our case React components) in your MDX content, for example, add a react component that is a comment section at the end of each article, or create a 3D animation using react three fiber and insert that react component in one of your articles, ...

Note: When I mention MDX on the following pages, I'm referring to MDX 3, the current version of MDX. The latest major release is MDX3 (October 24, 2023). The MDX v3 release blog post contains an overview of the few breaking changes and improvements. You can check the full MDX 3.0.0 changelog on the GitHub releases page, and if you are migrating from the previous version, you may want to have a look at the MDX v2 to v3 migration guide

All transformations happen thanks to utilities built on top of unified. It is the core project used to transform content with ASTs. The unified github repository gives us the following description:

Unified is an interface for parsing, inspecting, transforming, and serializing content through syntax trees

The specifications are all managed by the syntax-tree organisation on github which is part of the unified collective, this is the home for several syntax tree specifications, the base syntax tree is called unist, unist is a universal syntax tree specification, it is part of the family of syntax trees called Abstract Syntax Treess hence the abbreviation ASTs, on top of unist you have the other syntax trees that we are interested in, the first one is called MDAST this is the specification that represents markdown in a syntax tree and the second one is called HAST which is the specification that represents HTML in a syntax tree, but because we use MDX and not pure markdown, the two syntax trees MDAST and HAST have supersets, the superset of MDAST is called MDXAST and the superset of HAST is called MDXHAST

MDAST and HAST are the syntax tree specifications, but the actual tools are remnark, which is a tool that transforms markdown with plugins, and rehype which is a tool that transforms HTML with plugins

MDX supports both remark and rehype plugins. More about plugins in the "using plugins to extend MDX" chapter

Note: if you want to experiment with MDX content, there is a great tool called MDX playground. You can experiment with MDX content, and it will help you visualize how MDX content gets transformed from MDAST (markdown AST) to HAST (HTML AST) to ESAST (javascript / JSX)

Collection of informative souces

Frameworks with MDX support

All major frameworks support MDX either out of the box or via packages that you can install separately, Next.js has @next/mdx, but there are alternatives that I listed in the @next/mdx alternatives chapter, Astro has @astrojs/mdx, Remix devs often use mdx-bundler, and Gatsby has gatsby-plugin-mdx, there is also a popular project called Docusaurus which uses MDX, but it is more opinionated than the other frameworks as it focuses on building a documentation website

Next.js MDX & markdown packages

@next/mdx is an MDX package by the Next.js team

next mdx remote is an MDX package that has a feature @next/md does not, which is using remote MDX files or MDX content from a database

markdoc is a markdown only package (so no MDX), but they now have a Next.js plugin, which makes it easy to use markdoc with Next.js

contentlayer is an MDX package that was popular in the past (having earned >3k stars) but does not seem to get any updates anymore

Warning

This is the post suggests that its development is currently halted. Also, as of now, the last update was almost a year ago, so be careful when considering that package