前端文檔，樣式指南和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組件開發環境。它使用JavaScript文件而不是Markdown/MDX代替故事（表示組件狀態）。

故事（“按鈕”，模塊）
  .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中文網其他相關文章！