主持人 > 博客 > 管理 > 实时指南 - MDX 和其他框架

实时指南 - MDX 和其他框架

您可以拥有最好的开源项目，但如果它没有良好的文档，它很可能永远不会成功。 在办公室，良好的文档将防止您回答同样的问题。 如果关键员工离开公司或角色发生变化，文档还可以确保人们能够理解项目。 生活指南将有助于确保数据完整性。

如果您需要编写长文本，Markdown 是 HTML 的绝佳替代品。 有时 Markdown 语法还不够。 在这种情况下，我们可以在其中使用 HTML。 例如，自定义元素。 因此，如果您正在使用本机 Web 组件构建设计系统，它们可以轻松包含在文本文档中。 如果您使用 React（或任何其他 JSX 框架，如 Preact 或 Vue），则可以使用 MDX 执行相同的操作。

本文广泛概述了用于编写文档和创建指南的工具。 并非此处列出的所有工具都使用 MDX，但它越来越多地包含在文档工具中。

什么是MDX？

文件 .mdx 与 Markdown 具有相同的语法，但允许您导入交互式 JSX 组件并将它们嵌入到您的内容中。 对 Vue 组件的支持处于 alpha 阶段。 要开始使用 MDX，只需安装“Create React App”。 有 Next.js 和 Gatsby 的插件。 Docusaurus 的下一个版本（版本 2）也将提供本机支持。

使用 Docusaurus 编写文档

Docusaurus 在 Facebook 上写道。 他们在除 React 之外的每个开源项目上都使用它。 在公司外部，Redux、Prettier、Gulp 和 Babel 使用它。

实时指南 - MDX 和其他框架使用 Docusaurus 的项目。

Docusaurus 可以用来写 任何 文档，不仅仅是描述前端。 它的底层有 React，但您不必熟悉它就可以使用它。 它需要你的 Markdown 文件，一点点魔法和结构良好、格式化、可读、设计精美的文档就准备好了。

实时指南 - MDX 和其他框架
在 Redux 网站上你可以看到标准的 Docusaurus 模板

使用 Docusaurus 构建的网站还可以包括基于 Markdown 的博客。 Prism.js 立即连接以进行语法突出显示。 尽管 Docusaurus 出现的时间相对较晚，但它在 StackShare 上被公认为 2018 年最佳工具。

其他内容创建选项

Docusaurus 专为创建文档而设计。 当然，制作网站的方法有一百万零一种 - 您可以使用任何语言、CMS 部署自己的解决方案，或使用静态网站生成器。

例如，React、IBM 设计系统、Apollo 和 Ghost CMS 的文档使用 Gatsby——一种常用于博客的静态站点生成器。 如果您使用 Vue，那么 VuePress 对您来说是一个不错的选择。 另一种选择是使用用 Python 编写的生成器 - MkDocs。 它是开源的，并使用单个 YAML 文件进行配置。 GitBook 也是一个不错的选择，但它仅对公共和非商业团队免费。 您还可以简单地使用 Git 上传 mardown 文件并在 Github 中使用它们。

文档组件：Docz、Storybook 和 Styleguidist

指南、系统设计、组件库——无论你怎么称呼它们，它最近变得非常流行。 像 React 这样的组件框架和这里提到的工具的出现已经将它们从虚荣项目转变为有用的工具。

Storybook、Docz 和 Styleguidist 都做同样的事情：显示交互元素并记录其 API。 一个项目可以有数十个甚至数百个组件 - 所有组件都具有不同的状态和样式。 如果您希望组件被重用，人们需要知道它们的存在。 为此，只需对组件进行编目即可。 指南提供了所有组件的易于查找的概述。 这有助于保持视觉一致性并避免重复工作。

这些工具提供了查看不同状态的便捷方法。 在真实应用程序的上下文中重现组件的每个状态可能很困难。 与其点击实际的应用程序，不如开发一个单独的组件。 可以模拟难以到达的状态（例如加载状态）。

除了各种状态和属性列表的直观演示之外，通常还需要编写内容的一般描述 - 设计原理、用例或用户测试结果的描述。 Markdown 非常容易学习 - 理想情况下，指南应该成为设计师和开发人员的共享资源。 Docz、Styleguidist 和 Storybook 提供了一种轻松地将 Markdown 与组件混合的方法。

文档兹

目前 Docz 仅适用于 React，但支持 Preact、Vue 和 Web 组件的积极工作正在进行中。 Docz 是这三个工具中最新的一个，但它已经在 Github 上获得了超过 14 颗星。 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>

你可以用以下方式包装你自己的 React 组件 <Playground>创建内置 CodePen 或 CodeSandbox 的类似物 - 也就是说，您可以看到您的组件并可以对其进行编辑。 

<Playground>
  <Button>click</Button>
</Playground>

<Props> 将显示给定 React 组件的所有可用属性、默认值以及该属性是否是必需的。

<Props of={Button} />

就我个人而言，我发现这种基于 MDX 的方法是最容易理解和最容易使用的。

实时指南 - MDX 和其他框架

如果您是 Gatsby 静态站点生成器的粉丝，Docz 提供了出色的集成。

时尚指南

与 Docz 一样，示例是使用 Markdown 语法编写的。 Styleguidist 在常规文件中使用 Markdown 代码块（三引号） .md 文件，而不是 MDX。

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

Markdown 中的代码块通常只显示代码。 使用 Styleguidist 时，任何带有语言标签的代码块 js, jsx или javascript 将呈现为 React 组件。 与 Docz 一样，代码是可编辑的 - 您可以更改属性并立即查看结果。

实时指南 - MDX 和其他框架

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

实时指南 - MDX 和其他框架

Styleguidist 目前支持 React 和 Vue。

故事书

Storybook 将自己定位为“UI 组件开发环境”。 您无需在 Markdown 或 MDX 文件中编写示例组件，而是编写 故事 在 JavaScript 文件中。 故事 记录组件的特定状态。 例如，组件可能具有加载状态和禁用状态的历史记录（禁用).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Storybook 比 Styleguidist 和 Docz 复杂得多。 但与此同时，这是最受欢迎的选项；该项目在 Github 上拥有超过 36 颗星。 它是一个开源项目，拥有 000 名贡献者和全职员工。 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>

Storybook 的新功能将在接下来的几个月内逐步推出，看起来这将是向前迈出的一大步。

结果

模式库的好处在 Medium 上的数百万篇文章中得到了赞扬。 如果做得好，它们可以更轻松地创建相关产品并保持身份。 当然，这些工具都不会神奇地创建一个设计系统。 这需要仔细的设计和CSS。 但当需要让整个公司都可以使用设计系统时，Docz、Storybook 和 Styleguidist 都是不错的选择。

来自译者。 这是我第一次体验哈布雷。 如果您发现任何不准确之处，或者有改进文章的建议，请通过个人信息给我写信。

来源： habr.com

添加评论