Shortcodes

Note: This is an old blog post. The features described in it are currently documented at § MDX provider. The below is kept as is for historical purposes.

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.

If you have an application wrapper for your MDX documents you can add in components with the MDXProvider:

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}) => (
  <MDXProvider components={shortcodes}>{children}</MDXProvider>
)

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.

example.mdx

# Hello world!

Here’s a YouTube shortcode:

<YouTube tweetId="1234" />

Here’s a YouTube shortcode wrapped in TomatoBox:

<TomatoBox>
  <YouTube videoId="1234" />
</TomatoBox>

That’s it. 🎉 🚀

Huge thanks to Chris Biscardi for building out most of this functionality.