How to make a stories.mdx file in Storybook?

Creating stories.mdx files in Storybook is a highly effective way to write and display your component documentation. MDX is a format that combines Markdown and JSX, enabling you to directly integrate React components within Markdown files.

Step 1: Install Required Dependencies

First, ensure Storybook is installed in your project. Then, install @storybook/addon-docs, which enables Storybook to support MDX format.

bash
npm install @storybook/addon-docs --save-dev

Step 2: Configure Storybook

Within your .storybook folder's main.js configuration file, add addon-docs:

javascript
module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-docs'],
};

Step 3: Create Your MDX File

In your project, select a component to document. For example, if you have a Button component, create a Button.stories.mdx file. Within this file, you can use MDX syntax to define component stories (Story) and documentation.

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

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

# Button

This is a basic button component.

## Usage Example

<Preview>
  <Story name="Basic">
    <Button>Click me</Button>
  </Story>
</Preview>

## Props

<Props of={Button} />

Step 4: Run Storybook

After completing the configuration, run Storybook to view your component documentation:

bash
npm run storybook

Open your browser and access the Storybook URL (typically http://localhost:6006), where you can see the stories and documentation for your Button component.

Example

For example, assume you have a simple Button component with the following code:

javascript
import React from 'react';

const Button = ({ children, onClick }) => (
  <button onClick={onClick}>{children}</button>
);

export default Button;

You can create a corresponding Button.stories.mdx file to demonstrate how to use this button and provide interactive examples. This not only helps developers understand component usage but also serves as interactive documentation for designers and product managers.