Storybook Docs

迁移指南：此页面记录了最近在 5.3.0 中引入的 Storybook 配置方法，如果您想迁移到这种配置 Storybook 的格式，请参阅迁移指南。

Storybook Docs 将您的 Storybook 故事转换为世界一流的组件文档。

DocsPage。 开箱即用，您的所有故事都会获得一个 DocsPage。DocsPage 是您的组件故事、文本描述、docgen 注释、props 表格和代码示例的零配置聚合，生成干净、易读的页面。

MDX。 如果您想要更多控制权，MDX 允许您在一个文件中编写长篇 markdown 文档和故事。您也可以使用它来编写纯文档页面，并将其与您的故事一起嵌入到 Storybook 中。

就像 Storybook 一样，Docs 支持所有主要的视图层，包括 React、Vue、Angular、HTML、Web Components、Svelte 等等。

继续阅读以了解更多信息

Storybook Docs

DocsPage

当您安装 Docs 后，每个故事都会获得一个 DocsPage。DocsPage 从您的故事、组件、源代码和故事元数据中提取信息，构建出合理的零配置默认文档。

点击 Docs 标签查看

有关其工作原理的更多信息，请参阅DocsPage 参考。

MDX

MDX 是一种语法，用于在同一文件中并排编写长篇文档和故事。与开箱即用提供智能文档的 DocsPage 不同，MDX 让您完全控制您的组件文档。

这是一个示例文件

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Checkbox } from './Checkbox';

<Meta title="MDX/Checkbox" component={Checkbox} />

# Checkbox

With `MDX` we can define a story for `Checkbox` right in the middle of our
markdown documentation.

<Canvas>
  <Story name="all checkboxes">
    <form>
      <Checkbox id="Unchecked" label="Unchecked" />
      <Checkbox id="Checked" label="Checked" checked />
      <Checkbox appearance="secondary" id="second" label="Secondary" checked />
    </form>
  </Story>
</Canvas>

这是它在 Storybook 中的渲染效果

有关 MDX 的更多信息，请参阅MDX 参考。

框架支持

Storybook Docs 支持 Storybook 支持的所有视图层，目前除了 React Native。还有一些框架特定的功能，例如 props 表格和内联故事渲染。此图表显示了当前的支持状态

	React	Vue	Angular	Ember	Web Components	HTML	Svelte	Preact	Riot	Mithril	Marko
MDX 故事	+	+	+	+	+	+	+	+	+	+	+
CSF 故事	+	+	+	+	+	+	+	+	+	+	+
StoriesOf 故事	+	+	+	+	+	+	+	+	+	+	+
源码	+	+	+	+	+	+	+	+	+	+	+
笔记 / 信息	+	+	+	+	+	+	+	+	+	+	+
Props 表格	+	+	+	+	+
Props 控制	+	+	+
描述	+	+	+	+	+
内联故事	+	+	+		+	+

注意： # = WIP 支持 (正在进行)

想为您喜爱的框架添加增强功能？请查看此开发者指南

安装

首先添加包。确保您的 @storybook/* 包版本匹配

yarn add -D @storybook/addon-docs

Docs 依赖于 react 和 babel-loader。如果您想用 MDX 编写故事，您可能也需要添加这些依赖。

yarn add -D react babel-loader

然后将以下内容添加到您的 .storybook/main.js

module.exports = {
  stories: ['../src/**/*.stories.@(js|mdx)'],
  addons: ['@storybook/addon-docs'],
};

如果与 storyshots 插件一起使用，您将需要配置 Jest 将 MDX 故事转换为 Storyshots 可以理解的内容

将以下内容添加到您的 Jest 配置中

{
  "transform": {
    "^.+\\.[tj]sx?$": "babel-jest",
    "^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx"
  }
}

请务必查看框架特定的安装需求

预设选项

addon-docs 预设有一些配置选项可用于配置其 babel/webpack 加载行为。这是一个如何使用带选项预设的示例

module.exports = {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        configureJSX: true,
        babelOptions: {},
        sourceLoaderOptions: null,
        transcludeMarkdown: true,
      },
    },
  ],
};

当您在 MDX 中编写文档，并且项目中的 babel 配置尚未设置好处理 JSX 文件时，configureJSX 选项很有用。babelOptions 是在使用 configureJSX 时进一步配置 babel 处理程序的一种方法。

sourceLoaderOptions 是一个用于配置 @storybook/source-loader 的对象。当设置为 null 时，它告诉 docs 完全不运行 source-loader，这可以作为一种优化，或者如果您已经在 main.js 中使用了 source-loader。

transcludeMarkdown 选项允许 mdx 文件导入 .md 文件并将其渲染为组件。

import { Meta } from '@storybook/addon-docs/blocks';
import Changelog from '../CHANGELOG.md';

<Meta title="Changelog" />

<Changelog />

手动配置

我们建议使用预设，它应该开箱即用。如果您不想使用预设，并更喜欢“繁琐的”配置方法，请将以下配置添加到 .storybook/main.js（参阅行内注释了解解释）

const createCompiler = require('@storybook/addon-docs/mdx-compiler-plugin');

module.exports = {
  // 1. register the docs panel (as opposed to '@storybook/addon-docs' which
  //    will configure everything with a preset)
  addons: ['@storybook/addon-docs/register'],
  // 2. manually configure webpack, since you're not using the preset
  webpackFinal: async (config) => {
    config.module.rules.push({
      // 2a. Load `.stories.mdx` / `.story.mdx` files as CSF and generate
      //     the docs page from the markdown
      test: /\.(stories|story)\.mdx$/,
      use: [
        {
          loader: 'babel-loader',
          // may or may not need this line depending on your app's setup
          options: {
            plugins: ['@babel/plugin-transform-react-jsx'],
          },
        },
        {
          loader: '@mdx-js/loader',
          options: {
            compilers: [createCompiler({})],
          },
        },
      ],
    });
    // 2b. Run `source-loader` on story files to show their source code
    //     automatically in `DocsPage` or the `Source` doc block.
    config.module.rules.push({
      test: /\.(stories|story)\.[tj]sx?$/,
      loader: require.resolve('@storybook/source-loader'),
      exclude: [/node_modules/],
      enforce: 'pre',
    });
    return config;
  },
};

您还需要在 .storybook/preview.js 中设置 docs 参数。这包括用于渲染页面的 DocsPage、一个容器以及各种配置选项，例如用于手动提取组件描述的 extractComponentDescription

import { addParameters } from '@storybook/react';
import { DocsPage, DocsContainer } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    container: DocsContainer,
    page: DocsPage,
  },
});

TypeScript 配置

自 SB6 以来，TypeScript 已实现零配置，并且应该与 SB Docs 开箱即用。有关高级配置选项，请参阅Props 文档。