Storybook README addon

Note: withDocs feature is not released yet. It is available only at 3.1.0-beta2

It is very similar with Storybook Notes addon but using Storybook Notes there is <WithNotes notes={...}> wrapper at each story function and thats why Storybook Info always shows that wrapper at info screen.

This addon is compatible with:

Storybook for React

Additional features:

Does not affect on story function. So Storybook Info works correctly now.
100% markdown support
Code highlighting
Accept multiple README (useful for hoc component - add component's and original component's README)
Looks like Github's README

Also it very useful because most projects and components already have README.md files. Now it is easy to add them into your Storybook.

Stories will be added with .addWithInfo method if Storybook Info Addon is installed.

Install

npm install --save-dev storybook-readme

yarn add --dev storybook-readme

Webpack Configuration

module.exports = {
  module: {
    rules: [{
      test: /\.md$/,
      use: "raw-loader"
    }]
  }
};

npm install --save-dev raw-loader

Usage

import 'storybook-readme/register';

Then create your stories with the withReadme or withDocs API.

withDocs - Add README around the story component at the main panel. Example withDocs
withReadme - Add README to the storybook panels. Example withReadme

It is possible to combine withDocs and withReadme - Example combined APIs

import ButtonReadme from '../components/button/README.md';
import { withReadme, withDocs } from 'storybook-readme';

storiesOf('Button', module)
  .add('Default', withReadme(ButtonReadme, () => <Button onClick={action('clicked')} label="Hello Button"/>))

storiesOf('Content', module)
  .add('Default', withDocs(ButtonReadme, () => <Content>Hello Button<Content/>))

Use as Higher Order Component

withReadme(readme, story)
withDocs(readme, story)

Accepts README or array of README in markdown format. Multiple REAMDE is useful when you develop higher order component and want to add its README and original component README.

withReadme example:

import { withReadme } from 'storybook-readme';
import OriginalButtonREADME from 'node_modules/components/button/README.md';
import ButtonREADME from '../components/components/button/README.md';

storiesOf('Button', module)
  // add multiple READMEs (also supports only one)
  .add('Default', withReadme([OriginalButtonREADME, ButtonREADME], () => {
    return <Button onClick={action('clicked')} label="Hello Button"/>;
  }));

withDocs example:

import { withDocs } from 'storybook-readme';
import ButtonREADME from '../components/components/button/README.md';

storiesOf('Button', module)
  // add only one README (also supports multiple as array)
  .add('Default', withDocs(ButtonREADME, () => {
    return <Button onClick={action('clicked')} label="Hello Button"/>;
  }));

Use as Decorator

withReadme(readme) _ withDocs(readme)

Pass only first argument - README or array of README in markdown format.

In this way code of stories is more clean.

withReadme example:

import { withReadme } from 'storybook-readme';
import OriginalButtonREADME from 'node_modules/components/button/README.md';
import ButtonREADME from '../components/components/button/README.md';

storiesOf('Button', module)
  // add multiple READMEs (also supports only one)
  .addDecorator(withReadme([OriginalButtonREADME, ButtonREADME]))
  .add('Default', () => {
    return <Button onClick={action('clicked')} label="Hello Button"/>;
  });

withDocs example:

import { withDocs } from 'storybook-readme';
import ButtonREADME from 'node_modules/component/README.md';

storiesOf('Button', module)
  // add only one README (also supports multiple as array)
  .addDecorator(withDocs(ButtonREADME))
  .add('Default', () => {
    return <Button onClick={action('clicked')} label="Hello Button"/>;
  });

`withDocs` - Common Footer

Will appear at all stories that uses withDocs api.

Note: Should be added before all stories initialization.

import { withDocs } from 'storybook-readme';
import DocsFooterReadme from 'components/DOCS_FOOTER.md';

withDocs.addFooter(DocsFooterReadme);

README splitter (only for `withDocs` API)

You can use  at the README to control component story position. Instead of this placeholder story will be rendered. For example this docs:

# Button

Normal application button. Could be rendered as link is pass `href` prop.

<!-- STORY -->

### Flags usage rules

Use **alert** and **success** flags only in next cases:

**alert** - when `onClick` action removes something
**success** - when `onClick` action adds something

will render next story:

Have a look on this REAMDE and live story exmaple.

More examples at this example stories to learn more about the withReadme and withDocs API.

linshuizhaoying/storybook-readme