前端文档，样式指南和MDX的兴起

即使没有全面的文档，即使是最佳的开源项目也可能会失败。内部文档同样至关重要，即使随着员工的变化，也可以防止重复的问答和确保知识连续性。有据可查的编码指南促进了代码库的一致性。

对于大量文档，Markdown提供了与RAW HTML的优越替代品。但是，可以通过将HTML直接嵌入Markdown文件（包括使用Web组件的设计系统的自定义元素）来克服MARKDOWN的限制。对于React（和JSX兼容的框架），MDX提供了无缝集成。

本文提供了有关文档和样式指南创建工具的高级概述。虽然并非全部利用MDX，但其采用率正在迅速增加。

了解MDX

.mdx文件镜像标准标记语法，但允许导入和嵌入交互式JSX组件。 VUE组件支持当前在Alpha中。 MDX可以轻松地与Create React App集成，并且Next.js和Gatsby存在插件。 Docusaurus版本2还将具有内置支持。

Docusaurus：文档强国

由Facebook开发（不包括React），由许多主要的开源项目（Redux，Priptier，Gulp，Babel）使用。它的多功能性超出了前端文档。虽然在内部利用反应时，Docusaurus不需要使用反应知识才能使用。它将Markdown文件转换为结构良好，视觉上吸引人的文档网站。

Docusaurus网站可以合并基于Markdown的博客，并包括用于无缝语法突出显示的Prism.js。它的受欢迎程度很明显，已被评选为StackShare 2018年的最佳新工具。

替代文档解决方案

虽然Docusaurus专门从事文档，但仍有许多替代方案。使用各种后端语言，CMS或静态站点生成器可行自定义解决方案。 React，IBM的设计系统，Apollo和Ghost CMS，例如Leverage Gatsby，这是一种多功能的静态站点生成器，通常用于博客。 Vuepress在Vue生态系统中获得了吸引力。 MKDOCS是用Python编写的开源静态站点生成器，提供了直接的YAML配置。 Gitbook是一种受欢迎的付费选项，可免费访问开源和非营利团队。对于更简单的内部文档，GitHub的Markdown渲染功能是可行的选择。

组件文档：Docz，Storybook和StyleGuidist

风格指南和设计系统已获得巨大的知名度。组件驱动的框架（例如React）和相关工具将它们从虚荣项目转变为基本资源。

Storybook，Docz和StyleGuidist的目的类似：显示交互式UI组件并记录其API。用各种状态和样式管理众多组件需要一个集中的目录，以发现和重复使用。样式指南提供易于搜索的概述，促进视觉一致性并防止冗余工作。

这些工具简化了对不同组件状态的审查，克服了重现实时应用程序中所有状态的挑战。孤立的组件开发允许嘲笑难以到达的状态（例如，加载状态）。

丹·格林（Dan Green）对故事书的好处的评论同样适用于Docz和Styleguidist：

“故事书已经简化了设计和工程之间的协作。它消除了对复杂的设置（Docker容器等）的需求。对于Wave，我们仅在短暂的，复杂的过程中可见组件（例如，在Storybook中）。在故事书之前，在管理这些组件之前，管理这些组件很难。

- 丹·格林（Dan Green），波浪财务

除了可视化状态和列表道具外，书面内容（设计理由，用例，用户测试结果）增强了组件文档。 Markdown的可访问性使其非常适合设计师和开发人员之间的协作文档。 Docz，Styleguidist和Storybook将Markdown与组件无缝整合。

Docz

目前，Docz（14,000 GitHub Stars）目前仅反应（计划支持preaxct，vue和Web组件），提供用户友好的功能。它提供<playground></playground>和<props></props>组件，直接在.mdx文件中使用。

从“ docz”导入{playground，props};
从“ ../ src/button”导入按钮;

##您可以_write_ ** Markdown **
###您可以导入和使用组件

<playground>
  <button>点击</button>
</playground>

包装反应组件与<playground></playground>创建嵌入式交互式预览。<props></props>显示组件道具，默认值和所需状态。

<props of="{Button}"></props>

DOCZ的基于MDX的方法是直观有效的，提供了出色的盖茨比集成。

StyleGuidist

StyleGuidist在标准.md文件而不是MDX中使用Markdown Code块（三重背部）。

 ``JS
 console.log（“单击”）

<code></code>

 <code>>Push Me</code>

代码块标记为js ， jsx或javascript渲染作为交互式React组件。该代码可编辑，提供即时视觉反馈。 StyleGuidist会自动从Proptypes，Flow或Typescript声明中生成支柱表。它支持反应和vue。

故事书

Storybook（36,000 GitHub星）是一个UI组件开发环境。它不是Markdown/MDX，而是使用JavaScript文件进行故事（代表组件状态）。

故事（“按钮”，模块）
  .add（'disabled'，（）=>（
    <button disabled>lorem ipsum</button>
  ））

Storybook的方法不如DOCZ和StyleGuidist直观。然而，它的受欢迎程度和广泛的框架支持（React，React，Vue，Angular，Mithril，Ember，Riot，Svelte，Svelte，HTML）是值得注意的。文档当前需要插件，但未来版本将合并受DOCZ启发的MDX。

 ＃ 按钮

关于您的按钮写的一些_notes_用** Markdown语法**编写。


<button>lorem ipsum</button>

Storybook即将到来的文档功能有望进行重大改进。

结论

图案库的价值被广泛认可。执行良好的文库促进了视觉一致性和产品凝聚力。尽管这些工具不能取代设计和CSS专业知识，但DOCZ，Storybook和StyleGidist提供了出色的解决方案，可在组织内有效地沟通设计系统。

以上是前端文档，样式指南和MDX的兴起的详细内容。更多信息请关注PHP中文网其他相关文章！