Storybook项目中的MDX文档编写指南

最新推荐文章于 2025-06-12 09:09:29 发布

原创最新推荐文章于 2025-06-12 09:09:29 发布 · 352 阅读

3 ·

CC 4.0 BY-SA版权

Storybook项目中的MDX文档编写指南

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

什么是MDX文档

MDX是一种将Markdown与JavaScript/JSX结合的混合格式，能够创建丰富的交互式文档。在Storybook项目中，MDX文档成为组件文档化的强大工具，它允许开发者：

使用Markdown的简洁语法编写文档内容
嵌入使用组件故事格式(CSF)定义的故事
在文档任意位置插入JSX组件块
创建纯文档页面并与故事一起展示

MDX文档的核心优势

1. 格式分离，各司其职

Storybook推荐将组件文档分为两种格式：

CSF格式：专注于定义组件各种状态的故事示例
MDX格式：专注于编写结构化文档和交互式内容

这种分离充分发挥了各自格式的优势：CSF简洁高效，适合定义故事；MDX灵活强大，适合编写文档。

2. 丰富的交互能力

MDX文档不仅支持静态内容，还可以：

直接嵌入React组件
使用Storybook提供的Doc Blocks组件库
创建自定义的交互式文档组件

基础MDX文档结构

让我们通过一个Checkbox组件的例子来了解MDX文档的基本结构：

{/* 注释使用JSX块包裹JS注释 */}

import { Meta, Story } from '@storybook/blocks';
import { Checkbox } from './Checkbox';
import * as CheckboxStories from './Checkbox.stories';

<Meta of={CheckboxStories} />

# Checkbox组件文档

这是一个复选框组件，支持多种状态...

<Story of={CheckboxStories.Primary} />

对应的CSF故事文件(Checkbox.stories.js)：

import { Checkbox } from './Checkbox';

export default {
  title: 'Components/Checkbox',
  component: Checkbox,
};

export const Primary = {
  args: {
    label: '复选框',
    checked: true,
  },
};

关键组成部分详解

1. Meta块

<Meta>块定义了文档在Storybook侧边栏中的位置：

<Meta of={CheckboxStories} />

重要提示：

of属性应引用故事文件的默认导出，而不是组件本身
可使用name属性自定义侧边栏节点名称
使用title属性可自定义导航层级路径

2. 内容编写

MDX支持标准Markdown语法，可以：

使用标题、列表、代码块等常见元素
通过插件支持表格、脚注等扩展语法
自由混合Markdown和JSX内容

3. 故事嵌入

使用<Story>块可以嵌入定义好的组件故事：

<Story of={CheckboxStories.Primary} />

高级文档配置

1. 自定义文档位置

在Storybook配置文件中启用MDX支持：

// .storybook/main.js
export default {
  stories: [
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    '../src/**/*.mdx',
  ],
};

2. 独立文档页面

可以创建不绑定特定故事的纯文档：

# 项目指南

这里是项目使用指南内容...

无需Meta块，Storybook会根据文件位置自动生成导航

3. 多组件文档

单个MDX文件中可以引用多个组件：

import * as ButtonStories from './Button.stories';
import * as CheckboxStories from './Checkbox.stories';

# 表单组件

## 按钮
<Story of={ButtonStories.Primary} />

## 复选框
<Story of={CheckboxStories.Primary} />

常见问题解决

1. 表格渲染问题

如果Markdown表格无法正确显示，需要配置remark-gfm插件：

// .storybook/main.js
export default {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [require('remark-gfm')],
          },
        },
      },
    },
  ],
};