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

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

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

了解MDX

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

Docusaurus：文檔強(qiáng)國(guó)

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

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

替代文檔解決方案

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

組件文檔：Docz，Storybook和StyleGuidist

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

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

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

丹·格林（Dan Green）對(duì)故事書的好處的評(píng)論同樣適用於Docz和Styleguidist：

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

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

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

Docz

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

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

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

<playground>
  <button>點(diǎn)擊</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組件。該代碼可編輯，提供即時(shí)視覺(jué)反饋。 StyleGuidist會(huì)自動(dòng)從Proptypes，F(xiàn)low或Typescript聲明中生成支柱表。它支持反應(yīng)和vue。

故事書

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

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

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

 ＃ 按鈕

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


<button>lorem ipsum</button>

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

結(jié)論

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

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