Storybook README 插件
注意：此 README 仅适用于版本 ^5.0.0。对于旧版本，请访问 README_V4.md
所有之前的 API 应该在 ^5.0.0 及以上版本中正常工作。**但是 Vue 用户需要更改其导入路径，因为 Vue 命令已移动到其自己的文件夹中。**
此插件与以下版本兼容
功能
- 自动生成属性表（仅适用于 React）
- 100% 支持 Markdown
- 代码高亮
- 可以将文档添加到插件面板或故事周围
- 接受多个 README（对于 hoc 组件 - 添加组件和原始组件的 README）非常有用
- 看起来像 Github 的 README
- 支持 Vue 组件的
<docs/>标签（example-vue/components/MyButton/MyButton.vue）。
它也非常有用，因为大多数项目和组件已经拥有 README.md 文件。现在可以轻松地将它们添加到 Storybook 中。
如果安装了 Storybook Info Addon，则会使用 .addWithInfo 方法添加故事。
安装
npm install --save-dev storybook-readme
或
yarn add --dev storybook-readme
React Storybook 的 Webpack 配置
无需操作 :)
但是，如果您使用的是带有 React 的 Typescript，则需要在 Webpack 配置中添加 markdown-loader
{
test: /\.md$/,
use: [
{
loader: 'markdown-loader',
}
]
}
Vue Storybook 的 Webpack 配置
仅适用于使用 <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>
在故事中使用它来定义文档
import MyButton from '../components/MyButton/MyButton.vue';
storiesOf('Vue <docs>', module).addParameters({
readme: {
content: MyButton.__docs,
},
});
设置
在 .storybook/addons.js 中注册插件
import 'storybook-readme/register';
注意：可以设置插件面板标题
import registerWithPanelTitle from 'storybook-readme/registerWithPanelTitle';
registerWithPanelTitle('Docs');
在 .storybook/config.js 中添加装饰器
import { addDecorator, configure } from '@storybook/react';
import { addReadme } from 'storybook-readme';
// for Vue storybook
import { addReadme } from 'storybook-readme/vue'; // <---- vue subpackage
// for HTML storybook
import { addReadme } from 'storybook-readme/html'; // <---- html subpackage
addDecorator(addReadme);
function loadStories() {
require('../stories/index.js');
}
configure(loadStories, module);
注意：对于 HTML Storybook，仅提供侧边栏文档。
用法
希望它非常简单。
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 />);
可以覆盖故事的文档
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,
},
});
完整选项列表
将应用于一系列故事。
.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,
/**
* Enable / disable code highlighting for sidebar. true by default
*/
highlightSidebar: true,
/**
* Enable / disable code highlighting for content. true by default
*/
highlightContent: true,
/**
* Override theme values
*
* All theme values https://github.com/tuchk4/storybook-readme/blob/master/packages/storybook-readme/src/styles/githubMarkdownCss.js#L436
*/
theme: {},
/**
* Prism code theme
* Full list of theme https://github.com/PrismJS/prism-themes
* To be used with storybook-readme, naming of the code theme should be used in one of these styles. https://github.com/tuchk4/storybook-readme/tree/master/packages/storybook-readme/src/styles/prismCodeThemes
*/
codeTheme: 'github',
/**
* You can include prop tables locally here. See `propTables` example
* for more information
*/
includePropTables: [YourImportedReactComponent],
/**
* 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 header 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>
},
})
全局配置
将应用于所有故事。注意：全局配置仅应用于内容文档（故事周围的文档）。
import { addParameters } from '@storybook/react'; // or @storybook/vue for vuejs
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 header 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: '',
});
addParameters({
readme: {
// You can set a code theme globally.
codeTheme: 'github',
// You can exclude prop tables globally here. See `propTables` example
// for more information
excludePropTables: [YourImportedReactComponent],
},
});
Readme 占位符
<!-- STORY -->故事占位符<!-- SOURCE -->故事源代码占位符<!-- STORY_SOURCE -->故事源代码占位符<!-- PROPS -->属性表占位符。属性解析存在一些问题。说明 issue#137<!-- STORY HIDE START -->、<!-- STORY HIDE END -->标签包围的内容不会显示在故事中
Button variants could be imported separately.
\`\`\`js import { OutlinedButton, ContainedButton, TextButton } from 'Button'; \`\`\`
<!-- PROPS -->
Example:
<!-- STORY -->
<!-- SOURCE -->
<!-- STORY HIDE START -->
content here won't be shown in stories
<!-- STORY HIDE END -->
Some docs after story
表情符号
在冒号之间使用简码将表情符号插入文档中。例如
这是一个火箭 :rocket
这是一个火箭 :rocket
所有简码的列表可以在 Emojipedia 或 Gist/rxaviers 中找到
- :rocket
- :grinning
- :monkey
欢迎提出新功能建议或报告错误 :)
来自 v4 的 API。
之前 API 的完整文档位于 README_V4.md
太长不看版
接受 Markdown 格式的 README 或 README 数组。当您开发高阶组件并希望添加多个 README 以及原始组件文档时，多个 README 会非常有用。
withReadme
在插件面板中渲染 README。
import { withReadme } from 'storybook-readme';
import withReadme from 'storybook-readme/with-readme';
// as HigherOrder Component
storiesOf('Button', module).add(
'Default',
withReadme(ButtonReadme, () => <Button />),
);
// as Decorator
storiesOf('Button', module)
.addDecorator(withReadme(ButtonReadme))
.add('Default', () => <Button />);
withDocs
在故事周围渲染 README。
import { withDocs } from 'storybook-readme';
import withDocs from 'storybook-readme/with-docs';
// as HigherOrder Component
storiesOf('Button', module).add(
'Default',
withDocs(ButtonReadme, () => <Button />),
);
// as Decorator
storiesOf('Button', module)
.addDecorator(withDocs(ButtonReadme))
.add('Default', () => <Button />);
doc
在主框架中渲染 README，不带故事。
import { doc } from 'storybook-readme';
storiesOf('Button', module).add('Default', () => doc(ButtonReadme));
