MDX Embed for Storybook

Embed Egghead, Codepen, and Twitter into MDX

Published in

Storybook

3 min readDec 10, 2020

Storybook is one of the most popular tools for UI component documentation. It allows developers to write Markdown and React/Vue/Angular side-by-side using MDX. That means you can document components while building the UI.

In practice, MDX is a more convenient way to write documentation so popular frontend projects like Storybook, Gatsby, and NextJS support it. But MDXs core API is narrow — you need to write custom code to add rich media into your docs.

The MDX Embed addon allows you to embed 3rd party media content such as YouTube videos, Tweets, Instagram posts, Egghead lessons, Spotify, TikTok and many more into Storybook docs.

Why build an addon

When Storybook shipped with MDX support, I realized I could expand the default MDX implementation by creating an addon. That would make it easier for the community to embed content and help me get contributions and feedback.

I piggybacked off Storybook’s parameter API to wrap all MDX docs in “Provider”-type component called MDXEmbedProvider. That saves me from having to import them one-by-one (you might have encountered this if you use styled-components et al).

The provider allows Storybooks docs pages to render the out-of-the-box embed components for services like CodeSandbox whenever it encounters them in a *.stories.mdx file. Checkout the example below.

// some.stories.mdximport { Meta, Story, Canvas,} from '@storybook/addon-docs/blocks';
import { SomeComponent } from '../some-where';<Meta title="Components/SomeComponent" component={SomeComponent} />
<Canvas>
 <Story name="usage">
   <CodeSandbox codeSandboxId="react-new" />
 </Story>
</Canvas><Canvas>
 <Story name="something">
   <SomeComponent someProp="foo"/>
 </Story>
</Canvas>

You can see from the above that to render SomeComponent” you need to import it into your .stories.mdx file while MDX Embed’s CodeSandbox component doesn’t require the import.

MDX Embed is written in React and the core components can be imported in any JSX file as well

When to use MDX Embed

First off, you can only use the addon if you’re writing stories or docspages in the MDX story format, not Component Story Format (CSF).

Both formats output the same level of detail, prop tables, code snippets, etc but MDX allows for a nicer writing experience. If you plan to write supporting documentation around your component MDX is for you. Use cases that it’s great for:

Long form content
Brand guidelines
Typography
Do’s and don’ts
Usage examples

What’s more, designers tend to prefer MDX because it’s more natural to write “Markdown” than JavaScript. That helps teams bridge that designer / engineer gap. MDX Embed is perfect for these use cases because richer docs makes it easier for folks to learn.

How to install

First install the addon from npm.

npm install mdx-embed storybook-addon-mdx-embed --save

Then register the addon in Storybook’s configuration.

// .storybook/main.jsmodule.exports = {
  ...
  addons: ['storybook-addon-mdx-embed']
};

Final thoughts

I’m happy to share MDX Embed with the Storybook community.

If you’re interested in open-source software, developing addons for a popular project can give you a head start. Launching a project is hard without an audience, you can reach a lot more users by standing on the shoulders of giants so to speak.

If you’re interested in developing a Storybook addon, I recommend checking out the links below.

The Storybook team are super brilliant, if you have any questions about how to get started developing addons they’ll be more than happy to help.

Get involved

To get the latest addons and Storybook news sign up to the Storybook mailing list. Check out Storybook on GitHub and join the Discord chat.