最高のオープンソースプロジェクトでさえ、包括的なドキュメントなしで失敗する可能性があります。內(nèi)部ドキュメントも同様に重要であり、繰り返しのQ＆Aを防ぎ、スタッフの変更に伴い知識の継続性を確保します。十分に文書化されたコーディングガイドラインは、コードベースの一貫性を促進します。

広範なドキュメントのために、MarkdownはRAW HTMLに代わる優(yōu)れた代替品を提供します。ただし、Markdownの制限は、Webコンポーネントを使用した設計システム用のカスタム要素を含むMarkdownファイルにHTMLを直接埋め込むことで克服できます。 MDXは、React（およびPreactやVueなどのJSX互換フレームワーク）の場合、シームレスな統(tǒng)合を提供します。

この記事では、ドキュメントとスタイルガイドの作成ツールの高レベルの概要を説明します。すべてがMDXを利用しているわけではありませんが、その採用は急速に増加しています。

MDXの理解

.mdxファイルは、標準のマークダウン構文をミラーリングしますが、インタラクティブなJSXコンポーネントのインポートと埋め込みを可能にします。 Vueコンポーネントサポートは現(xiàn)在Alphaにあります。 MDXはCreate Reactアプリと簡単に統(tǒng)合し、next.jsとGatsby用のプラグインが存在します。 Docusaurusバージョン2には、組み込みのサポートも備えています。

Docusaurus：ドキュメントパワーハウス

Facebook（Reactを除く）によって開発されたDocusaurusは、多數(shù)の主要なオープンソースプロジェクト（Redux、The Prettier、Gulp、Babel）で利用されています。その汎用性は、フロントエンドのドキュメントを超えて拡張されます。內(nèi)部的に反応を利用している間、Docusaurusは使用に反応知識を必要としません。マークダウンファイルを、よく構築された視覚的に魅力的なドキュメントサイトに変換します。

Docusaurusサイトでは、マークダウンベースのブログを組み込んで、シームレスな構文ハイライトにPrism.jsを含めることができます。その人気は明らかであり、Stackshareで2018年のトップの新しいツールに選ばれました。

代替ドキュメントソリューション

Docusaurusはドキュメントを?qū)熼Tとしていますが、多くの代替品が存在します。カスタムソリューションは、さまざまなバックエンド言語、CMS、または靜的サイトジェネレーターを使用して実行可能です。たとえば、IBMの設計システム、Apollo、およびGhost CMSは、ブログによく使用される多用途の靜的サイトジェネレーターであるGatsbyを活用しています。 Vuepressは、Vueエコシステム內(nèi)で牽引力を獲得しています。 Pythonで書かれたオープンソースの靜的サイトジェネレーターであるMKDOCSは、簡単なYAML構成を提供します。人気のある有料オプションであるGitBookは、オープンソースと非営利のチームへの無料アクセスを提供します。より簡単な內(nèi)部ドキュメントのために、GithubのMarkdownレンダリング機能は実行可能なオプションです。

コンポーネントドキュメント：Docz、Storybook、およびStyleGuidist

スタイルガイドとデザインシステムは非常に人気を博しています。コンポーネント駆動型フレームワーク（Reactなど）や関連ツールは、それらを虛栄心プロジェクトから必須リソースに変換しました。

ストーリーブック、Docz、およびStyleGuidistは、インタラクティブなUIコンポーネントの表示とAPIの文書化など、同様の目的を果たします。さまざまな狀態(tài)とスタイルを使用して多數(shù)のコンポーネントを管理するには、発見可能性と再利用のための集中カタログが必要です。スタイルガイドは、簡単に検索可能な概要を提供し、視覚的な一貫性を促進し、冗長な作業(yè)を防ぎます。

これらのツールは、さまざまなコンポーネント狀態(tài)のレビューを簡素化し、ライブアプリケーション內(nèi)のすべての狀態(tài)を再現(xiàn)するという課題を克服します。孤立したコンポーネント開発により、到達が困難な狀態(tài)（狀態(tài)を積み込む）をock笑することができます。

Storybookの利點に関するDan Greenのコメントは、DoczとStyleGuidistにも同様に當てはまります。

「ストーリーブックは、設計とエンジニアリングの間のコラボレーションを簡素化しました。複雑なセットアップ（Dockerコンテナなど）の必要性を排除します。Waveの場合、短命の複雑なプロセス（例えば、畫面の読み込み）でのみ目に見えるコンポーネントを管理します。ストーリーブックの前に、これらのコンポーネントの管理は困難でした。

- ダン?グリーン、ウェーブ?ファイナンシャル

狀態(tài)の視覚化と小道具のリストを超えて、書かれたコンテンツ（デザインの根拠、ユースケース、ユーザーテストの結果）がコンポーネントのドキュメントを強化します。 Markdownのアクセシビリティにより、デザイナーと開発者の間の共同ドキュメントに最適です。 Docz、StyleGuidist、およびStorybookは、マークダウンをコンポーネントとシームレスに統(tǒng)合します。

docz

現(xiàn)在、Reactのみ（Preact、Vue、およびWebコンポーネントを計畫しているサポート）であるDocz（14,000 Github Stars）は、ユーザーフレンドリーな機能を提供しています。それは提供します<playground></playground>そして<props></props>.mdxファイル內(nèi)で直接使用されるコンポーネント。

 「docz」から{playground、props}をインポートします。
"../src/button"からボタンをインポートします。

## _write_ **マークダウン**
###コンポーネントをインポートおよび使用できます

<playground>
  <button>クリック</button>
</playground>

ラッピング反応コンポーネント<playground></playground>組み込みのインタラクティブなプレビューを作成します。<props></props>コンポーネントのプロップ、デフォルト値、および必要なステータスを表示します。

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

DoczのMDXベースのアプローチは直感的で効率的であり、Gatsbyの優(yōu)れた統(tǒng)合を提供します。

StyleGuidist

StyleGuidistは、MDXの代わりに標準.mdファイル內(nèi)でマークダウンコードブロック（トリプルバックティック）を使用します。

 「JS」
 console.log（ 'clicked'）

<code></code>

 <code>>Push Me</code>

js 、 jsx 、またはjavascriptのタグ付けされたコードブロックは、インタラクティブな反応コンポーネントとしてレンダリングされます。コードは編集可能で、即時の視覚的なフィードバックを提供します。 StyleGuidistは、PropTypes、Flow、またはTypeScript宣言からプロップテーブルを自動的に生成します。それはReactとVueをサポートします。

ストーリーブック

ストーリーブック（36,000 Github Stars）は、UIコンポーネント開発環(huán)境です。 MarkDown/MDXの代わりに、ストーリー（コンポーネント狀態(tài)を表す）にJavaScriptファイルを使用します。

 Storiesof（ 'Button'、モジュール）
  .add（ 'disabled'、（）=>（
    <button disabled>Lorem Ipsum</button>
  ）））

Storybookのアプローチは、DoczやStyleGuidistより直感的ではありません。しかし、その人気と広範なフレームワークのサポート（React、React Native、Vue、Angular、Mithril、Ember、Riot、Svelte、HTML）は注目に値します?，F(xiàn)在、ドキュメントにはアドオンが必要ですが、將來のリリースにはDoczに觸発されたMDXが組み込まれます。

 ＃ ボタン

** Markdown Syntax **で書かれたボタンについて_notes_。


<button>Lorem Ipsum</button>

Storybookの今後のドキュメント機能は、大幅な改善を約束します。

結論

パターンライブラリの価値は広く認められています。よく実行されたライブラリは、視覚的な一貫性と製品の結束を促進します。これらのツールは設計やCSSの専門知識に取って代わるものではありませんが、Docz、Storybook、StyleGuidistは、組織內(nèi)でデザインシステムを効果的にコミュニケーションするための優(yōu)れたソリューションを提供します。

以上がフロントエンドドキュメント、スタイルガイド、MDXの臺頭の詳細內(nèi)容です。詳細については、PHP 中國語 Web サイトの他の関連記事を參照してください。