miguelcast/storybook-readme

React Storybook addon to render README files in github style

Storybook README addon

This addon is compatible with:

• Storybook for React (React example storybook)
• Storybook for Vue (Vue example storybook)

Live demo

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
• Supports <docs/> tags for vue components (example-vue/components/MyButton/MyButton.vue).

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

or

yarn add --dev storybook-readme

Webpack Configuration for React Storybook

There is no additional webpack configuration if using with @storybooks/[email protected].

For lower versions use:

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

Webpack Configuration for Vue Storybook

Only if using Single File Components and want to use <docs> tag at storybook documentation.

module.exports = storybookBaseConfig => {
  storybookBaseConfig.module.rules.push({
    resourceQuery: /blockType=docs/,
    use: [
      'storybook-readme/env/vue/docs-loader',
      'html-loader',
      'markdown-loader',
    ],
  });
};

Usage

Register addon at .storybook/addons.js

import 'storybook-readme/register';

Then create your stories with the withReadme or withDocs API (use as story HOC or as Storybook Decorator).

• withDocs - Add README around the story component at the main panel. Example withDocs
• withReadme - Add README to the storybook panels. Example withReadme
• doc - Add README instead of component preview. Example doc

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

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

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>)
);

// with custom preview element
const withCustomPreview = withDocs({
  // it is easy with styled-components
  PreviewComponent: styled.div`
    text-align: center;
    padding: 25px;
    box-shadow: 0 0 40px rgba(0, 0, 0, 0.1);
  `,
  FooterComponent: ({ children }) => {
    return (
      <div
        style={{
          padding: '25px',
          background: 'rgba(246, 255, 0, 0.23)',
          borderTop: '2px solid rgba(0, 0, 0, 0.1)',
        }}
      >
        {children}
      </div>
    );
  },
});

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

Use as Higher Order Component

• withReadme(readme, story)
• withDocs(readme, story) or withDocs({ PreviewComponent, FooterComponent })(readme, story)
• doc(readme)

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" />;
    })
  );

doc example:

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

storiesOf('ButtonDoc', module).add('Docs', doc(ButtonREADME));

Use as Decorator

• withReadme(readme)
• withDocs(readme) or withDocs({ PreviewComponent, FooterComponent })(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.addFooterDocs(DocsFooterReadme);

Custom Story Layout

Right now only for React storybooks. Take a look on this [Example].(https://tuchk4.github.io/storybook-readme/?selectedKind=Marked&selectedStory=Marked1&full=0&addons=1&stories=1&panelRight=1&addonPanel=storybooks%2Fstorybook-addon-knobs)

import Marked from 'storybook-readme/components/Marked';
import ButtonReadme from './ButtonReadme.md';

storiesOf('Custom Layout', module).add('Button', () => {
  return (
    <React.Fragment>
      <Button label="Button before intro" />
      <Marked md={'### INTRO '} />

      <Button label="Button after intro" />
      <Marked md={ButtonReadme} />

      <Button label="Button before outro" />
      <Marked md={'### OUTRO '} />
    </React.Fragment>
  );
});

README splitter (only for withDocs API)

You can use <!-- STORY --> at the README to control component story position. For example:

Docs before story

<!-- STORY -->

Docs after story

Have a look on this README and live story exmaple.

Take a look at more examples at packages/example-react/stories/index.js to learn more about the withReadme and withDocs API.