前端文档、风格指南与 MDX 的兴起

您可能拥有世界上最好的开源项目，但如果它没有良好的文档，它很可能永远不会流行起来。在办公室里，良好的文档可以帮助您避免重复回答相同的问题。文档确保即使关键员工决定离开公司或改变角色，人们也能弄清楚事物的工作原理。完善的编码指南有助于使代码库保持一致性。

如果您要编写长篇文本，Markdown 显然是编写 HTML 的绝佳替代方案。但有时 Markdown 语法还不够。您一直可以在 Markdown 文档中编写纯 HTML。这包括自定义元素，因此，如果您使用原生 Web 组件构建设计系统，则可以轻松地将它们整合到您的文本型文档中。如果您使用 React（或任何其他使用 JSX 的框架，如 Preact 或 Vue），您可以使用 MDX 做同样的事情。

本文是对用于编写文档和构建风格指南的可用工具的广泛概述。此处列出的并非所有工具都使用 MDX，但它越来越多地被整合到文档工具中。

什么是 MDX？

.mdx 文件与普通 Markdown 文件具有完全相同的语法，但允许您导入交互式 JSX 组件并将它们嵌入到您的内容中。对 Vue 组件的支持处于 alpha 阶段。使用 Create React App 轻松设置 MDX。有针对 Next.js 和 Gatsby 的 MDX 插件。即将发布的第二版 Docusaurus 也将提供内置支持。

使用 Docusaurus 编写文档

Docusaurus 由 Facebook 创建，并用于除 React 之外的所有 Facebook 开源项目。它也被许多大型开源项目用于 Facebook 之外，包括 Redux、Prettier、Gulp 和 Babel。

A screenshot of logos of all the various frameworks that support Docusaurus, including React, Gulp, Jest, Babel, Redux and Prettier. — 使用 Docusaurus 的项目。

您可以使用 Docusaurus 来记录任何内容 - 它不是特定于前端的。 Docusaurus 在幕后使用 React，但您不必了解该框架即可使用它。它将获取您的 Markdown 文件并将它们转换为结构合理、格式良好且可读的文档站点，并提供开箱即用的出色设计。

A screenshot of the Redux documentation homepage with the headline Getting Started with Redux. — Redux 网站显示了典型的 Docusaurus 布局

使用 Docusaurus 创建的网站还可以包含基于 Markdown 的博客。 Prism.js 默认包含在内，无需设置即可实现语法高亮。虽然 Docusaurus 比较新，但它已经证明其流行程度，被评为 StackShare 上 2018 年最受欢迎的新工具。

其他书面内容选项

Docusaurus 特别适合构建文档。当然，制作网站的方法数不胜数 - 因此您可以使用任何后端语言、CMS 或静态站点生成器来构建自己的解决方案。

React、IBM 的设计系统、Apollo 和 Ghost CMS 的文档站点使用 Gatsby，例如 - 一个通常用于博客的通用静态站点生成器。如果您使用 Vue 框架，VuePress 正在成为一个流行的选择。 MkDocs 是一个用于创建文档的开源静态站点生成器，用 Python 编写，并使用单个 YAML 文件进行配置。 GitBook 是一款流行的付费产品，对开源和非营利团队免费。如果您要构建内部文档并且想要一些简单的东西，GitHub 本身的阅读体验还不错，因此您可以提交一些 Markdown 文件并保留原样。

记录组件：Docz、Storybook 和 Styleguidist

风格指南、设计系统、模式库 - 无论您称它们为什么 - 在过去十年中已成为人们关注的热门领域。真正让它们从虚荣项目转变为有用工具的，不是思想领袖的夸夸其谈，而是 React 等组件驱动框架的出现，以及本文中提到的工具。

Storybook、Docz 和 Styleguidist 都做着差不多的事情：显示交互式 UI 组件并记录其 API。一个项目可能拥有数十甚至数百个组件需要跟踪 - 每个组件都有多种状态和样式。如果您希望组件被重复使用，人们就必须知道它们的存在。当我们对组件进行编目时，我们就可以提高可发现性。风格指南提供了一个易于搜索和浏览的概述，涵盖了所有 UI 组件。这有助于保持视觉一致性并避免重复工作。

这些工具提供了一种方便的方式来查看不同状态。在实际应用程序的上下文中，重现组件的每个状态可能很困难。与需要在实际应用程序中进行点击相比，单独开发组件可能会有所帮助。难以触及的状态（例如加载状态）可以被模拟。

Dan Green 针对使用 Storybook 的好处写了一篇很好的概述，但它同样适用于 Docz 和 Styleguidist

“Storybook 让编码的设计师能够轻松地与工程师协作。通过在 storybook 中工作，他们无需运行整个环境（Docker 容器等）。对于 Wave，我们有许多重要的组件，这些组件只能在短时间内完成的流程中间可见，并且很难重现（例如，加载屏幕，只有在用户设置其支付帐户时才会显示）。在 Storybook 之前，我们没有好的方法来处理这些组件，并且不得不使用临时方法来使它们可见。现在，有了 Storybook，我们有一个孤立的地方来轻松处理它们，这也有利于设计师和 PM 方便访问。它还使我们能够轻松地在冲刺演示中展示这些状态。”

– Dan Green，Wave Financial

除了并排可视化不同状态和列出属性外，对组件进行书面描述也很有用 - 无论是解释设计原理、用例还是描述用户测试的结果。 Markdown 非常容易学习 - 理想情况下，风格指南应该是设计师和开发人员共同使用的资源，双方都可以进行贡献。 Docz、Styleguidist 和 Storybook 都提供了一种方法，可以将 Markdown 无缝地与组件本身混合在一起。

Docz

目前，Docz 只是一个 React 项目，但正在努力支持 Preact、Vue 和 Web 组件。 Docz 是这三种工具中最新的，但它已经在 GitHub 上积累了 14,000 多颗星。就我而言，它是最易于使用的解决方案。 Docz 提供两个组件 - 和。这些组件直接导入并使用在 .mdx 文件中。

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<button>click</button>

您可以使用来包装您自己的 React 组件，以创建类似于嵌入式 CodePen 或 CodeSandbox 的内容 - 您组件的视图以及可编辑的代码。

  <button>click</button>

将显示给定 React 组件的所有可用属性、默认值以及属性是否为必填项。

我个人认为这种基于 MDX 的方法最易于理解和使用。

A screenshot of a Code Sandbox project making use of the tool to document the code for a Button component.

如果您是基于 React 的静态站点生成器 Gatsby 的粉丝，Docz 提供了很好的集成。

Styleguidist

就像 Docz 一样，示例使用 Markdown 语法编写。Styleguidist 在普通的 .md 文件中使用 Markdown 代码块（三个反引号），而不是 MDX。

```js
<button> console.log('clicked')&gt;Push Me</button>
```

Markdown 中的代码块通常只是显示代码。在 Styleguidist 中，任何带有 js、jsx 或 javascript 语言标签的代码块都将被渲染为 React 组件，并附带代码。就像 Docz 一样，代码是可以编辑的 - 你可以更改属性并立即看到结果。

A screenshot of the output of the documentation for a pink button made with Styleguidist.

Styleguidist 将自动从 PropTypes、Flow 或 Typescript 声明创建属性表。

A screenshot of a table of values that Styleguidiist generated for the pink button documentation, including values it accepts.

Styleguidist 目前支持 React 和 Vue。

Storybook

Storybook 将自己定位为“UI 组件的开发环境”。你不需要在 Markdown 或 MDX 文件中编写组件示例，而是在 Javascript 文件中编写故事。一个故事记录了组件的特定状态。例如，一个组件可能包含加载状态和禁用状态的故事。

storiesOf('Button', module)
  .add('disabled', () =&gt; (
    <button disabled="disabled">lorem ipsum</button>
  ))

Storybook 比 Styleguidist 和 Docz 更难使用。但是，它在 GitHub 上拥有超过 36,000 颗星，是目前最受欢迎的选择。它是一个开源项目，拥有 657 位贡献者和一位全职维护者。它被 Airbnb、Algolia、Atlassian、Lyft 和 Salesforce 等公司使用。Storybook 支持比其他任何产品都多的框架 - React、React Native、Vue、Angular、Mithril、Ember、Riot、Svelte 和纯 HTML 都得到了支持。

编写关于组件的文档目前需要插件。在即将发布的版本中，Storybook 将从 Docz 中汲取灵感，并采用 MDX。

# Button

Some _notes_ about your button written with **markdown syntax**.


  <button disabled="disabled">lorem ipsum</button>

Storybook 的新 Docs 功能将在未来几个月内逐步推出，看起来将会是一个巨大的进步。

您是否使用 @storybookjs 用于组件文档或设计系统？您一定会喜欢 DocBlocks
📦 融入 MDX
🏗 模块化和可组合
🤝 与 @gatsbyjs、#nextjs 等兼容

🔜 https://#/AmE4l9B3FU by @mshilman pic.twitter.com/Q48PQCmiEt

— Dominic Nguyen (@domyen) April 28, 2019

总结

模式库的好处已经在无数的 Medium 文章中被反复提及。如果做得好，它们可以帮助保持视觉一致性，并促进创建一致的产品。当然，这些工具都不能凭空创造出设计系统。这需要对设计和 CSS 进行认真思考。但是，当需要将该系统传达给组织中的其他成员时，Docz、Storybook 和 Styleguidist 都是很好的选择。