MDX

观看视频教程

MDX 文件混合使用 Markdown 和 Javascript/JSX 来创建丰富的交互式文档。您可以使用 Markdown 易读的语法（例如 # 标题）编写文档，包含在组件故事格式 (CSF) 中定义的故事，并在文件的任何位置自由嵌入 JSX 组件块。一次性完成所有操作。

此外，您可以在 MDX 中编写纯文档页面，并将其与故事一起添加到 Storybook 中。

MDX simple example result

Storybook 8 中已移除直接在 MDX 中编写故事的功能，并且我们不再支持它。请参阅之前的文档以获取有关该功能的指南，或迁移到新格式。

基本示例

让我们从一个示例 Checkbox.mdx 开始，它将 Markdown 与单个故事结合起来。

{/* Checkbox.mdx */}
 
import { Canvas, Meta } from '@storybook/blocks';
 
import * as CheckboxStories from './Checkbox.stories';
 
<Meta of={CheckboxStories} />
 
# Checkbox
 
A checkbox is a square box that can be activated or deactivated when ticked. 
 
Use checkboxes to select one or more options from a list of choices.
 
<Canvas of={CheckboxStories.Unchecked} />

此 MDX 文件引用了一个故事文件 Checkbox.stories.js|ts，该文件使用组件故事格式 (CSF) 编写。

Checkbox.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Checkbox } from './Checkbox';
 
const meta: Meta<typeof Checkbox> = {
  component: Checkbox,
};
 
export default meta;
type Story = StoryObj<typeof Checkbox>;
 
export const Unchecked: Story = {
  args: {
    label: 'Unchecked',
  },
};

以下是 Storybook 中的渲染方式

MDX simple example result

这里有很多内容。我们正在编写 Markdown，我们正在编写 JSX，我们还在定义和引用 Storybook 故事，这些故事与整个 Storybook 生态系统完全兼容。

让我们分解一下。

MDX 和 CSF

首先要注意的是，组件文档被划分为不同的格式：一种用于编写描述每个可能组件状态的组件故事，另一种用于记录如何使用它们。这种拆分利用了每种格式的最佳特性。

CSF 非常适合简洁地定义故事（组件示例）。如果您使用 TypeScript，它还提供类型安全性和自动完成功能。
MDX 非常适合编写结构化文档并将其与交互式 JSX 元素组合。

MDX 的结构

假设您已经熟悉使用 CSF 编写故事，我们可以更详细地剖析 MDX 方面的内容。

文档由多个块组成，这些块用空行分隔。由于 MDX 将几种不同的语言混合在一起，因此它使用这些空行来帮助区分一个块的开始和下一个块的开始。如果块之间没有用空格分隔，可能会导致（有时是神秘的）解析错误。

按顺序浏览代码块

{ /* Checkbox.mdx */ }

MDX 中的注释是包含 JS 注释的 JSX 块。

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

导入将在整个文件中 JSX 中使用的组件和故事。

{/* Checkbox.mdx */}
 
import { Meta } from '@storybook/blocks';
 
import * as CheckboxStories from './Checkbox.stories';
 
<Meta of={CheckboxStories} />

当为 Meta 块提供 of 属性时，请确保您正在引用故事文件的 默认导出，而不是组件本身，以防止生成的文档出现渲染问题。

Meta 块定义了文档将在侧边栏中的位置。在本例中，它位于 Checkbox 的故事旁边。默认情况下，文档侧边栏节点的标题为 "Docs"，但可以通过传递 name 属性进行自定义（例如，<Meta of={CheckboxStories} name="Info" />）。如果您想在导航层次结构中的任意位置放置文档节点，可以使用 title 属性（例如，<Meta title="path/to/node" />）。

# Checkbox
 
A checkbox is a square box that can be activated or deactivated when ticked.
 
Use checkboxes to select one or more options from a list of choices.

MDX 默认支持标准 Markdown（"commonmark"），并且可以扩展以支持 GitHub Flavored Markdown (GFM) 和其他扩展（请参阅故障排除部分以了解有关某些当前限制的更多信息）。

{/* Checkbox.mdx */}
 
import { Canvas } from '@storybook/blocks';
 
import * as CheckboxStories from './Checkbox.stories';
 
<Canvas of={CheckboxStories.Unchecked} />

最后，MDX 支持任意 JSX 块。

在本例中，我们正在利用“文档块”，这是一个文档组件库，旨在与 Storybook 故事一起使用，以显示您的故事、组件 API 和用于在文档中与组件交互的控件，以及其他实用程序。

除了文档块之外，MDX 还可以包含任意 React 组件，使其成为一个非常灵活的文档系统。假设您希望为组件提供一个风格化的“注意事项”列表；您可以使用现成的组件或编写自己的组件。

{/* Guideline.mdx */}
 
<Guidelines>
  <Dos>
    - Use buttons for the main actions on your page 
    - Identify the primary action and make it `primary`
  </Dos>
  <Donts>
    - Use a button when a link will do (e.g., for navigation-only actions) 
    - Use multiple `primary` buttons in a single UI state
  </Donts>
</Guidelines>

已知限制

虽然 MDX 支持各种运行时（React、Preact、Vue），但 Storybook 的实现仅限于 React。这意味着您的文档在 React 中呈现，而您的故事则在您选择的运行时中呈现（React、Vue、Angular、Web Components、Svelte 等）。

设置自定义文档

此外，除了使用 MDX 为组件编写文档外，您还可以扩展它来编写其他类型的內容，例如有关如何使用组件的指南或最佳实践。要使用此格式为您的故事启用自定义文档，请首先更新您的 Storybook 配置文件（例如，.storybook/main.js|ts|cjs）。

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
  framework: '@storybook/your-framework',
  stories: [
    //👇 Your documentation written in MDX along with your stories goes here
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: ['@storybook/addon-essentials'],
};
 
export default config;

创建 MDX 文件以添加您的自定义文档。根据您希望文档在 UI 中的呈现方式，您需要考虑以下用例。

使用 `Meta` 文档块

如果您需要将组件文档与现有故事匹配，则可以配置 Meta 文档块来控制文档的呈现方式。默认情况下，它允许您定义自定义标题或您需要记录的故事的引用（即，通过 of 属性）。例如

此代码段在 React 中不存在。

{/* Button.mdx */}
 
import { Meta, Controls } from '@storybook/blocks';
 
<Meta title="Button" />
 
# Definition
 
Button is a clickable interactive element that triggers a response.
 
You can place text and icons inside of a button.
 
Buttons are often used for form submissions and to toggle elements into view.
 
## Usage
 
The component comes in different variants such as `primary`, `secondary`, `large` and `small` which you can use to alter the look and feel of the button.
 
## Inputs
 
Button has the following properties:
 
<Controls />

编写未关联的文档

假设您正在记录一个现有组件，并且仅提供 Meta 文档块而没有其他属性或其他块。在这种情况下，Storybook 会将其视为“未关联”文档，或者换句话说，是“仅文档”页面，并且它会在侧边栏导航菜单中以不同的方式呈现它。

{/* ExampleDocumentation.mdx */}
 
import { Meta } from '@storybook/blocks';
 
import * as ExampleComponentStories from './ExampleComponent.stories';
 
{/* 👇 Documentation-only page */}
 
<Meta title="Documentation" />
 
{/* 👇 Component documentation page */}
 
<Meta of={ExampleComponentStories} />

MDX docs only story

使用文件系统

但是，在某些用例中，例如独立页面，甚至作为测试组件的指南，可能不需要提供 Meta 文档块。在这种情况下，您可以安全地省略它。Storybook 将改为依靠文件的物理位置将文档放置在侧边栏中，并用您自己的文档覆盖任何预先存在的自动生成的文档。例如

此代码段在 React 中不存在。

{/* src/components/Select.mdx */}
 
# Select
 
Select is a type of input that allows users to choose one or more options from a list of choices. 
 
The options are hidden by default and revealed when a user interacts with an element. 
 
It shows the currently selected option in its default collapsed state.
 
## Design implementation
 
To help users get acquainted with the existing UI elements, it is recommended to use check the Figma file to see how the select input is implemented.
 
### When to use?
 
In a select input where there are less than 3-4 items, consider using radio boxes, or radio inputs instead. 
 
### How to use?
 
To help users understand the options available in a select input, include a default option that is unselectable and acts as a label.

如果您要覆盖通过 tags 配置属性启用的现有自动生成文档页面，我们建议将其删除以避免错误。

加载自定义 MDX 文档后，Storybook 将使用相同的启发式规则推断标题和位置以生成自动标题故事并在侧边栏中将其呈现为 Docs 条目。

使用独立文档页面

编写独立文档页面是一个常见的用例，它不仅适用于每个组件，也适用于每个项目。例如，您可能希望记录项目的入门流程，其中包含使用该项目的说明。为此，您可以创建一个包含文档的新 MDX 文件，使用类似的结构和内容。

{/* src/GettingStarted.mdx */}
 
# Getting Started
 
Welcome! Whether you're a designer or a developer, this guide will help you get started and connect you to the essential resources you need.
 
## Table of Contents
 
- [Design Resources](#design-resources)
  - [Figma](#figma)
  - [UI/UX Design Guidelines](#uiux-design-guidelines)
  - [Design Assets](#design-assets)
 
- [Development Resources](#development-resources)
  - [Coding Standards](#coding-standards)
  - [Version Control](#version-control)
  - [Development Tools](#development-tools)
 
---
 
## Design Resources
 
### Figma
 
[Figma](https://www.figma.com/) is a collaborative design and prototyping tool. It's the heart of the design process, allowing designers to work together seamlessly.
 
- **Get Access**: If you're not already part of the Figma project, request access from the project lead or manager.
 
### UI/UX Design Guidelines
 
Before you dive into designing, familiarize yourself with our UI/UX design guidelines. They provide valuable insights into our design philosophy and standards.
 
- [UI/UX Guidelines Document](https://your-design-guidelines-link.com)
 
### Design Assets
 
All the essential design assets like logos, icons, and brand guidelines can be found in the Figma project. Ensure you have access and familiarize yourself with these assets for consistency.
 
---
 
## Development Resources
 
### Coding Standards
 
Maintaining a consistent code style is essential for collaborative development. Our coding standards document will guide you on best practices.
 
- [Coding Standards Document](https://your-coding-standards-link.com)
 
### Version Control
 
We use Git for version control. Make sure you have Git installed and are familiar with its basics.
 
### Development Tools
 
Your development environment is critical. Here are some tools and resources to help you set up your workspace:
 
- **Code Editor**: We recommend using [Visual Studio Code](https://vscode.js.cn/) for development. It's highly customizable and supports a wide range of extensions.
 
- **Package Manager**: [npm](https://npmjs.net.cn/) is the package manager we use for JavaScript projects. Install it to manage project dependencies.
 
---

MDX guidelines page

当 Storybook 加载文档时，它将使用文件的物理位置推断页面在侧边栏导航菜单中的位置，并将其呈现为 Docs 条目。

完全控制自定义文档

当应用于每个项目组件时，文档的维护和更新成本可能很高。为了简化此过程，Storybook 提供了一组有用的 UI 组件（即文档块）来帮助涵盖更高级的用例。如果您需要其他内容，请使用它们来帮助创建您的自定义文档。

{/* Button.mdx */}
 
import { Meta, Story } from '@storybook/blocks';
 
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
# Button
 
Button is a clickable interactive element that triggers a response.
 
You can place text and icons inside of a button.
 
Buttons are often used for form submissions and to toggle elements into view.
 
## Usage
 
<Story of={ButtonStories.Basic} />

使用多个组件

如果您需要在一个文档页面中记录多个组件，则可以直接在 MDX 文件中引用它们。在内部，Storybook 会查找故事元数据，并将其与您现有的文档一起组合。例如

{/* Page.mdx */}
 
import { Canvas, Meta, Story } from '@storybook/blocks';
 
import * as ListStories from './List.stories';
 
import * as ListItemStories from './ListItem.stories';
 
import * as PageStories from './Page.stories';
 
<Meta of={PageStories} />
 
# Page
 
Page is a layout container that is used to position children in predetermined areas. 
 
It's often used to apply consistent positioning for content across pages in an application
 
## Usage
 
<Canvas of={PageStories.Basic} />
 
# List
 
List is a grouping of related items. List can be ordered with multiple levels of nesting.
 
## Usage
 
<Story of={ListStories.Filled} />
 
# List Item
 
List items are used to group related content in a list. They must be nested within a List component.
 
## Usage
 
<Story of={ListItemStories.Starter} meta={ListItemStories} />

从 Markdown 生成文档

如果您需要使用 Markdown 编写的其他内容扩展文档，则可以使用 Markdown 文档块导入可用内容，Storybook 将将其与您现有的文档一起呈现。例如，如果您有一个 CHANGELOG.md 文件，您可以将其导入并在文档页面中按如下方式呈现它

{/* Changelog.mdx */}
 
import { Meta, Markdown } from "@storybook/blocks";
 
import Readme from "../../Changelog.md?raw";
 
<Meta title="Changelog" />
 
# Changelog
 
<Markdown>{Readme}</Markdown>

Markdown 文档块提供了其他配置选项来自定义文档的呈现方式。有关更多信息，请参阅 API 文档。

Changelog markdown in an MDX story

链接到其他故事和页面

改进文档的另一种方法是链接到其他故事和页面。假设您已经有了一个具有以下唯一标识符的组件故事，some--id，并且您想将其链接到您的文档页面。在这种情况下，您可以使用 path 查询字符串重定向到与故事相关的文档条目。

[Go to specific documentation page](?path=/docs/some--id)

相反，如果您需要定位特定的文档部分，则可以调整链接以指向它。例如

[Go to the conclusion of the documentation page](?path=/docs/some--id#conclusion)

但是，文档的交叉链接并不限于文档页面。如果您需要引用特定的故事，则可以调整 path 查询并提供故事的唯一标识符。例如

[Go to specific story canvas](?path=/story/some--id)

通过将此模式与 Controls 扩展程序一起应用，所有锚点都将在 Canvas 中被忽略，具体取决于 Storybook 如何处理 URL 以跟踪参数值。

故障排除

Markdown 表格无法正确渲染

如果您扩展文档以包含特定功能（例如，表格、脚注），您可能会遇到一些使用 Storybook 支持的当前 MDX 版本正确呈现它们的问题。我们建议在您的配置文件（即 remark-gfm）中启用 .storybook/main.js|ts 插件以正确呈现它们。

.storybook/main.ts

import remarkGfm from 'remark-gfm';
 
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other addons go here
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [remarkGfm],
          },
        },
      },
    },
  ],
};
 
export default config;

remark-gfm 包默认情况下不包含在 Storybook 中，必须作为开发依赖项单独安装。要了解有关如何使用它以及 MDX 引入的其他重大更改的更多信息，请参阅 MDX 团队提供的 GFM 指南和迁移指南，以获取更多信息。

npx @hipster/mdx2-issue-checker

根据数量，您可能需要多次运行该命令才能修复所有问题。

完成后，它将输出导致问题的文件列表。然后，您可以使用此信息手动修复问题。

此外，如果您使用的是 VSCode，您可以添加 MDX 扩展并通过将以下内容添加到您的用户设置中来启用 MDX 实验性支持以进行 lint、类型检查和自动完成功能

{
  "mdx.experimentalLanguageServer": true
}

如果您仍然遇到问题，我们建议您使用默认的沟通渠道（例如，GitHub 讨论）联系社区。

控件没有更新 MDX 文档页面中的故事

如果您通过 inline 配置选项关闭了故事的内联渲染，您将遇到关联控件没有更新文档页面中故事的情况。这是当前实现的一个已知限制，将在未来的版本中解决。

使用的 React 版本不符合预期

对于大多数项目，Storybook 的 addon-docs 使用项目依赖项中列出的 React 版本。如果找不到，它将使用 React 18.2.0。有两个例外

Preact 项目将始终使用 React 17
Next.js 项目将始终使用安装的 Next.js 版本附带的 canary 版本，而不管项目依赖项中列出了哪个 React 版本。

如果您在使用 React 版本时遇到问题，您可能需要重新创建项目的 node_modules 文件夹以确保使用正确的版本。

详细了解 Storybook 文档

自动文档用于为您的故事创建文档
MDX 用于自定义您的文档
文档块用于撰写您的文档
发布文档用于自动化发布文档的过程

MDX