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.
📚 Documentation
Good libraries need great docs, so we’ve been working on adding content and improving the overall documentation website experience.
- Search (thanks Algolia)
- Guides
- Automatic deployment via ZEIT
- Custom Gatsby theme
- Reorganization of docs for intuitiveness
- Full page rewrites to improve clarity
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.
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.
- MDXs: #454
- Interleaving: #195
- Global shortcodes: #508
- Stable Vue support: #238
- Blocks: MDX WYSIWYG: blocks/blocks
- MDX playground inspired by AST Explorer: #220
- New splash page: #444
- Showcase page: #414
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.
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.
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.
Written by John Otander