` with custom React
Components.
[Iâve previously
written](https://www.christopherbiscardi.com/post/codeblocks-mdx-and-mdx-utils)
about the way `MDXTag` works when trying to replace the `` tag
with a custom code component.
[mdx-utils](https://github.com/ChristopherBiscardi/gatsby-mdx/blob/00769a1b72455f40843cd2f09ee34fd63b009fb2/packages/mdx-utils/index.js)
contains the methodology for pulling the props around appropriately
through the `MDXTag` elements that are inbetween `pre` and `code`.
{/* more */}
```tsx
exports.preToCodeBlock = preProps => {
if (
// children is MDXTag
preProps.children &&
// MDXTag props
preProps.children.props &&
// if MDXTag is going to render a
preProps.children.props.name === 'code'
) {
// we have a situation
const {
children: codeString,
props: {className, ...props}
} = preProps.children.props
return {
codeString: codeString.trim(),
language: className && className.split('-')[1],
...props
}
}
return undefined
}
```
So `MDXTag` is a real Component in the middle of all of the other MDX
rendered elements.
All of the code is included here for reference.
```tsx
import React, {Component} from 'react'
import {withMDXComponents} from './mdx-provider'
const defaults = {
inlineCode: 'code',
wrapper: 'div'
}
class MDXTag extends Component {
render() {
const {
name,
parentName,
props: childProps = {},
children,
components = {},
Layout,
layoutProps
} = this.props
const Component =
components[`${parentName}.${name}`] ||
components[name] ||
defaults[name] ||
name
if (Layout) {
return (
{children}
)
}
return {children}
}
}
export default withMDXComponents(MDXTag)
```
`MDXTag` is used in the hast to estree conversion,
which is the final step in the MDX AST pipeline.
Every renderable element is wrapped in an `MDXTag`, and `MDXTag` handles
rendering the element later.
```tsx
return `${children}`
```
## A concrete example
The following MDX
```mdx
# a title
and such
testing
```
turns into the following React code
```tsx
export default ({components, ...props}) => (
{`a title`}{' '}
{`and such `}{' '}
{`testing`}
)
```
resulting in the following HTML
```html
a title
`and such`
testing
```
## createElement
With the new approach, the above MDX transforms into this new React code
```tsx
const layoutProps = {}
export default function MDXContent({components, ...props}) {
return (
{`a title`}
{`and such
`}
{`testing`}
)
}
MDXContent.isMDXComponent = true
```
Notice how now the React elements are plainly readable without
wrapping `MDXTag`.
Now that weâve cleaned up the intermediary representation, we need to
make sure that we have the same functionality as the old `MDXTag`.
This is done through a custom `createElement` implementation.
Typically when using React, we use `React.createElement` to render the elements
on screen.
This is even true if youâre using JSX because JSX tags such as `` compile
to `createElement` calls.
So this time instead of using `React.createElement` weâll be using our own.
Reproduced here is our `createElement` function and the logic for how
we decide whether or not MDX should take over the rendering of the
`createElement` call.
```tsx
export default function (type, props) {
const args = arguments
const mdxType = props && props.mdxType
if (typeof type === 'string' || mdxType) {
const argsLength = args.length
const createElementArgArray = new Array(argsLength)
createElementArgArray[0] = MDXCreateElement
const newProps = {}
for (let key in props) {
if (hasOwnProperty.call(props, key)) {
newProps[key] = props[key]
}
}
newProps.originalType = type
newProps[TYPE_PROP_NAME] = typeof type === 'string' ? type : mdxType
createElementArgArray[1] = newProps
for (let i = 2; i < argsLength; i++) {
createElementArgArray[i] = args[i]
}
return React.createElement.apply(null, createElementArgArray)
}
return React.createElement.apply(null, args)
}
```
## Vue
One really cool application of the new output format using a custom
`createElement` is that we can now write versions of it for Vue and other
frameworks.
Since the pragma insertion is the responsibility of the webpack (or other
bundlers) loader, swapping the pragma can be an option in mdx-loader as long as
we have a Vue `createElement` to point to.
---
## File: docs/blog/index.mdx
{
/**
* @import {Item} from '../_component/sort.js'
*/
/**
* @typedef Props
* @property {Item} navigationTree
*/
}
import assert from 'node:assert/strict'
import {BlogGroup} from '../_component/blog.jsx'
export const info = {
author: [{name: 'MDX Contributors'}],
modified: new Date('2024-07-04'),
published: new Date('2021-11-01')
}
export const navExcludeGroup = true
export const navigationSortItems = 'navSortSelf,meta.published:desc'
export const navSortSelf = 7
# Blog
The latest news about MDX.
{
(function () {
const navigationTree = props.navigationTree
const category = navigationTree.children.find(function (item) {
return item.name === '/blog/'
})
assert(category)
return (
)
})()
}
---
## File: docs/blog/shortcodes.mdx
import {Note} from '../_component/note.jsx'
export const info = {
author: [
{github: 'johno', name: 'John Otander'}
],
modified: new Date('2021-11-01'),
published: new Date('2019-05-14')
}
**Note**: This is an old blog post.
The features described in it are currently documented at
[§ MDX provider](/docs/using-mdx/#mdx-provider).
The below is kept as is for historical purposes.
# Shortcodes
An exciting new feature in MDX v1 is global shortcodes.
This allows you to expose components to all of your documents in your app or
website.
This is a useful feature for common components like YouTube embeds, Twitter
cards, or anything else frequently used in your documents.
{/* more */}
If you have an application wrapper for your MDX documents
you can add in components with the `MDXProvider`:
```tsx path="src/App.js"
import React from 'react'
import {MDXProvider} from '@mdx-js/react'
import {TomatoBox, Twitter, YouTube} from './ui'
const shortcodes = {TomatoBox, Twitter, YouTube}
export default ({children}) => (
{children}
)
```
Then, any MDX document thatâs wrapped in `App` has access to `YouTube`,
`Twitter`, and `TomatoBox`.
Shortcodes are nothing more than components, so you can reference them anywhere
in an MDX document with JSX.
```mdx path="example.mdx"
# Hello world!
Hereâs a YouTube shortcode:
Hereâs a YouTube shortcode wrapped in TomatoBox:
```
Thatâs it.
đ đ
Huge thanks to [Chris Biscardi](https://christopherbiscardi.com)
for building out most of this functionality.
---
## File: docs/blog/v1.mdx
import {Note} from '../_component/note.jsx'
export const info = {
author: [
{github: 'johno', name: 'John Otander'}
],
modified: new Date('2025-01-27'),
published: new Date('2019-04-11')
}
**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.
# 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][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)
* [Guides](/guides/)
* [Automatic deployment via ZEIT][zeit]
* [Custom Gatsby theme][gatsbyjs]
* Reorganization of docs for intuitiveness
* Full page rewrites to improve clarity
Special thanks to [@jxnblk](https://github.com/jxnblks) and
[@wooorm][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://github.com/pedronauck/docz)
* [MDX Deck](https://github.com/jxnblk/mdx-deck)
* [Next.js](https://nextjs.org)
* [Gatsby][gatsbyjs]
* [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][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][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][] đ„
* [Gatsby][gatsbyjs] đ„
* [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][wooorm],
[@silvenon](https://github.com/silvenon),
[@timneutkens](https://github.com/timneutkens),
[@ChristopherBiscardi][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.
[blocks]: https://github.com/blocks/blocks
[christopherbiscardi]: https://github.com/christopherbiscardi
[gatsbyjs]: https://gatsbyjs.org
[wooorm]: https://github.com/wooorm
[zeit]: https://zeit.co
---
## File: docs/blog/v2.mdx
import {Note} from '../_component/note.jsx'
export const info = {
author: [
{github: 'wooorm', name: 'Titus Wormer'}
],
modified: new Date('2025-01-27'),
published: new Date('2022-02-01')
}
**Note**: This is an old blog post.
The below is kept as is for historical purposes.
**Note**: Info on how to migrate is available in our
[Version 2 migration guide][migrating].
# MDX 2
Version 2 of MDX was released after years of hard work, and has many
improvements.
Here are the highlights:
{/* more */}
* đ **Improved syntax** makes it easier to use markdown in JSX
* đ§âđ» **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI}
* đ New **esbuild**, **Rollup**, and **Node.js** integrations
* âïž **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, theyâre
all supported
* đł **Improved AST** exposes more info in greater detail
* đââïž Compiles at least **25% faster**
* đŽ Generated code runs twice as fast (**100% faster**)
* đ Bundle size of `@mdx-js/mdx` is more than three times as small
(**250% smaller**)
* 𧔠âŠand much, so much more
Itâs been 4 years since this project was announced.
2œ since we released our stable version 1.
**Weâre proud to finally release v2!**
Letâs dive in!
## Contents
* [Improvements to the MDX format](#improvements-to-the-mdx-format)
* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations)
* [Architectural improvements](#architectural-improvements)
* [TypeScript](#typescript)
* [Docs & site](#docs--site)
* [Breaking changes](#breaking-changes)
* [Thanks](#thanks)
## Improvements to the MDX format
Weâve spent a lot of time thinking and trying out different ways to improve the
format.
Originally, the format was very close to how markdown, and HTML in markdown,
works.
We found that the old behavior often yielded unexpected results.
In version 2, we shift the format a little bit closer to how JS(X) works.
Take for example this MDX file:
```mdx chrome=no
*hi*?
# hi?
# hi?
```
In version 1, that was equivalent to the following JSX:
```tsx chrome=no
<>
*hi*?
# hi?
`# hi?`
```
In version 2, itâs equivalent to the following JSX:
```tsx chrome=no
<>
*hi*?