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 Design System 的一部分实时浏览它（介绍文章）。每个组件都有其自己的 DocsPage，从现有的 Storybook 自动生成。

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

这并非异想天开。DocsPage 取代了 addon-info，它是一个自动化文档工具，也是 Storybook 生态系统中最受欢迎的插件之一。

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

• ✅ DocsPage 不依赖于 React。它支持 Storybook 支持的任何框架中的组件。
• ✅ 它渲染到自己的窗口中，因此不会污染快照测试或与其他 Storybook 预览窗口交互的工具。
• ✅ 您可以在 Storybook 的 UI 中查看文档，并且可以导出独立的文档站点。
• ✅ 您获得的是按组件而非按故事划分的文档。
• ✅ 得益于彻底的重新设计，维护变得异常简单。

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

📈 从优秀到卓越

但 DocsPage 不仅是更好的自动化文档：它还是通往优秀、文档丰富的设计系统的敲门砖。

DocsPage 中的每个条目都是一个 Doc Block：一个精心设计的 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 使使用 MDX 替换组件的 DocsPage 变得容易，或者在自动生成的 DocsPage 文档旁边添加补充的 MDX 文档到您的 storybook 中。

因此，工作流程变为

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

然后将 docs 添加到现有项目

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

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

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

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

🚀 项目协作

Storybook Docs 是一个宏大的项目，旨在简化构建设计系统的技术方面。

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

我们需要您的帮助，让 Docs 变得更出色。

最简单的帮助方法是在您的项目中安装 DocsPage，并在我们的 Github 项目中提问和/或提交错误。如果您发现并能修复错误，我们欢迎所有贡献！

我们还有更大的计划

我们非常希望能帮助将 DocsPage 带到 Storybook 支持的每个框架。DocsPage 是“免费”的，但一些功能（如属性表支持）仍需逐个框架地构建。如果您想改进 DocsPage 对您选择的框架的支持，请在此总括性议题中查看您框架的当前状态。

除了 DocsPage 之外，我们还有很多处于不同完成阶段的功能即将推出。

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

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

感谢社区

Storybook Docs 由 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。