import {Note} from '../_component/note.server.js'
export const info = {
  author: [
    {name: 'John Otander', github: 'johno', twitter: '4lpine'}
  ],
  published: new Date('2019-04-11'),
  modified: new Date('2021-11-01')
}

<Note type="legacy">
  **Note**: This is an old blog post.
  [ZEIT is now Vercel](https://rauchg.com/2020/vercel).
  An “`@mdx` pragma” is no longer needed.
  The below is kept as is for historical purposes.
</Note>

# 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](https://johno.com/authorable-format) that
makes it *fun* to write again.

{/* more */}

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](https://github.com/remarkjs/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](https://github.com/remarkjs/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](https://github.com/christopherbiscardi)
for implementing this feature.

[Read the blog post](/blog/custom-pragma/)

### 📚 Documentation

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

*   [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672)
*   [Guides](/guides/)
*   [Automatic deployment via ZEIT](https://zeit.co)
*   [Custom Gatsby theme](https://gatsbyjs.org)
*   Reorganization of docs for intuitiveness
*   Full page rewrites to improve clarity

Special thanks to [@jxnblk](https://github.com/jxnblks) and
[@wooorm](https://github.com/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](/migrating/v1#pragma)
*   MDXProvider now merges component contexts when nested
    — [migration guide](/migrating/v1#mdxprovider)
*   React support now requires `>= 16.8` in `@mdx-js/react`
    — [migration guide](/migrating/v1#react)

[Read the full v1 migration guide](/migrating/v1)

### 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](https://github.com/mdx-js/mdx/graphs/contributors?from=2017-12-17\&to=2019-04-11\&type=c)

### Ecosystem

*   [Prettier](https://prettier.io)
*   [Docz](https://docz.site)
*   [MDX Deck](https://github.com/jxnblk/mdx-deck)
*   [Next.js](https://nextjs.org)
*   [Gatsby](https://gatsbyjs.org)
*   [AST Explorer](https://astexplorer.net)
*   [Vue support (alpha)](/docs/getting-started/#vue)
*   [Demoboard](https://frontarm.com/demoboard/)
*   [Editors](/docs/getting-started/#editor)

## 🛣 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](https://github.com/mdx-js/mdx/issues/454)
*   Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195)
*   Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508)
*   Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238)
*   Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks)
*   MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220)
*   New splash page: [#444](https://github.com/mdx-js/mdx/issues/444)
*   Showcase page: [#414](https://github.com/mdx-js/mdx/issues/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.

[See the Vue example](https://github.com/mdx-js/mdx/tree/36cb41b/examples/vue)

### 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](https://github.com/blocks/blocks)

## 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.

*   [ZEIT](https://zeit.co) 🥇
*   [Gatsby](https://gatsbyjs.org) 🥇
*   [Holloway](https://www.holloway.com) 🥉
*   [Backers](https://opencollective.com/unified#budget) 🏆
*   [You?](https://opencollective.com/unified)👤

## 🙏 Thanks

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