您可能有一个更好的开源项目，但是如果它没有好的文档，那么它很可能永远都不会起飞。 在办公室，好的文档将使您无法回答相同的问题。 该文档还确保如果关键员工离开公司或角色变更，则人们可以理解项目。 实时指南有助于确保数据完整性。
如果您需要写长文本，Markdown是HTML的绝佳替代品。 有时Markdown语法还不够。 在这种情况下，我们可以使用其中的HTML。 例如，自定义元素。 因此，如果要使用本机Web组件构建设计系统，则很容易将其包含在文本文档中。 如果您使用React（或其他任何JSX框架，例如Preact或Vue），则可以使用MDX进行相同的操作。
本文是对文档编写和指南工具的广泛概述。 并非此处列出的所有工具都使用MDX，但是越来越多的工具被包含在文档工具中。
什么是MDX？
.mdx文件具有与Markdown相同的语法，但是允许您导入JSX交互式组件并将其嵌入到您的内容中。 对Vue组件的支持为alpha。 要开始使用MDX，只需安装“创建React App”。 有适用于Next.js和Gatsby的插件。 下一个版本的Docusaurus（版本2）也将具有内置支持。
用Docusaurus编写文档
Docusaurus在Facebook上写道。 他们在React以外的每个开源项目上使用它。 在公司外部，Redux，Prettier，Gulp和Babel使用它。
使用Docusaurus的项目。
Docusaurus可以用来编写任何文档，而不仅仅是描述前端。 他的内幕下有React，但是要使用它，不必熟悉他。 它需要您的Markdown文件，一堆魔术和结构良好，格式化且易读的文档，并具有精美的设计。
在Redux网站上，您可以看到标准的Docusaurus模板
使用Docusaurus创建的网站也可能包含基于Markdown的博客。 Prism.js立即连接到语法突出显示。 尽管Docusaurus出现得较晚，但在StackShare上它被公认为2018年最佳工具。
其他内容创建选项
Docusaurus专为创建文档而设计。 当然，建立站点有一百万种方法-您可以使用任何语言，CMS部署自己的解决方案，也可以使用静态站点生成器。
例如，React的文档（IBM，Apollo和Ghost CMS的设计系统）使用的是Gatsby，这是一种静态网站生成器，通常用于博客。 如果您使用Vue，那么VuePress是您的理想选择。 另一个选择是使用用Python编写的生成器-MkDocs。 它是打开的，并且可以使用单个YAML文件进行配置。 GitBook也是一个不错的选择，但它仅对开放和非营利团队免费。 您也可以使用gith上传mardown文件，并在Github上使用它们。
组件文档：Docz，Storybook和Styleguidist
准则，系统设计，组件库-不论您如何称呼它们，但最近它变得非常流行。 组件框架（如React和此处提到的工具）的出现使将它们从自负的项目变成有用的工具成为可能。
Storybook，Docz和Styleguidist-做同样的事情：显示交互式元素并记录其API。 一个项目可以包含数十个甚至数百个组件-所有组件都具有不同的状态和样式。 如果要重用组件，人们需要知道它们的存在。 为此，只需对组件进行分类。 准则提供了所有组件的可搜索概述。 这有助于保持视觉一致性并避免重复工作。
这些工具提供了查看各种状态的便捷方法。 在实际应用程序的上下文中，可能很难重现每个组件的状态。 而不是单击真实的应用程序，您应该开发一个单独的组件。 您可以模拟难以到达的状态（例如，启动状态）。
除了各种状态的可视化演示和属性列表之外，通常还需要编写内容的一般说明-设计依据，案例研究或用户测试结果的说明。 Markdown非常易于学习-理想情况下，指南应该是设计人员和开发人员的共享资源。 Docz，Styleguidist和Storybook提供了一种轻松将Markdown与组件混合的方法。
多茨
现在Docz仅与React一起使用，但是正在积极支持Preact，Vue和Web组件。 Docz是这三种仪器中最新鲜的一种，但是在Github上，他能够收集超过14,000颗恒星。 Docz表示两个组件- <Playground>和< Props > 。 它们被导入并在.mdx文件中使用。
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
您可以使用<Playground>包装自己的React组件，以创建内置CodePen或CodeSandbox的类似物-也就是说，您可以看到自己的组件并可以对其进行编辑。
<Playground> <Button>click</Button> </Playground>
<Props>将显示该React组件的所有可用属性，默认值以及是否需要一个属性。
<Props of={Button} />
我个人认为，这种基于MDX的方法最容易理解，也最容易使用。
如果您是Gatsby静态网站生成器的粉丝，Docz将为您提供出色的集成。
Styleguidist
与Docz一样，示例都是使用Markdown语法编写的。 Styleguidist在常规.md文件中而不是MDX中使用Markdown代码块（三重引号）。
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Markdown中的代码块通常只显示代码。 使用Styleguidist时，带有js ， jsx或javascript语言标记的任何代码块都将显示为React组件。 与在Docz中一样，该代码是可编辑的-您可以更改属性并立即查看结果。
Styleguidist将根据PropTypes，Flow或Typescript声明自动创建属性表。
Styleguidist现在支持React和Vue。
故事书
故事书将自己定位为“ UI组件的开发环境”。 您无需在Markdown或MDX文件中编写组件示例，而在Javascript文件中编写故事 。 历史记录由组件的特定状态记录。 例如，组件可能具有启动状态和禁用状态的历史记录。
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
故事书比Styleguidist和Docz复杂得多。 但与此同时，这是最受欢迎的选择，在Github上，该项目拥有36,000多颗恒星。 这是一个开源项目，共有657名参与者，并有全职员工陪同。 Airbnb，Algolia，Atlassian，Lyft和Salesforce使用它。 Storybook支持的框架比其竞争对手更多-React，React Native，Vue，Angular，Mithril，Ember，Riot，Svelte和常规HTML。
在将来的版本中，将有来自Docz的芯片，并且将引入MDX。
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
故事书的新功能将在未来几个月内逐步出现，显然，这将是一大进步。
总结
在Medium上的数百万篇文章中都赞扬了模式库的优势。 如果做得好，他们可以轻松创建相关产品并维护身份。 当然，这些工具都无法神奇地创建设计系统。 这需要仔细的设计和CSS设计。 但是当需要将设计系统提供给整个公司时，Docz，Storybook和Styleguidist都是不错的选择。
来自翻译者。 这是我第一次在Habré上的经历。 如果您发现某些内容不正确，或者有改进文章的建议，请亲自撰写。