使用 Storybook MDX 创建丰富的文档

Storybook 是 UI 组件开发的标准工具。它被用于构建网络上最流行的设计系统，包括 Shopify Polaris、IBM Carbon、Salesforce Lightning、Auth0 Cosmos 和 Airbnb Lunar。

像这样的高质量文档对于帮助人们复用你的 UI 组件至关重要，但要做好也非常痛苦。实际上，你花费在维护文档系统上的时间比实际编写文档的时间还要多！

这就是为什么 Storybook 致力于使 UI 组件文档快速且简单。我们的第一步是 DocsPage，一个可以根据你现有 stories 自动生成最佳实践文档的工具。

今天我很高兴地宣布 Storybook 中快速、完全定制化的文档功能，由 MDX 提供支持，并已在 Storybook 5.3 中可用！🎉

MDX 使你能够使用自己的组件、混合搭配 DocBlocks，并让非技术团队成员参与进来，自定义 Storybook 自动生成的文档。所有这些都可以在舒适的 Markdown 环境中完成。

• 🎨 可定制的文档：轻松创建完全定制化的文档。
• 📦 现成的构建块：复用 Storybook 强大的 DocBlocks。
• 🤝 共同编写文档：对开发者强大，对设计师和产品经理友好
• 🔌 100% 兼容：无需配置即可无缝集成 Storybook

💡 为什么这很重要？

今年早些时候，团队提出了一个重塑组件文档的宏大愿景。我们的第一个里程碑是 Storybook 5.2，它引入了DocsPage，可以从现有 stories 自动生成最佳实践 UI 文档。

Storybook Docs 如火箭般腾飞，在短短几周内成为最受欢迎的文档工具之一（按 npm 下载量衡量）！但即使团队都接受了 DocsPage，编写完全自定义文档的需求依然明确。

Storybook MDX 为组件作者提供了灵活性、简洁性和易用性之间的无与伦比的平衡。MDX 是一种开放的、可创作的格式，它在同一个文件中流畅地交织了 Markdown 和 JSX 组件。这使得将现成的构建块（如调色板、排版示例和属性表）组合成长篇文档变得容易。

更重要的是，直接的 MDX 创作体验意味着设计师、产品经理以及任何熟悉 Markdown 的人都可以为共享的 UI 文档做出贡献。大胆的预发布用户已经将 Storybook 用作其组件库和设计系统的单一事实来源。

Storybook MDX 是我梦想中的文档系统。我保留了 Storybook 备受喜爱的“Canvas”的强大功能和灵活性，但现在有了一种成熟的方式来编写美观且可移植的长篇文档，真正触及我们设计系统的核心。— Vince Speelman，TEDtalks 前端工程师

📝 MDX 简化文档编写

Storybook 5.3 的关键新增功能是 MDX 支持。MDX（“组件时代的 Markdown”）是一个基础项目，它将 Markdown 与嵌入的 JSX 组件流畅地混合。一个 MDX story 示例如下：

你可能识别出 Markdown 的部分，例如 # Badge, Let's define 和 We can even 等代码块。还有一些 JSX 元素：

• Meta 是一个将你的组件定位在 Storybook 中的元素。
• Story 定义一个新的 story（或引用现有的 story）。
• Preview 包围一个（或多个）story，并显示其源代码。

这些 DocBlocks 构成了 Storybook MDX 的基础。我们将在下一节介绍更多。

但在此之前，让我们先看一个完整的示例：REAVIZ，一个在 Storybook 中构建和文档化的 React 可视化库。它在一个 Storybook 中展示了主题化、静态 Markdown 页面、自定义 MDX 和 DocsPage。

📦 复用 Storybook 的现成构建块

除了渲染 stories 外，还很有用的是包含其他设计系统文档，例如属性表、调色板和排版。

我们为组件的 API 精心制作了一个属性表 DocBlock。

<Props of={AvatarList} />

当应用于 React 组件时，它会显示每个属性的名称、描述、类型和默认值。

Patrick Lafrance & Francis Thibault 为此付出了心血。当应用于其他框架时——例如 Aaron Pool & Shota Fuji 的 Vue / Kai Röder 的 Angular / Thomas Allmer 的 Web components / Matthew Irish 的 Ember——属性表被划分为输入、输出、插槽、事件等部分。更多详情将在另一篇文章中公布！😘

在 Storybook MDX 中记录你的样式也很容易。开箱即用地提供调色板、图标系统和排版。未来，基于 Philipp Siekmann 在 storybook-design-token 方面的出色工作，你将获得与不同设计令牌源更紧密的集成。

# Colors

<ColorPalette>
  <ColorItem
    title="theme.color.greyscale"
    subtitle="Some of the greys"
    colors={['#FFFFFF', '#F8F8F8', '#F3F3F3']}
  />
  ...
</ColorPalette>

# Icons

<IconGallery>
  <IconItem name="add"><ExampleIcon icon="add" /></IconItem>
  ...
</IconGallery>

# Typography

<Typeset fontSizes={['12px', '14px', ...]} sampleText="Heading" />

Storybook Docs 为我们所有的组件提供了人类可读的文档。MDX 降低了复杂性，并使组织内的所有部门都能参与到讨论中来。— Sean Luo，Kickstarter 软件工程师

🤝 面向整个团队的 UI 文档

Storybook 最初是一个用于组织、开发、文档化和测试组件的开发工具。随着其越来越受欢迎，团队开始将 Storybook 用作设计师、产品经理和 QA 的共享资源。

有了 MDX，非技术团队成员现在可以帮助更新共享的 UI 文档。这使得你的团队成员参与进来，并减少了你的维护工作。这是一个双赢的局面，为 Storybook 更好地支持跨职能协作开启了新的方向。

🔌 与生态系统的无缝集成

Storybook MDX 与 Storybook 生态系统的其余部分 100% 兼容。

凭借 Storybook MDX 带来的所有功能，你可能会猜测将其与 Storybook 庞大的原型设计、评审、测试、文档化和协作工具与服务生态系统的其余部分集成会是一个挑战。幸运的是，你错了！

今年早些时候，我们引入了 Component Story Format (CSF)，这是一个基于 ES6 模块导出的组件示例开放标准。CSF 是 Storybook 的基础。在底层，我们的 MDX stories 被透明地编译成 CSF。这意味着任何可以加载 CSF 的工具也可以加载 Storybook MDX，无需额外的集成工作。

我们已经通过向 Storybook 本身添加一个 webpack loader 来证明这一点，并向 Storyshots（我们的开源 DOM 快照库）添加一个 Jest transformer 来证明与 Jest 的兼容性。像 Chromatic 这样的云服务也在第一时间内置了对 MDX 的完全支持。

⚡️ 1 分钟安装

想要使用吗？首先将你的项目升级到 Storybook 5.3

npx npm-check-updates '/storybook/' -u
npm install # or yarn if you prefer

然后向现有项目添加文档

npm install @storybook/addon-docs --save-dev # or yarn

最后，将以下行添加到你的 .storybook/main.js 文件中

module.exports = {
  addons: ['@storybook/addon-docs'];
}

有关配置 MDX 的更多信息，请阅读安装说明。

🚀 我们需要你的帮助来改进文档功能

最简单的帮助方式是在你的项目中安装 Storybook 5.3–rc，并在我们的 GitHub 项目中提问和/或提交 bug。如果你发现并能修复 bug，我们欢迎所有贡献！

此外，我们还有很多正在进行的工作

• 我们正在扩展对更多框架的增强文档支持。Storybook 5.2 支持 React，5.3 支持 Vue/Angular/Web Components/Ember。在你的帮助下，我们很乐意添加 Svelte 和其他框架。
• 我们正在创建一个丰富的 DocBlocks 库，例如组件的 GitHub 贡献者头像、组件状态徽章等。
• 最后，我们还希望能够将 Storybook 文档嵌入到其他文档系统，例如 Gatsby。

如果你对其中任何一项协作感兴趣，或者只是想了解最新动态，项目社区主要活跃在我们 Discord 的 #docs-mode 频道。

🙏 感谢社区

Storybook Docs 由以下团队开发：Michael Shilman (me!), Atanas Stoyanov, Patrick Lafrance, Francis Thibault, Aaron Pool, Shota Fuji, Kai Röder, Tom Coleman, Norbert de Langen, Lionel Benychou, Matthew Irish, Thomas Allmer, 和 Igor Davydkin。设计与主题化由 Dominic Nguyen 完成。特别感谢 MDX 的早期使用者 Austin McDaniel, Vince Speelman, Kevin Suttle, Alex Wilson, 和 Tom Speak。衷心感谢 Brad Frost 在设计系统项目方面提供的指导。🙌

如果 Storybook 让你的 UI 开发者工作流程更轻松，请帮助 Storybook 变得更好。你可以贡献新功能、修复 bug 或改进文档。加入我们的 Discord，在 Open Collective 上支持我们，或者直接参与 GitHub 项目。