Storybook README 插件

注意：此 README 仅适用于版本 ^5.0.0。对于旧版本，请参阅 LEGACY_README.md

所有之前的 api 在 ^5.0.0 及更高版本中应能正常工作。但 Vue 用户需要更改其导入路径，因为 Vue 命令已移至其自己的文件夹。

Storybook README addon

此插件兼容

Storybook for React（React 示例 Storybook）
Storybook for Vue（Vue 示例 Storybook）

实时演示

功能特性

自动生成 props 表格（仅支持 React）
不影响 story function。因此 Storybook Info 现在可以正常工作。
100% Markdown 支持
代码高亮
支持多个 README（对于 hoc component 很有用 - 添加组件和原始组件的 README）
看起来像 Github 的 README
支持 Vue 组件的 <docs/> 标签（example-vue/components/MyButton/MyButton.vue）。

这也非常有用，因为大多数项目和组件已经有 README.md 文件。现在很容易将它们添加到您的 Storybook 中。

如果安装了 Storybook Info Addon，则 stories 将使用 .addWithInfo 方法添加。

安装

npm install --save-dev storybook-readme

或

yarn add --dev storybook-readme

React Storybook 的 Webpack 配置

无需操作 :)

Vue Storybook 的 Webpack 配置

仅在使用 Single File Components 并希望在 Storybook 文档中使用 <docs> 标签时需要。

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

在 Vue 模块中定义 <docs> 标签

<docs>
Docs inside vue module 
</docs>

<template>
  <button class="button">
    <slot></slot>
  </button>
</template>

使用它在 story 中定义文档

import MyButton from '../components/MyButton/MyButton.vue';

storiesOf('Vue <docs>', module).addParameters({
  readme: {
    content: MyButton.__docs,
  },
});

设置

在 .storybook/addons.js 中注册插件

import 'storybook-readme/register';

在 .storybook/config.js 中添加 decorator

import { addReadme } from 'storybook-readme';
addDecorator(addReadme);

重要 5.0 版本变更： 此插件的核心命令现在根据您使用的框架从不同位置导入。例如，React 将从主文件夹导入其命令，如上所示，与 v4.0 中相同。而 Vue 现在则有其特定的导入位置。详见下方

import { addReadme } from 'storybook-readme/vue'; // <---- Vue subpackage
addDecorator(addReadme);

用法

希望这非常简单。

import React from 'react';
import { storiesOf } from '@storybook/react';

import Button from '../components/Button';
import ButtonReadme from '../components/Button/README.md';

storiesOf('Buttons', module)
  .addDecorator(withKnobs)
  .addParameters({
    readme: {
      // Show readme before story
      content: ButtonReadme,
      // Show readme at the addons panel
      sidebar: ButtonReadme,
    },
  })
  .add('Button', () => <Button />);

可以覆盖 story 的文档

import React from 'react';
import { storiesOf } from '@storybook/react';

import Button from '../components/Button';
import ButtonReadme from '../components/Button/README.md';

storiesOf('Buttons', module)
  .addDecorator(withKnobs)
  .addParameters({
    readme: {
      content: ButtonReadme,
      sidebar: ButtonReadme,
    },
  })
  .add('Button', () => <Button />)
  .add('Button', () => <Button />)
  .add('Button', () => <Button />, {
    readme: {
      // override docs
      content: CustomButtonReadme,
      sidebar: CustomButtonReadme,
    },
  });

完整选项列表

将应用于一系列 stories。

.addParameters({
    readme: {
      /**
       * Accepts string (markdown) or array of strings
       * string | Array<string>
       */
      content: Readme,

      /**
       * Accepts string (markdown) or array of strings
       * string | Array<string>
       */
      sidebar: Readme,

      /**
       * Override theme values
       *
       * All theme values https://github.com/tuchk4/storybook-readme/blob/master/packages/storybook-readme/src/styles/githubMarkdownCss.js#L436
       */
      theme: {},

      /**
       * Highlightjs code theme
       * Import theme at _.storybook/config.js_.
       * Full list of theme https://highlightjs.org/static/demo/.
       */
      codeTheme: 'github',

      /**
       * Wrapper for story. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      StoryPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for hedaer docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      HeaderPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for footer docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      FooterPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for content and sidebar docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      DocPreview: ({ children}) => <div>{children}</div>
    },
  })

全局配置

将应用于所有 stories。注意：global configuration 仅应用于内容文档（围绕 story 的文档）。

import { configureReadme } from 'storybook-readme';

configureReadme({
  /**
   * Wrapper for story. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  StoryPreview: ({ children }) => <div>{children}</div>,

  /**
   * Wrapper for content and sidebar docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  DocPreview: ({ children }) => (
    <div style={{ background: '#000' }}> {children}</div>
  ),

  /**
   * Wrapper for hedaer docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  HeaderPreview: ({ children }) => (
    <div style={{ background: 'red' }}>{children}</div>
  ),

  /**
   * Wrapper for footer docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  FooterPreview: ({ children }) => <div>{children}</div>,

  /**
   * Header docs in markdown format
   */
  header: '',

  /**
   * Footer docs in markdown format
   */
  footer: '',
});

README 占位符

 是 story 的占位符
 是 props 表格的占位符

Button variants could be imported separately.

\`\`\`js import { OutlinedButton, ContainedButton, TextButton } from 'Button'; \`\`\`

<!-- PROPS -->

Example:

<!-- STORY -->

Some docs after story

表情符号

使用冒号之间的短代码将表情符号插入文档中。例如

这是一个火箭 :rocket

可以在 Emojipedia 或 Gist/rxaviers 找到所有短代码列表

:rocket
:grinning
:monkey

欢迎随时提出新功能建议或报告 bug :)

制作人

beyondghx

标签

如何安装插件创建插件