Skip to navigation
3-4 minutes read
By Titus Wormer

About

This article explains in short how MDX came to be and why it exists. It also gives thanks to the people who’ve helped make it and inspired it.

What is MDX?

MDX is the combination of markdown with JSX. See § What is MDX? for more info.

Why MDX?

Markdown does not have a syntax for custom components. MDX solves this.

There are many languages objectively better than markdown, however, markdown is great because:

  • It looks like what it means and is relatively easy to read
  • Although images are confusing, most stuff is relatively simple to write
  • It’s loose and ambiguous: it may not work but you won’t get an error (great for someone posting a comment to a forum if they forgot an asterisk)

Markdown does have a way to extend it, HTML, but that has drawbacks:

  • HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense
  • HTML is unsafe by default, so it’s sometimes (partially) unsupported
  • HTML and markdown don’t mix well, resulting in confusing rules such as blank lines or markdown="1" attributes
  • HTML is coupled with browsers, markdown is useful for other things too

The frontend world has an alternative to HTML: JSX. JSX is great, amongst other things, because:

  • It has a relatively familiar syntax (like XML)
  • It’s agnostic to semantics and intended for compilers (can have any domain-specific meaning)
  • It’s strict and unambiguous (great if an author forgot a slash somewhere, as they’ll get an error early, instead of a book going to print with broken stuff in it)

Who governs MDX?

The project is governed by the unified collective.

Who created MDX?

The idea of combining markdown, JavaScript, and JSX was a collaborative effort by Guillermo Rauch (@rauchg), James K. Nelson (@jamesknelson), John Otander (@johno), Tim Neutkens (@timneutkens), Brent Jackson (@jxnblk), Jessica Stokes (@ticky), and more.

While everyone above was key to MDX, we want to stress the involvement of John Otander (@johno). John wrote most of the code for the first alpha and later stable version 1 of this project!

Logo designs were created by Evil Rabbit of Vercel.

What projects inspired MDX?

The following projects, languages, and articles helped shape MDX either in implementation or inspiration.

Note: Is your work missing? Please open a PR if we failed to attribute your work.

The markdown and JSX languages inspired MDX. Markdown was created by John Gruber (@gruber). CommonMark, the most popular markdown variant, by John McFarlane (@jgm) et al. JSX was created by Sebastian Markbåge (@sebmarkbage) et al. at Facebook, Inc.

The @mdx-js/* projects currently make heavy use of unified (specifically micromark, remark and rehype) and Acorn. unified, remark, rehype, and related tools were created by Titus Wormer (@wooorm) et al. Acorn by Marijn Haverbeke (@marijnh) et al.

The following projects inspired @mdx-js/* originally:

The following articles inspired @mdx-js/* originally: