您可以擁有最好的開源項目，但如果它沒有良好的文檔，它很可能永遠不會成功。 在辦公室，良好的文件將防止您回答相同的問題。 如果關鍵員工離開公司或角色發生變化，文件還可以確保人們能夠理解專案。 生活指南將有助於確保資料完整性。
如果您需要編寫長文本，Markdown 是 HTML 的絕佳替代品。 有時 Markdown 語法還不夠。 在這種情況下，我們可以在其中使用 HTML。 例如，自訂元素。 因此，如果您正在使用本機 Web 元件建立設計系統，它們可以輕鬆包含在文字文件中。 如果您使用 React（或任何其他 JSX 框架，如 Preact 或 Vue），則可以使用 MDX 執行相同的操作。
本文廣泛概述了用於編寫文件和建立指南的工具。 並非此處列出的所有工具都使用 MDX，但它越來越多地包含在文件工具中。
什麼是MDX？
文件 .mdx 與 Markdown 具有相同的語法，但允許您匯入互動式 JSX 元件並將它們嵌入到您的內容中。 對 Vue 組件的支援處於 alpha 階段。 要開始使用 MDX，只需安裝“Create React App”。 有 Next.js 和 Gatsby 的插件。 Docusaurus 的下一個版本（版本 2）也將提供本機支援。
使用 Docusaurus 編寫文檔
Docusaurus 在 Facebook 上寫道。 他們在 React 之外的每個開源專案上都使用它。 在公司外部，Redux、Prettier、Gulp 和 Babel 使用它。
使用 Docusaurus 的項目。
Docusaurus 可以用來寫 任何 文檔，不僅僅是描述前端。 它的底層有 React，但您不必熟悉它就可以使用它。 它需要你的 Markdown 文件，一點魔法和結構良好、格式化、可讀、設計精美的文檔就準備好了。
在 Redux 網站上你可以看到標準的 Docusaurus 模板
使用 Docusaurus 建立的網站還可以包括基於 Markdown 的部落格。 Prism.js 立即連接以進行語法突出顯示。 儘管 Docusaurus 出現的時間相對較晚，但它在 StackShare 上被公認為 2018 年最佳工具。
其他內容創建選項
Docusaurus 專為建立文件而設計。 當然，製作網站的方法有一百萬零一種 - 您可以使用任何語言、CMS 部署自己的解決方案，或使用靜態網站產生器。
例如，React、IBM 設計系統、Apollo 和 Ghost CMS 的文檔使用 Gatsby——一種常用於部落格的靜態網站產生器。 如果您使用 Vue，那麼 VuePress 對您來說是一個不錯的選擇。 另一個選擇是使用用 Python 編寫的生成器 - MkDocs。 它是開源的，並使用單一 YAML 檔案進行設定。 GitBook 也是一個不錯的選擇，但它只對公共和非商業團隊免費。 您也可以簡單地使用 Git 上傳 mardown 檔案並在 Github 中使用它們。
文件元件：Docz、Storybook 和 Styleguidist
指南、系統設計、元件庫——無論你怎麼稱呼它們，它最近變得非常流行。 像 React 這樣的元件框架和這裡提到的工具的出現已經將它們從虛榮專案轉變為有用的工具。
Storybook、Docz 和 Styleguidist 都做同樣的事情：顯示互動元素並記錄其 API。 一個項目可以有數十個甚至數百個組件 - 所有組件都具有不同的狀態和樣式。 如果您希望元件被重複使用，人們需要知道它們的存在。 為此，只需對組件進行編目即可。 指南提供了所有組件的易於查找的概述。 這有助於保持視覺一致性並避免重複工作。
這些工具提供了查看不同狀態的便捷方法。 在真實應用程式的上下文中重現元件的每個狀態可能很困難。 與其點擊實際的應用程序，不如開發一個單獨的組件。 可以模擬難以到達的狀態（例如載入狀態）。
除了各種狀態和屬性清單的直覺式演示之外，通常還需要編寫內容的一般描述 - 設計原理、用例或使用者測試結果的描述。 Markdown 非常容易學習 - 理想情況下，指南應該成為設計師和開發人員的共享資源。 Docz、Styleguidist 和 Storybook 提供了一種輕鬆地將 Markdown 與元件混合的方法。
文件茲
目前 Docz 僅適用於 React，但支援 Preact、Vue 和 Web 元件的積極工作正在進行中。 Docz 是這三個工具中最新的一個，但它已經在 Github 上獲得了超過 14 顆星。 Docz 引入了兩個組件 - <Playground> и < Props >。 它們被導入並在文件中使用 .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>你可以用以下方式包裝自己的 React 元件 <Playground>建立內建 CodePen 或 CodeSandbox 的類似物 - 也就是說，您可以看到您的元件並可以對其進行編輯。
<Playground>
<Button>click</Button>
</Playground><Props> 將顯示給定 React 元件的所有可用屬性、預設值以及該屬性是否是必需的。
<Props of={Button} />就我個人而言，我發現這種基於 MDX 的方法是最容易理解和最容易使用的。
如果您是 Gatsby 靜態網站產生器的粉絲，Docz 提供了出色的整合。
時尚指南
與 Docz 一樣，範例是使用 Markdown 語法編寫的。 Styleguidist 在常規文件中使用 Markdown 程式碼區塊（三引號） .md 文件，而不是 MDX。
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown 中的程式碼區塊通常只顯示程式碼。 使用 Styleguidist 時，任何帶有語言標籤的程式碼區塊 js, jsx 或 javascript 將呈現為 React 元件。 與 Docz 一樣，程式碼是可編輯的 - 您可以更改屬性並立即查看結果。
Styleguidist 將自動從 PropTypes、Flow 或 Typescript 宣告建立屬性表。
Styleguidist 目前支援 React 和 Vue。
故事書
Storybook 將自己定位為「UI 元件開發環境」。 您無需在 Markdown 或 MDX 文件中編寫範例元件，而是編寫 歷史 在 JavaScript 檔案中。 故事 記錄組件的特定狀態。 例如，元件可能具有載入狀態和停用狀態的歷史記錄（禁用).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook 比 Styleguidist 和 Docz 複雜得多。 但同時，這是最受歡迎的選項；該項目在 Github 上擁有超過 36 顆星。 它是一個開源項目，擁有 000 名貢獻者和全職員工。 Airbnb、Algolia、Atlassian、Lyft 和 Salesforce 使用它。 Storybook 支援比競爭對手更多的框架 - React、React Native、Vue、Angular、Mithril、Ember、Riot、Svelte 和常規 HTML。
在未來的版本中，將引入 Docz 和 MDX 的功能。
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook 的新功能將在接下來的幾個月內逐步推出，看起來這將是向前邁出的一大步。
結果
模式庫的好處在 Medium 上的數百萬篇文章中得到了讚揚。 如果做得好，它們可以更輕鬆地創建相關產品並保持身份。 當然，這些工具都不會神奇地創造一個設計系統。 這需要仔細的設計和CSS。 但當需要讓整個公司都可以使用設計系統時，Docz、Storybook 和 Styleguidist 都是不錯的選擇。
來自譯者。 這是我第一次體驗哈布雷。 如果您發現任何不準確之處，或有改進文章的建議，請透過個人資訊給我寫信。
來源： www.habr.com