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

Avatar of Ollie Williams
Ollie Williams

DigitalOcean 提供适合您旅程各个阶段的云产品。 立即开始使用 价值 200 美元的免费信贷!

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

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

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

什么是 MDX?

.mdx 文件与普通 Markdown 文件具有完全相同的语法,但允许您导入交互式 JSX 组件并将它们嵌入到您的内容中。 对 Vue 组件的支持处于 alpha 阶段。 使用 Create React App 轻松设置 MDX。 有针对 Next.jsGatsby 的 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 或静态站点生成器来构建自己的解决方案。

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

记录组件:Docz、Storybook 和 Styleguidist

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

StorybookDoczStyleguidist 都做着差不多的事情:显示交互式 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 中,任何带有 jsjsxjavascript 语言标签的代码块都将被渲染为 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 功能将在未来几个月内逐步推出,看起来将会是一个巨大的进步。

总结

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