Storybook DocsPage
精美的文档，即时生成
我很高兴地宣布 DocsPage，现已在 Storybook 5.2 中推出。
Storybook 是事实上的 UI 组件工作坊标准。它为 Airbnb、Lyft、Squarespace、Slack 和 Dropbox 等公司，以及超过 25,000 个公共 Github 项目提供前端开发工作流支持。
DocsPage 是一种零配置的方式，可以将你的 Storybook 转化为丰富、可读的文档。这是将你的 Storybook 转化为一流设计系统的第一步。
💡 这有什么大不了的？
高质量的组件文档对任何协作式 UI 开发过程都非常有价值。
但是编写文档需要花费大量时间。即使你做到了，在开发功能的同时维护你的文档也非常困难。实际上，大多数文档在发布的那一刻就已经过时了。😭
在过去的几年里，现代前端团队拥抱了 组件驱动开发，从组件开始，以屏幕结束，自底向上地构建 UI。他们使用 Storybook 将关键的组件状态编码为故事 (stories)。
故事很容易编写，并且由于它们使用了真实的生产组件，因此始终是最新的。许多团队已经为每个项目生成了数百个故事，以捕捉它们关键的用例。
如果你能利用你在开发过程中已经创建的故事来自动生成高质量的文档，那会怎么样？
你将获得独立组件开发的好处以及最佳实践 UI 组件文档……而且是免费的！
💵 给我看看钱！
DocsPage 是一个将你的 Storybook 转化为精美文档的简单模板。每个组件页面都包含一个描述、一个主要故事（带可复制源代码）、一个 props 表格以及一系列故事。
你可以作为 Storybook 设计系统 的一部分实时浏览（介绍文章）。每个组件都有自己的 DocsPage，这些 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 元素，聚合来自你的组件、它们的故事或相关元数据（源代码、props 定义、类型、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 中添加补充的 MDX 文档变得很容易，与自动生成的 DocsPage 文档并存。
因此工作流程变为：
- 在 Storybook 中构建你的组件
- 为每个组件自动获得基于示例的文档
- 根据需要使用 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 项目中提问和/或提交 bug。如果你看到一个你可以修复的 bug，我们欢迎所有贡献！
我们也有更宏大的计划
我们很乐意帮助将 DocsPage 引入 Storybook 支持的每个框架。DocsPage 是“免费”的，但一些功能——例如 Props 表格支持——仍然需要逐个框架进行构建。如果你想改进 DocsPage 对你选择的框架的支持，请在这个汇总 issue中查看你框架的当前状态。
除了 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 变得更好。你可以贡献新功能、修复 bug 或改进文档。加入我们的 Discord，在 Open Collective 上支持我们，或者直接在 Github 上参与。