@storybook/mdx2-csf

What is @storybook/mdx2-csf?

The @storybook/mdx2-csf npm package is designed to convert MDX (Markdown for JSX) files into Component Story Format (CSF) used by Storybook. This allows developers to write their stories in MDX format, which combines Markdown with JSX, and then automatically convert these stories into the format that Storybook can understand and use to render components in its UI.

What are @storybook/mdx2-csf's main functionalities?

Convert MDX to CSF

This feature allows developers to convert MDX content directly into CSF format. The code sample demonstrates how to import the conversion function and use it to transform an MDX string that includes a component story into valid CSF.

import { mdxToCsf } from '@storybook/mdx2-csf';

const mdxContent = `
<Meta title='MyComponent' component={MyComponent} />

# MyComponent

<Story name='Example'>
  <MyComponent />
</Story>
`;

const csfContent = mdxToCsf(mdxContent);
console.log(csfContent);

Other packages similar to @storybook/mdx2-csf

@storybook/addon-docs

This package is part of the Storybook ecosystem and allows developers to write documentation alongside their stories in MDX format. While it also processes MDX files, it focuses more on integrating documentation directly into Storybook's UI, rather than converting MDX to CSF.

README

@storybook/mdx2-csf

Storybook's mdx2-csf is a compiler that turns MDXv2 input into CSF output.

For example, the following input:

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

<Meta title="atoms/Button" />

<Story name="Bar">
  <Button>hello</Button>
</Story>

Might be transformed into the following CSF (over-simplified):

export default {
  title: 'atoms/Button',
};

export const Bar = () => <Button>hello</Button>;

API

This library exports an async function to compile MDX, compile. It does not support a synchronous compiler because it uses asynchronous imports to bridge the ESM/CJS gap. The underlying MDXv2 libraries only support pure ESM, but this library is used in CJS environments.

compile

Asynchronously compile a string:

import { compile } from '@storybook/mdx2-csf';

const code = '# hello\n\nworld';
const output = await compile(code);

Loader

In addition, this library supports a simple Webpack loader that mirrors MDXv1's loader, but adds Webpack5 support. It doesn't use MDXv2's loader because it is prohibitively complex, and we want this to be interchangeable with the @storybook/mdx1-csf's loader which is also based on the MDXv1 loader.

The loader takes two options:

• skipCsf don't generate CSF stories for the MDX file
• mdxCompileOptions full options for the MDX compile function

For example, to add GFM support:

import remarkGfm from 'remark-gfm';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(stories|story)\.mdx$/,
        use: [
          {
            loader: require.resolve('@storybook/mdx2-csf/loader'),
            options: {
              skipCsf: false,
              mdxCompileOptions: {
                remarkPlugins: [remarkGfm],
              },
            },
          },
        ],
      },
    ],
  },
};

Contributing

We welcome contributions to Storybook!

• 📥 Pull requests and 🌟 Stars are always welcome.
• Read our contributing guide to get started, or find us on Discord, we will take the time to guide you

License

MIT