Storybook 文档页

我很高兴地宣布，DocsPage 今天在 Storybook 5.2 版本中发布。

Storybook 是事实上的 UI 组件工作台标准。它为 Airbnb、Lyft、Squarespace、Slack 和 Dropbox 的前端开发工作流程提供支持，此外还为超过 25,000 个公共 Github 项目提供支持。

DocsPage 是一种零配置的方式，可将您的 Storybook 转化为丰富、易读的文档。这是将您的 Storybook 转化为世界一流设计系统的第一步。

💡 有什么大不了的？

高质量的组件文档对于任何协作的 UI 开发过程都非常有价值。

但是编写文档需要花费大量时间。即使您设法编写了文档，在构建功能的同时维护文档也非常困难。实际上，大多数文档在发布的那一刻就过时了。 😭

在过去的几年中，现代前端团队采用了组件驱动开发，从组件开始，到屏幕结束，自下而上地构建 UI。他们使用 Storybook 将关键组件状态编码为故事。

故事易于编写，并且始终保持最新，因为它们使用真实的生产组件。许多团队已经在每个项目中生成数百个故事，以捕获其关键用例。

如果您可以利用您在开发过程中已经创建的故事，并使用它们自动生成高质量的文档，那会怎么样？

您将获得隔离组件开发和最佳实践 UI 组件文档的双重好处……而且是免费的！

💵 给我看看好处！

DocsPage 是一个简单的模板，可将您的 Storybook 转化为美观的文档。每个组件页面都包含描述、主要故事（带有可复制的源代码）、属性表和故事集合。

您可以浏览 Storybook 设计系统的实时版本（介绍文章）。每个组件都有自己的 DocsPage，它是从现有的 Storybook 自动生成的。

🏋️‍♀️ 站在巨人的肩膀上…

这并不是一个疯狂的想法。DocsPage 取代了 addon-info，这是一个自动文档工具，它是 Storybook 生态系统中最受欢迎的插件之一。

尽管存在一些已知的缺陷，Info 插件仍拥有超过 100 万次 npm 下载/月。DocsPage 修复了 Info 的所有缺点，甚至更多。

• ✅ DocsPage 不仅限于 React。它可以处理 Storybook 支持的任何框架中的组件。
• ✅ 它将其自身渲染到自己的窗口中，因此不会污染快照测试或与 Storybook 预览窗口交互的其他工具。
• ✅ 您可以在 Storybook 的 UI 内部查看文档，并导出独立的文档站点。
• ✅ 您可以获得每个组件的文档，而不是每个故事的文档。
• ✅ 由于从头开始的重新设计，它更容易维护。

DocsPage 不仅解决了所有这些问题，而且我们甚至还设计了周到的迁移路径，如果您已经使用了 addon-info 或 addon-notes。

📈 从好到更好

但 DocsPage 不仅仅是更好的自动文档：它还是通往出色、文档丰富的设计系统的门户。

DocsPage 中的每个项目都是一个文档块：一个精心设计的 UI 元素，它聚合了来自您的组件、其故事或关联元数据（源代码、属性定义、类型、docgen 注释、git 提交、测试覆盖率、性能测量等等）的单个信息。

这些相同的构建块也可以轻松地在基于 markdown 的长篇文档中重用使用 MDX

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

<Meta title="Demo/Badge" component={Badge} />

# Badge

With `MDX` we write longform markdown documentation for our `Badge` component and embed Doc Blocks inline.

<Props of={Badge} />

<Story name="positive">
  <Badge status="positive">Positive</Badge>
</Story>

Storybook Docs 使您可以轻松地将组件的 DocsPage 替换为 MDX，或者在 Storybook 中自动生成的 DocsPage 文档旁边添加补充 MDX 文档。

因此，工作流程变为

1. 在 Storybook 中构建您的组件
2. 自动获取每个组件的基于示例的文档
3. 根据需要使用 MDX 增强您的文档

MDX 支持今天在 5.2 版本中可用，正式版本将在 Storybook 5.3 RC 中发布。有关 MDX 支持的更多信息，请参阅Storybook MDX 发布文章。

⚡️ 1 分钟安装

想要使用它吗？首先将您的项目升级到最新的 Storybook 版本

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

然后将文档添加到现有项目

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

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

module.exports = ['@storybook/addon-docs/preset'];

将 react 替换为您选择的框架。有关配置 DocsPage 的更多信息，请阅读安装说明。

🚀 项目协作

Storybook 文档是一个雄心勃勃的项目，旨在简化构建设计系统的技术方面。

4 月，我们宣布了该项目，5 月，我们发布了第一个技术预览版。从那时起，我们迭代了 70 多个预发布版本。DocPage 是第一个发布的功能。

我们需要您的帮助，使文档变得更好。

您可以提供的最简单的帮助是在您的项目中安装 DocsPage，并在我们的 Github 项目中提出问题和/或提交错误报告。如果您发现了可以修复的错误，我们欢迎所有贡献！

我们还有更大的计划

我们希望帮助将 DocsPage 带到 Storybook 支持的每个框架。DocsPage 是“免费”提供的，但某些功能（例如属性表支持）仍然需要在每个框架的基础上构建。如果您想改进对您选择的框架的 DocsPage 支持，请在此总括性问题中查看您框架的当前状态。

除了 DocsPage 之外，我们还有更多正在开发中的功能，处于不同的完成阶段。

• 我们正在创建一个丰富的文档块库，例如组件的 Github 协作者头像、组件状态徽章等等。
• 我们还支持MDX 文档创作。初步版本已作为 5.2 版本的一部分提供，我们希望在 5.3 版本正式发布之前与社区一起改进它。
• 最后，我们还希望能够将 Storybook 文档嵌入到其他文档系统中，例如 Gatsby。

如果您有兴趣在任何方面进行协作，或者只是想随时了解最新动态，项目社区主要活跃在我们的 Discord 上的 #docs-mode 频道中。

感谢社区

Storybook 文档由Michael Shilman（我！）、Tom Coleman、Norbert de Langen、Lionel Benychou、Atanas Stoyanov 和 Igor Davydkin 开发。设计和主题由 Dominic Nguyen 负责。特别感谢尝鲜采用者 Pål Nes、Jeroen Reumkens、Bart Ledoux、Aaron Pool、Alex Wilson、Joey Cozza 和 Tom Speak。非常感谢 Brad Frost 提供设计系统项目指导。

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