生活ガイドライン - MDX およびその他のフレームワーク

最高のオープンソース プロジェクトを持つことはできますが、適切なドキュメントがなければ、プロジェクトは決して普及しない可能性があります。 オフィスでは、適切な文書があれば、同じ質問に答えることができなくなります。 また、文書化することで、主要な従業員が会社を辞めたり、役割が変わったりした場合でも、人々がプロジェクトを理解できるようになります。 生活ガイドラインは、データの整合性を確保するのに役立ちます。

長いテキストを記述する必要がある場合、Markdown は HTML の優れた代替手段です。 場合によっては、Markdown 構文だけでは不十分な場合があります。 この場合、その中で HTML を使用できます。 たとえば、カスタム要素です。 したがって、ネイティブ Web コンポーネントを使用してデザイン システムを構築している場合、それらをテキスト ドキュメントに簡単に含めることができます。 React (または Preact や Vue などの他の JSX フレームワーク) を使用している場合は、MDX で同じことを行うことができます。

この記事では、ドキュメントの作成とガイドラインの作成のためのツールの概要を説明します。 ここにリストされているすべてのツールが MDX を使用しているわけではありませんが、ドキュメント ツールに MDX が含まれることが増えています。

MDXとは何ですか？

ファイル .mdx の構文は Markdown と同じですが、インタラクティブな JSX コンポーネントをインポートしてコンテンツに埋め込むことができます。 Vue コンポーネントのサポートはアルファ版です。 MDX の使用を開始するには、「Create React App」をインストールするだけです。 Next.js と Gatsby のプラグインがあります。 Docusaurus の次のバージョン (バージョン 2) もネイティブ サポートを持つ予定です。

Docusaurus を使用してドキュメントを作成する

ドキュサウルス氏はフェイスブックにこう書いた。 彼らは React を除くすべてのオープンソース プロジェクトでこれを使用しています。 社外では、Redux、Prettier、Gulp、Babel で使用されています。

Docusaurus を使用するプロジェクト。

Docusaurus を使用して書くことができます 任意の フロントエンドの説明だけでなくドキュメントも必要です。 内部には React が組み込まれていますが、使用するのに精通している必要はありません。 Markdown ファイルを使用すると、ひとつまみの魔法で、適切に構造化され、フォーマットされ、読みやすい美しいデザインのドキュメントが完成します。

Redux Web サイトでは、標準の Docusaurus テンプレートを参照できます。

Docusaurus で構築された Web サイトには、Markdown ベースのブログを含めることもできます。 Prism.js は構文強調表示のためにすぐに接続されます。 Docusaurus は比較的最近登場したという事実にもかかわらず、StackShare では 2018 年の最高のツールとして認められました。

その他のコンテンツ作成オプション

Docusaurus は、ドキュメントの作成に特化して設計されています。 もちろん、Web サイトを作成する方法は無数にあります。任意の言語、CMS で独自のソリューションを展開することも、静的サイト ジェネレーターを使用することもできます。

たとえば、React、IBM デザイン システム、Apollo、Ghost CMS のドキュメントでは、ブログでよく使用される静的サイト ジェネレーターである Gatsby が使用されています。 Vue を使用する場合は、VuePress が最適なオプションです。 もう XNUMX つのオプションは、Python で書かれたジェネレーター (MkDocs) を使用することです。 これはオープンソースであり、単一の YAML ファイルを使用して構成されます。 GitBook も良い選択肢ですが、無料なのはパブリックおよび非営利チームのみです。 Git を使用してマーダウン ファイルをアップロードし、Github で操作することもできます。

文書化コンポーネント: Docz、Storybook、Styleguidist

ガイドライン、システム設計、コンポーネント ライブラリ、何と呼んでも、最近非常に人気があります。 React のようなコンポーネント フレームワークとここで説明したツールの出現により、それらは虚栄的なプロジェクトから便利なツールに変わりました。

Storybook、Docz、および Styleguidist はすべて同じことを行います。つまり、インタラクティブな要素を表示し、その API を文書化します。 プロジェクトには数十、場合によっては数百のコンポーネントが含まれる場合があり、すべて異なる状態とスタイルを持ちます。 コンポーネントを再利用したい場合は、コンポーネントの存在を人々に知らせる必要があります。 これを行うには、コンポーネントをカタログ化するだけです。 ガイドラインは、すべてのコンポーネントの概要を見つけやすく提供します。 これにより、視覚的な一貫性が維持され、反復作業が回避されます。

これらのツールは、さまざまな状態を表示する便利な方法を提供します。 実際のアプリケーションのコンテキストでコンポーネントの各状態を再現するのは難しい場合があります。 実際のアプリケーションをクリックする代わりに、別のコンポーネントを開発する価値があります。 到達が困難な状態 (読み込み状態など) をシミュレートできます。

さまざまな状態の視覚的なデモンストレーションやプロパティのリストに加えて、多くの場合、コンテンツの一般的な説明 (設計の理論的根拠、使用例、ユーザー テストの結果の説明) を記述する必要があります。 Markdown は非常に簡単に学ぶことができます。理想的には、ガイドラインはデザイナーと開発者のための共有リソースであるべきです。 Docz、Styleguidist、Storybook は、Markdown とコンポーネントを簡単に組み合わせる方法を提供します。

ドクズ

現在、Docz は React でのみ動作しますが、Preact、Vue、および Web コンポーネントをサポートするための積極的な作業が進行中です。 Docz は 14 つのツールの中で最も新しいものですが、Github 上で 000 を超えるスターを集めることができました。 DoczはXNUMXつのコンポーネントを導入します- <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 が優れた選択肢となります。

翻訳者より。 これが私にとってハブレでの初めての経験です。 不正確な点を見つけた場合、または記事を改善するための提案がある場合は、個人メッセージで私に書いてください。

出所： habr.com