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

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

使用 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 的方法最易于理解和使用。

如果您是基于 React 的静态站点生成器 Gatsby 的粉丝,Docz 提供了很好的集成。
Styleguidist
就像 Docz 一样,示例使用 Markdown 语法编写。Styleguidist 在普通的 .md
文件中使用 Markdown 代码块(三个反引号),而不是 MDX。
```js
<button> console.log('clicked')>Push Me</button>
```
Markdown 中的代码块通常只是显示代码。在 Styleguidist 中,任何带有 js
、jsx
或 javascript
语言标签的代码块都将被渲染为 React 组件,并附带代码。就像 Docz 一样,代码是可以编辑的 - 你可以更改属性并立即看到结果。

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

Styleguidist 目前支持 React 和 Vue。
Storybook
Storybook 将自己定位为“UI 组件的开发环境”。你不需要在 Markdown 或 MDX 文件中编写组件示例,而是在 Javascript 文件中编写故事。一个故事记录了组件的特定状态。例如,一个组件可能包含加载状态和禁用状态的故事。
storiesOf('Button', module)
.add('disabled', () => (
<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 都是很好的选择。
您在 ode 示例中使用的是什么语法高亮配色方案?
您好,Aen!我们使用的是 Prism.js,并对 Twilight 配色方案进行了一些修改。:)