フロントエンドドキュメント、スタイルガイド、MDXの台頭

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

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

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

MDXの理解

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docz

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

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

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

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

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

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

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

StyleGuidist

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

 「JS」
 console.log（ 'clicked'）

<code></code>

 <code>>Push Me</code>

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

ストーリーブック

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

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

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

 ＃ ボタン

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


<button>Lorem Ipsum</button>

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

結論

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

以上がフロントエンドドキュメント、スタイルガイド、MDXの台頭の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。