MDX

June 7, 2018

MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects. It combines the readability of Markdown with the expressivity of JSX. The best of both worlds.

If you configure MDX for your project you can do wild things like importing React components into your markdown file and use them in there.

import Graph from './components/graph'

## Here's a graph

<Graph />

And on the other hand you can import your MDX files into React components and use them as regular React components.

import React from 'react'
import Hello from '../hello.md'

export default () => <Hello />

Powerful stuff. If you are a developer building something with React or Next.js and you want to add content to the project, that’s a really nice way to do it. It feels kind of mind blowing once you use it.

MDX is a superset of the CommonMark specification that adds embedded JSX and the import/export syntax.

CommonMark was created by the people who built Discourse. They support Markdown on their platform and they needed a clear specification that handles certain edge cases. The original specification by John Gruber was not specific enough. At first they wanted to call it Standard Markdown but Gruber threw a hissyfit, wrote an angry email and even talked about it on his podcast The Talkshow.

Discourse never sought to upset him or take anything away from him so they renamed it to CommonMark.

It’s great to see that things like MDX can be built quite safely and relatively easy because there is a Markdown specification.