Storybook for React — MDX Documentation
Tags: react, webdev, programming, javascript
Published: 2021-01-24 21:44:18

**Check out my books on Amazon at https://www.amazon.com/John-Au-Yeung/e/B08FT5NT62**

**Subscribe to my email list now at http://jauyeung.net/subscribe/**


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.