Skip to navigation
5-7 minutes read
By John Otander

Note: This is an old blog post. ZEIT is now Vercel. An “@mdx pragma” is no longer needed. The below is kept as is for historical purposes.

MDX goes stable

It’s been a year and a half since the first MDX commit and a year since MDX was first announced at ZEIT Day. MDX is a radical paradigm shift in how to write immersive content using components. It’s an open, authorable format that makes it fun to write again.

Since announcing MDX we’ve been working on numerous bug fixes, new features, better parsing, and integration tests. Now, we think it’s ready. We’re happy to finally release v1!

🎉 What’s new?

Here’s a rough breakdown on what we’ve been working on:

Parsing

MDX document parsing is significantly improved. We won’t get into the nitty gritty here, but we’ve seen how MDX is used in real-world projects, integrated the edge cases we came across into our test suite, and now handle JSX, imports, and exports much more intuitively. Please open an issue if you find a case we haven’t covered!😸

remark-mdx

remark-mdx is the syntactic extension for MDX in remark. It provides the parsing functionality for MDX as a remark plugin. That sounds a bit meta. What it means is that before we had the syntax parsing bits in the library (unusable from the outside), and now it’s externalized (usable from the outside). This is useful if you want to inspect or transform MDX documents. For example, it allows tools like prettier to use the exact same parser used by MDX core. Or you could use remark-mdx in combination with remark-lint to check your MDX.

Custom pragma

With v1 we’ve moved away from using MDXTag and are using a custom pragma which wraps React.createElement. We decided to update this approach so the JSX output is more legible, lighterweight, and more customizable. This means MDX can be used with any React, Vue, Preact, or any other library with JSX support.

Special thanks to @christopherbiscardi for implementing this feature.

Read the blog post

📚 Documentation

Good libraries need great docs, so we’ve been working on adding content and improving the overall documentation website experience.

Special thanks to @jxnblk and @wooorm for their help improving the docs and updating the build tooling.

Breaking changes

In order to make some improvements we were forced to introduce a few breaking changes. These were the result of real-world production testing and feedback. The community has evolved and we’ve come up with newer, better ideas over the last year. We have made sure the impact is small and have written a full migration guide.

  • 🚨@mdx-js/tag is replaced by @mdx-js/react and an @mdx pragma — migration guide
  • MDXProvider now merges component contexts when nested — migration guide
  • React support now requires >= 16.8 in @mdx-js/react — migration guide

Read the full v1 migration guide

Deprecations

We only needed to introduce one deprecation. The mdPlugins and hastPlugins options have been renamed remarkPlugins and rehypePlugins respectively. For the time being we will issue a warning when the old options are used. In v2, the old options will be removed.

📈 Growth

A major release is always a good time to take a step back and reflect on what’s been happening in terms of growth and the greater community. The ecosystem surrounding MDX has already grown larger than we ever dreamed. We’ve also seen projects/products/application we never even imagined.

Numbers

  • Downloads: 125,000/week, 2.4M total
  • Stars: 6,200
  • Contributors: 50
  • Pull requests: 281
  • Commits: 670

The contributor growth is one of the most important aspects here as we have numerous community members that are familiar with MDX internals. This allows us to continually improve the project and spread the workload against an ever growing team of contributors.

See the contributor graph

Ecosystem

🛣 Roadmap

With v1 released we have a roadmap in place that we’ll continue working towards over the next 6 months or so in addition to bug fixes and parsing issues we might encounter.

Vue support

Supporting Vue is an important goal for MDX and is one of the primary reasons we’ve rearchitected MDX to use custom pragma. We’re delighted that we now have an alpha version for Vue working. We’d love it if anyone from the Vue community wants to give it a try and provide feedback.

See the Vue example

Blocks project

One of the key missing aspects of authoring MDX documents is the editing experience. Currently, there isn’t an approachable way to write MDX unless you enjoy working in a text editor and writing raw Markdown/code. We’d like to solve that and have begun work on an MDX “blocks editor” that’s a content-focused WYSIWYG. Not to mention, we’ll be doing all that we can to make sure the editor is as accessible as it can be from the beginning.

When we have a beta ready we will be open sourcing it and announcing, so stay tuned.

Check out the Blocks project

unified collective

MDX is part of the unified collective, which is an open source ecosystem for dealing with many sources of content. unified projects are used all over the web, and it would never be possible without financial support from our fine sponsors.

🙏 Thanks

We’d like to say thanks to all our contributors and our happy users. Special thanks to @wooorm, @silvenon, @timneutkens, @ChristopherBiscardi, @jxnblk, @alexandernanberg, @jescalan, @Jarred-Sumner, @leimonio, @ticky, @jamesknelson, @pshrmn, @rauchg, @joelhooks, @jlengstorf, @johnlindquist, @kyleamathews, @kentcdodds, @wesbos, @rosew, @pedronauck, @tayiorbeii, @nickbender, @ntaylor89, @mxstbr, @manovotny, @xyc, @filoxo, @millette, @hugmanrique, @johnsherrard, @sw-yx, and anyone we may have forgotten.