使用 Storybook MDX 构建丰富的文档

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

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

正因如此，在 Storybook，我们下定决心让 UI 组件文档编写变得快速而简单。我们的第一步是 DocsPage，这是一个从你现有的 stories 自动生成最佳实践文档的工具。

今天，我很高兴地宣布在 Storybook 中推出快速、完全自定义的文档，它由 MDX 驱动，并在 Storybook 5.3 中可用！🎉

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

• 🎨 可自定义的文档： 完全自定义文档变得简单。
• 📦 现成的构建块： 重用 Storybook 强大的 DocBlocks。
• 🤝 共同编写文档： 对开发者来说功能强大，对设计师和 PM 来说简单易用
• 🔌 100% 兼容： 无缝 Storybook 集成，零配置

💡 有什么大不了的？

今年早些时候，团队概述了一个 雄心勃勃的愿景，重新思考组件文档。我们的第一个里程碑是 Storybook 5.2，它引入了 DocsPage 以从你现有的 stories 自动生成最佳实践 UI 文档。

Storybook Docs 像火箭一样迅速蹿红，在几周内成为最流行的文档工具之一（按 npm 下载量计算）！但即使团队接受了 DocsPage，对完全自定义文档的需求仍然很明显。

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

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

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

📝 MDX 简化了文档编写

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

你可能在诸如 # Badge、Let's define 和 We can even 等代码块中识别出 Markdown。还有一些 JSX 元素

• Meta 是一个将你的组件置于 Storybook 中的元素。
• Story 定义一个新的 story（或引用一个现有的 story）。
• Preview 框架化一个（或多个 stories）并显示其源代码。

这些 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 软件工程师 @ Kickstarter

🤝 适用于你整个团队的 UI 文档

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

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

🔌 与生态系统无缝集成

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

考虑到 Storybook MDX 带来的所有功能，你可能会认为将其与 Storybook 庞大的原型设计、评审、测试、文档和协作工具及服务生态系统的其余部分集成将是一个挑战。幸运的是，你的想法是错误的！

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

我们已经通过添加 webpack loader 在 Storybook 本身中展示了这一点，并通过为 Storyshots（我们的开源 DOM 快照库）添加 jest transformer 在 Jest 中展示了这一点。像 Chromatic 这样的云服务也在第一天就内置了完整的 MDX 支持。

⚡️ 1 分钟安装

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

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

然后将 docs 添加到现有项目

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

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

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

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

🚀 我们需要你的帮助来使 Docs 更出色

你可以提供的最简单的帮助是在你的项目中安装 Storybook 5.3–rc，并在 我们的 GitHub 项目 中提问和/或提交错误报告。如果你发现可以修复的错误，我们欢迎所有贡献！

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

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

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

🙏 感谢社区

Storybook Docs 由 Michael Shilman (我！)、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 变得更好。你可以贡献新功能、修复错误或改进文档。在 Discord 上加入我们，在 Open Collective 上支持我们，或者直接在 GitHub 上参与。