Support Storybook's Component Story Format

[sapegin]

Component Story Format (CSF) is a new format that doesn't call Storybook API directly, meaning it can be used not just in Storybook. By supporting CSF we can allow teams to use Storybook for component development, visual and end-to-end testing, and use Styleguidist to generate beautiful documentation.

It looks like this:

import React from 'react';
import { action } from '@storybook/addon-actions';
import Button from './Button';

export default {
  component: Button,
  title: 'Button',
};

export const text = () => <Button onClick={action('clicked')}>Hello Button</Button>;

export const emoji = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      😀 😎 👍 💯
    </span>
  </Button>
);

I see two ways of doing it:

1. We can implement it by first adding an internal Styleguidist format that will be used on the frontend, the current Markdown format and CSF will be converted to this format. I had this idea back in 2017, and this may open other possibilities.

2. Keep documentation in Markdown but reference stories to load source code from them, similar to loading source code from files.

• Check if CSF can be extended (meaning adding new fields to stories and default export object won't break Storybook).
• Find a way to load source of the stories.
• Find a way to define imports. Dependencies are essential part of documentation to make code copypastable.
• Find what to do with actions. We can probably substitute it with our own implementation.

Only needed for the first option:

• Define the API to add textual Markdown documentation for each story.
• Define the API to include / exclude stories in / from the styleguide.
• Define internal Styleguidist format that will be used on the frontend, the current Markdown format and CSF will be converted to this format

[elevatebart]

Supporting MDX (and especially storybook format) is a great idea. It could bridge the divide between the two communities.

MDX holds one big advantage over pure MarkDown: Tooling
Since MDX contains valid JSX you can import components using es6 imports.
VSCode will pick up on it and check props usage and types. This would avoid mistakes and improve the dev experience a lot.

I prefer to use pure markdown for now as the source code of examples remains visible in GitHub renderings of the ReadMe.md files. When you got to this folder, you still get a readable (non-interactive) documentation of the Button component. Github is not the only service that follows this standard. Azure, GitLab and BitBucket are doing the same thing.

With MDX you get weird unclean JSX structures like in storybooks example here

[sapegin]

Yeah, MDX might be an option but I think it's much more difficult to do than especially the second option here.

[elevatebart]

It feels easy to parse CSF using babel and extract the source code of examples from it. I think we could make a separate package that allows referencing CSF stories in styleguidist.

I would probably see a format like this one. Though, I am struggling to see a scenario where I would use it.

``` javascript {"story": {"file": "./MyButton.stories.js", "name": "text"}}
```

[sapegin]

I don't even think we need babel for this, just Acorn to locate positions of the code. Similar to how we transpile imports.

And the API — I was thinking about something like that too.

[elevatebart]

Acorn is what I meant when I said babel. They kind of conflate in my mind (babel parser ~ acorn).
I apologize for the confusion.

Regarding the API, in vue-styleguidist, I used another syntax: [import](./myExample.vue) documented here

It has a considerable dev experience advantage, which is to allow navigation to the said file in vscode.

[sapegin]

With #1712 we'll be able to load CSF stories using a React component, instead of inventing our own syntax.