John Au-YeungCheck 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.
