前端文档,样式指南和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中文网其他相关文章!

热AI工具

Undresser.AI Undress
人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover
用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool
免费脱衣服图片

Clothoff.io
AI脱衣机

Video Face Swap
使用我们完全免费的人工智能换脸工具轻松在任何视频中换脸!

热门文章

热工具

记事本++7.3.1
好用且免费的代码编辑器

SublimeText3汉化版
中文版,非常好用

禅工作室 13.0.1
功能强大的PHP集成开发环境

Dreamweaver CS6
视觉化网页开发工具

SublimeText3 Mac版
神级代码编辑软件(SublimeText3)

关于Flex布局中紫色斜线区域的疑问在使用Flex布局时,你可能会遇到一些令人困惑的现象,比如在开发者工具(d...
