Storybook-readme: Ability to use multiple stories within a single README

[andyrichardson]

Hey there. First off, thanks for the awesome package!

I'm wondering if there is/could be a way to have a single README with multiple different stories.

Example

Here I would expect the story to contain two sections _Primary_ and _Secondary_ with the corresponding buttons rendered.

const MD = `
# Buttons

## Primary
This is a primary button
<!-- STORY -->

## Secondary
This is a secondary button
<!-- STORY -->
`;

storiesOf("Components|Button", module)
    .addParameters({ readme: { content: MD } })
    .add("Button", () => <Button kind="primary">Primary</Button>)
    .add("Button", () => <Button kind="secondary">Secondary</Button>);

[tuchk4]

@andyrichardson your example looks working.
Did you face any issues?

[andyrichardson]

@tuchk4 here's what I'm currently seeing - its as if the second 'add' call replaces the initial story.

Edit: And here is the HTML output

<div class="storybook-readme-story">
  <div>
    <div class="markdown-body">
      <h1 id="buttons">Buttons</h1>
      <h2 id="primary">Primary</h2>
      <p>This is a primary button</p>
    </div>
  </div>
  <div style="margin: 32px 0px;">
    <div><button>Secondary</button></div>
  </div>
  <div>
    <div class="markdown-body">
      <h2 id="secondary">Secondary</h2>
      <p>This is a secondary button</p>
      <!-- STORY -->
    </div>
  </div>
</div>

[tuchk4]

Got it.
Right now it is not possible but I am going to implement such feature in near future. Maybe 1-2 months. (don't have enough time right now :( )

[andyrichardson]

No worries! I believe it would require a substantial change to the API as storybook doesn't look to allow multiple stories.

In order to get around this constraint, react-storybook-addon-chapters added their own addChapter function rather than using the built in add.

[tuchk4]

Sounds like challenge :) Hold my bear

[tuchk4]

I have prof of concept.
All code inside code blocks marked with story will render as separated story inside your doc.
It is possible to implement.

@lonyele Interested your opinion about this feature

# Button :star:

Application button.

\```js 
import Button from 'components/Button';
\```

### Button


\```story
const Button = require('../components/Button');

<Button>Hello World</Button>
\```

### Alert button

\```story

const Button = require('../components/Button');

<Button variant="alert">Hello World</Button>
\```

[andyrichardson]

Looks like an MDX style approach 👍

[lonyele]

Hm... It took some time to come up with my solution to this problem. Just to be clear...

What is desired

From a single README, stories with same name should be rendered on its places(In this issue's case, MD is a single README and Button is a story name)

Possible implementation of this feature

1. As tuchk4 said, it is possible to write story on README with ```story and render it.
   Thought: It sounds fine, but here my concerns...
   First, user can't get any code formatting because it is being written to markdown's code block(reason for the rise of MDX?)
   Second, if user writes everything on README for this case, what is being written to the normal story? At least one is needed to be passed

2. From storybook, they give an array of stories when multiple stories with same name exists and from storybook-readme use this to render multiple stories to single README.
   Thought: Currently, It seems like last story that is added is only passed. Maybe complicate to implement from storybook's side...

3. From storybook, new api such as .addMultipleStories() exists and use it from storybook-readme
   Thought: Maybe complicate to implement from storybook's side...

4. From storybook-readme, if the story looks like this(an array of childrens such as this). It is possible to extract it as seperate story and render on README.
   Thought: This sounds like a very-bad hack since it can't guarantee it is for this specific feature or
   normally writing stories with React fragments

.add('With a single Readme!', () => 
      <>
         <Button label={'Hello Im Button 11111'} />,
         <Button label={'Hello Im Button 22222'} />,
         <Button label={'Hello Im Button 33333'} />,
      </>
    );
)

My choice of solution

I'm not sure if this is a good one or not, but I'll say it anyway... It is similar to solution 4, but with storybook-readme's custom components. If storybook-readme offers React component like MultipleStories and used like this example. It is possible to know safely that it is for this specifc use case.

storiesOf('Multiple stories in single Readme', module)
  .addParameters({
    readme: {
      content: TestMultipleReadme,
    },
  })
  .add('With a single Readme!', () => {
    return (
      <MultipleStories
        stories={[
          <Button label={'Hello Im Button 11111'} />,
          <Button label={'Hello Im Button 22222'} />,
          <Button label={'Hello Im Button 33333'} />,
          1234,
          555555,
        ]}
      />
    );
  });

Below is the example of README file. We can just use <!-- STORY --> or something new for this specific case such as <!-- MULITPLE_STORY --> (btw I prefer new placeholder for this to explicitly say to the user)

### Multiple stories in single Readme

## First~
This is a primary button
<!-- STORY -->

## Second~
This is a secondary button
<!-- STORY -->

## Third~
This is a third button
<!-- STORY -->

## Fourth~
This is a fourth button
<!-- STORY -->

For this discussion, I made a simple implementation of my solution at my repo It is same as this repo. I made an example on branch example/multiple-stories-in-single-readme. I want to here about any opinions on this. @tuchk4

[tuchk4]

Here is Proof of concept for MDX https://github.com/tuchk4/storybook-readme/pull/178

## Title

Some description

\```js
// const Button = require('../components/Button');

<button>Hello World</button>
\```

\```js
// const Button = require('../components/Button');

const value = state.counter || 0;

<button
  onClick={() => {
    setState({
      counter: value + 1,
    });
  }}
>
  Hello World {value}
</button>;
\```

Here how it is renderd now

Possible usage API:

storiesOf('Button', module).add(
  'Button variants',
  mdx({
    content: require('./Multiple.md'),
  }),
);

[tuchk4]

storybook-readme provides two main features:

• render MD files at the sidebar. Possible to use at any storybook react / vue / angular etc.
• render MD files around the stories. Strongly depends on env. Now supports vue and html (polymer).

So one of the main blockers is that MDX style for both React and Vue :)

Actually, I like your solution with internal components, seems it should be easier in implementation.
But if it is possible, I would like to keep mdx style as at #178.

---

@lonyele

First, user can't get any code formatting because it is being written to markdown's code block

prettier formats code inside markdown documents very well :)

I would like to ship this feature with high prio

[lonyele]

@tuchk4 If that's the case, sticking to MDX style is far better!

[tuchk4]

@lonyele do you want to continue this feature?

I will able to continue only after 1 month.

NOTE that at proof of concept there is no good way to support knobs / info / sources / any other storybook addons .

[lonyele]

@tuchk4 Oh, I thought you are already working on this one because POC code doesn't look small which means you've pretty much put some effort in it. Just personally, I have to finish some works on storybook and chromium, though it will take only a few days, so I'll take a look this one right after those. It seems like I have to ask a lot of questions to you

[tuchk4]

I am going to close this issue because now it is builtin feature at storybook

🎉🎉🎉🎉https://medium.com/storybookjs/storybook-docspage-e185bc3622bf

@ndelangen
@shilman