Storybook for React — MDX Documentation

Storybook lets us prototype components easily with various parameters.

In this article, we’ll look at how to add MDX documentation with Storybook.

MDX

The MDX file format mixes Markdown with JSX.

We can use Markdown’s succinct syntax for our documentation.

Storybook will compile the Markdown and JSX together into a document.

We create a MDX file with the stories.mdx to create our documentation.

For example, we can write:

Button.stories.mdx

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Button } from './Button';

<Meta title="Example/Button" component={Button} />

# Button

A button

<!--- This is your Story template function, shown here in React -->

export const Template = (args) => <Button {...args} />

<Canvas>
  <Story name="Primary" args={{
      label: 'button',
      primary: true
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
      label: 'button',
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
    label: 'button'
  }}>
    {Template.bind({})}
   </Story>
</Canvas>

Then in the Storybook screen, we see the button displayed.

The Canvas component is the container for the documentation.

Story has the stories we populate in our documentation.

The Markdown description will show in the Docs tab.

Decorators and Parameters

We can add decorators and parameters in the MDX document.

We can add them as the props of the Meta component.

For example, we can add the decorators prop by writing:

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Button } from './Button';

<Meta
  title="Example/Button"
  component={Button}
  decorators={[(Story) => <div style={{ margin: '20px' }}><Story/></div>]}
/>

# Button

A button

<!--- This is your Story template function, shown here in React -->

export const Template = (args) => <Button {...args} />

<Canvas>
  <Story name="Primary" args={{
      label: 'button',
      primary: true
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
      label: 'button',
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
    label: 'button'
  }}>
    {Template.bind({})}
   </Story>
</Canvas>

To add parameters, we can write:

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Button } from './Button';

<Meta
  title="Example/Button"
  component={Button}
  parameters={{
    backgrounds: {
      values: [
        { name: 'red', value: '#f00' },
        { name: 'green', value: '#0f0' },
      ],
    },
  }}
/>

# Button

A button

<!--- This is your Story template function, shown here in React -->

export const Template = (args) => <Button {...args} />

<Canvas>
  <Story name="Primary" args={{
      label: 'button',
      primary: true
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
      label: 'button',
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
    label: 'button'
  }}>
    {Template.bind({})}
   </Story>
</Canvas>

We added the parameters prop with the usual parameters object.

Now we should see the background color dropdown which is added by adding the background property.

Documentation-only MDX

To define documentation-only MDX, we just add the Meta component but don’t define any stories.

For example, we can create a src/stories/Foo.stories.mdx file and add:

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';

<Meta
  title="Example/Foo"
/>

# Foo

foo bar

Now we should see a Foo link on the left sidebar and we can click on it to see the Markdown displayed as HTML.

Conclusion

We can add stories with MDX files, which mixes Markdown with JSX.