即使沒有全面的文檔，即使是最佳的開源項目也可能會失敗。內(nèi)部文檔同樣至關(guān)重要，即使隨著員工的變化，也可以防止重復(fù)的問答和確保知識連續(xù)性。有據(jù)可查的編碼指南促進(jìn)了代碼庫的一致性。

對于大量文檔，Markdown提供了與RAW HTML的優(yōu)越替代品。但是，可以通過將HTML直接嵌入Markdown文件（包括使用Web組件的設(shè)計系統(tǒng)的自定義元素）來克服MARKDOWN的限制。對于React（和JSX兼容的框架），MDX提供了無縫集成。

本文提供了有關(guān)文檔和樣式指南創(chuàng)建工具的高級概述。雖然并非全部利用MDX，但其采用率正在迅速增加。

了解MDX

.mdx文件鏡像標(biāo)準(zhǔn)標(biāo)記語法，但允許導(dǎo)入和嵌入交互式JSX組件。 VUE組件支持當(dāng)前在Alpha中。 MDX可以輕松地與Create React App集成，并且Next.js和Gatsby存在插件。 Docusaurus版本2還將具有內(nèi)置支持。

Docusaurus：文檔強(qiáng)國

由Facebook開發(fā)（不包括React），由許多主要的開源項目（Redux，Priptier，Gulp，Babel）使用。它的多功能性超出了前端文檔。雖然在內(nèi)部利用反應(yīng)時，Docusaurus不需要使用反應(yīng)知識才能使用。它將Markdown文件轉(zhuǎn)換為結(jié)構(gòu)良好，視覺上吸引人的文檔網(wǎng)站。

Docusaurus網(wǎng)站可以合并基于Markdown的博客，并包括用于無縫語法突出顯示的Prism.js。它的受歡迎程度很明顯，已被評選為StackShare 2018年的最佳新工具。

替代文檔解決方案

雖然Docusaurus專門從事文檔，但仍有許多替代方案。使用各種后端語言，CMS或靜態(tài)站點生成器可行自定義解決方案。 React，IBM的設(shè)計系統(tǒng)，Apollo和Ghost CMS，例如Leverage Gatsby，這是一種多功能的靜態(tài)站點生成器，通常用于博客。 Vuepress在Vue生態(tài)系統(tǒng)中獲得了吸引力。 MKDOCS是用Python編寫的開源靜態(tài)站點生成器，提供了直接的YAML配置。 Gitbook是一種受歡迎的付費選項，可免費訪問開源和非營利團(tuán)隊。對于更簡單的內(nèi)部文檔，GitHub的Markdown渲染功能是可行的選擇。

組件文檔：Docz，Storybook和StyleGuidist

風(fēng)格指南和設(shè)計系統(tǒng)已獲得巨大的知名度。組件驅(qū)動的框架（例如React）和相關(guān)工具將它們從虛榮項目轉(zhuǎn)變?yōu)榛举Y源。

Storybook，Docz和StyleGuidist的目的類似：顯示交互式UI組件并記錄其API。用各種狀態(tài)和樣式管理眾多組件需要一個集中的目錄，以發(fā)現(xiàn)和重復(fù)使用。樣式指南提供易于搜索的概述，促進(jìn)視覺一致性并防止冗余工作。

這些工具簡化了對不同組件狀態(tài)的審查，克服了重現(xiàn)實時應(yīng)用程序中所有狀態(tài)的挑戰(zhàn)。孤立的組件開發(fā)允許嘲笑難以到達(dá)的狀態(tài)（例如，加載狀態(tài)）。

丹·格林（Dan Green）對故事書的好處的評論同樣適用于Docz和Styleguidist：

“故事書已經(jīng)簡化了設(shè)計和工程之間的協(xié)作。它消除了對復(fù)雜的設(shè)置（Docker容器等）的需求。對于Wave，我們僅在短暫的，復(fù)雜的過程中可見組件（例如，在Storybook中）。在故事書之前，在管理這些組件之前，管理這些組件很難。

- 丹·格林（Dan Green），波浪財務(wù)

除了可視化狀態(tài)和列表道具外，書面內(nèi)容（設(shè)計理由，用例，用戶測試結(jié)果）增強(qiáng)了組件文檔。 Markdown的可訪問性使其非常適合設(shè)計師和開發(fā)人員之間的協(xié)作文檔。 Docz，Styleguidist和Storybook將Markdown與組件無縫整合。

Docz

目前，Docz（14,000 GitHub Stars）目前僅反應(yīng)（計劃支持preaxct，vue和Web組件），提供用戶友好的功能。它提供<playground></playground>和<props></props>組件，直接在.mdx文件中使用。

從“ docz”導(dǎo)入{playground，props};
從“ ../ src/button”導(dǎo)入按鈕;

##您可以_write_ ** Markdown **
###您可以導(dǎo)入和使用組件

<playground>
  <button>點擊</button>
</playground>

包裝反應(yīng)組件與<playground></playground>創(chuàng)建嵌入式交互式預(yù)覽。<props></props>顯示組件道具，默認(rèn)值和所需狀態(tài)。

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

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

StyleGuidist

StyleGuidist在標(biāo)準(zhǔn).md文件而不是MDX中使用Markdown Code塊（三重背部）。

 ``JS
 console.log（“單擊”）

<code></code>

 <code>>Push Me</code>

代碼塊標(biāo)記為js ， jsx或javascript渲染作為交互式React組件。該代碼可編輯，提供即時視覺反饋。 StyleGuidist會自動從Proptypes，F(xiàn)low或Typescript聲明中生成支柱表。它支持反應(yīng)和vue。

故事書

Storybook（36,000 GitHub星）是一個UI組件開發(fā)環(huán)境。它不是Markdown/MDX，而是使用JavaScript文件進(jìn)行故事（代表組件狀態(tài)）。

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

Storybook的方法不如DOCZ和StyleGuidist直觀。然而，它的受歡迎程度和廣泛的框架支持（React，React，Vue，Angular，Mithril，Ember，Riot，Svelte，Svelte，HTML）是值得注意的。文檔當(dāng)前需要插件，但未來版本將合并受DOCZ啟發(fā)的MDX。

 ＃ 按鈕

關(guān)于您的按鈕寫的一些_notes_用** Markdown語法**編寫。


<button>lorem ipsum</button>

Storybook即將到來的文檔功能有望進(jìn)行重大改進(jìn)。

結(jié)論

圖案庫的價值被廣泛認(rèn)可。執(zhí)行良好的文庫促進(jìn)了視覺一致性和產(chǎn)品凝聚力。盡管這些工具不能取代設(shè)計和CSS專業(yè)知識，但DOCZ，Storybook和StyleGidist提供了出色的解決方案，可在組織內(nèi)有效地溝通設(shè)計系統(tǒng)。

以上是前端文檔，樣式指南和MDX的興起的詳細(xì)內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！