マークダウンで人魚の図を作成します

人魚の図とフローチャートは、特にGithubがMarkdownでネイティブにサポートされていると発表したことで、牽引力を獲得しています。彼らが何であるか、それらをどのように使用するか、そして同じくらい重要なことを見てみましょう。なぜ。

ドキュメントソースにCodepenデモを直接埋めたいと思うように、テキストに隣接する図やチャートを飼育するのに役立つ、つまりドキュメントの状態と同期しないようにするのに役立ちます。役に立たない、時代遅れ、または誤解を招くコードのコメントは、コメントなしよりも客観的に悪化する可能性がありますが、図にも同じことが言えます。

人魚の図は、Jamstackと静的サイトジェネレーターとよく組み合わされており、人気が高まっています。ペアリングは自然です。人魚の図はマークダウンエクスペシではありませんが、マークダウンにインスパイアされています。マークダウンがコードを表記するために提供するのと同じマークアップ抽象化を使用すると、人魚は出力図とフローチャートと同じものを表すことができます。そして、マークダウンは、ピーナッツバターがゼリーにあるので、ジャムスタックと静的サイトにあります。

サイトがHTMLに処理され、カスタムJavaScriptを少し追加するのに十分なコントロールがある場合は、この記事でカバーするアイデアを使用して、マークダウンの残りの部分と一緒に人魚のダイアグラムを便利に実装するために十分に制御できます。 「コードとしての図」はまだ用語ですか？そうあるべきです。

たとえば、派手な新製品に取り組んでおり、ガントチャート（または他のタイプなど、フローチャート、シーケンス、クラス図など）の形でロードマップを提供したいとします。人魚を使用すると、これを少し一握りの行で行うことができます。

ガント
  私の製品ロードマップをタイトルします
  dateformat yyyy-mm-dd
  セクションクールな機能
  タスク：A1、2022-02-25、30d
  別のタスク：A1、20Dの後
  セクションRAD機能
  順番のタスク：2022-03-04、12d
  タスク、No。2：24d

これは、そうするような素敵なSVG図をレンダリングします：

プロのヒント： Mermaidにはライブエディターがあり、Mermaid.liveでコミットメントなしで試してみることができます。

マークダウンの人魚図

Mermaidは、Mermaid Language Syntaxセットのみを使用して、単なる別のフェンスで囲まれたコードブロックとして自分自身を提示するため、Markdownによく合います。たとえば、このコードブロック：

 「人魚」
グラフTD;
    a-> b;
    a-> c;
    b-> d;
    c-> d;
`` `

…内部にコードブロックの内容を含むHTML

要素を生成します。<pre rel="HTML" data-line=""> <pre class="brush:php;toolbar:false"> <code>グラフTD;
    a-> b;
    a-> c;
    b-> d;
    c-> d; </code> 

Commonmark仕様に合わせたMarkdownプロセッサを使用している場合、これに似ています。

 <pre class="brush:php;toolbar:false"> <code>グラフTD;
    a-> b;
    a-> c;
    b-> d;
    c-> d;
</code> 

デモを表示します

Mermaid APIのデフォルト動作には、コンテンツを直接含む

タグが予想されます。したがって、Markdown-to-HTMLからの変換でわかるように、または<span>（構文の蛍光ペンからのように）です。<h3 id="JavaScriptのフィネス"> JavaScriptのフィネス</h3> <p>JavaScriptを少し使用すると、Markdownで生成されたHTMLを採取し、Mermaidがターゲットとする</p> <div>タグにフィネスすることが合理的です。ここでは$ element.textContentが目的であることに注意する価値があります。マークダウンは、人魚が使用するHTML-Encode固有の文字（> into＆gt;など）です。また、<pre class="brush:php;toolbar:false">要素の子孫である誤ったHTML要素を除外します。&lt;pre rel=&quot;JavaScript&quot; data-line=&quot;&quot;&gt; // &lt;pre class=&quot;brush:php;toolbar:false&quot;&gt; _and_ &lt;pre class=&quot;brush:php;toolbar:false&quot;&gt; &lt;code&gt;を選択します document.QuerySelectorall（ &quot;pre.mermaid、pre&gt; code.language-mermaid&quot;）。 // 2番目のセレクターがヒットした場合、親&lt;pre class=&quot;brush:php;toolbar:false&quot;&gt;を参照してください if（$ el.tagname === &quot;code&quot;） $ el = $ el.parentelement //人魚の内容を予想される&lt;div&gt;に入れます //プラス元のコンテンツを素敵なに保持します $ el.outerhtml = ` &lt;div&gt; $ {$ el.TextContent} &lt;/div&gt; &lt;summary&gt;図のソース&lt;/summary&gt; &lt;pre class=&quot;brush:php;toolbar:false&quot;&gt; $ {$ el.TextContent} </pre> 詳細> ` }）<p> HTMLが適切にフォーマットされているので、レンダリングを行うために人魚を実装しましょう。</p> <h3 id="人魚を使用します">人魚を使用します</h3> <p>MermaidはNPMパッケージとして公開されているため、UNPKGのようなパッケージ認識CDNを使用してコピーを入手できます。 Mermaid.core.jsのデフォルトエクスポートの代わりに、邪魔されたコード（mermaid.min.jsなど）を使用する必要があります。例えば：</p> <pre rel="HTML" data-line=""> &lt;p&gt; MermaidはESM対応で&lt;em&gt;も&lt;/em&gt;あるため、Skypackを使用してロードすることもできます。&lt;/p&gt;&lt;pre rel=&quot;HTML&quot; data-line=&quot;&quot;&gt; &lt;script type=&quot;module&quot;&gt; &quot;https://cdn.skypack.dev/ [Email Protected]&quot;からの人魚をインポートします。 &lt;/script&gt;</pre><p>物事をシンプルに保ちたい場合は、ここでやめることができます。デフォルトでは、Mermaidは、ドキュメントの準備ができたら自動的に自動化します。 Markdown-to-HTMLを前述したJavaScriptでフィネスする限り - 人魚でロードする<em>前に</em>、あなたはすべて設定されます。</p><p>ただし、Mermaidには、構成する価値のあるいくつかの設定があります。</p><pre rel="JavaScript" data-line=""> //マーメイドを[1]ログエラーに初期化し、[2]ファーストパーティのセキュリティが緩くなります //著者の図、および[3]は好ましい暗い配色を尊重します Mermaid.Initialize（{ logLevel：「エラー」、// [1] SecurityLevel：「loose」、// [2] テーマ：（ window.matchmedia &amp;&amp; window.matchmedia（ &quot;（&quot;（presters-color-scheme：dark） &quot;）。一致）？ &quot;暗い&quot; ： 「デフォルト」// [3] }）</pre><ol> <li> LogLevelは、発生する可能性のあるエラーをもう少し可視化します。詳細情報をご覧になりたい場合は、より冗長レベル（またはその逆）を選択できます。</li> <li> SecurityLevelは、図ソースの信頼のレベルに関連しています。<em>あなた</em>がオーサリングしていることがコンテンツである場合、「ゆるい」は問題ありません。ユーザーが生成したコンテンツの場合、おそらく「厳格な」デフォルトを整備しておくのが最適です。</li> <li>テーマは、レンダリングされた図のスタイリングを変更します。優先配色を照会し、3成分演算子を活用することにより、必要に応じて「暗い」を指定できます。</li> </ol><h3 id="今すべて一緒に">今すべて一緒に！</h3><p>ここに、マークダウンの人魚の図の例がいくつかあります。</p><h3 id="より深い海">より深い海</h3><p>この戦略は、<em>プログレッシブで</em>あるため、特に効果的です。JavaScriptが無効になっている場合、元の人魚ソースが表示されます。ファウルはありません。</p><p>また、人魚用の本格的なコマンドラインインターフェイスもあります。これは、探索に興味深い場合は、完全にサーバー側のレンダリングされた図を表示するためにレバレッジできる可能性があります。マーメイドCLIとオンラインジェネレーターの間では、図のスナップショットを生成してソースコードの代わりに<img alt="マークダウンで人魚の図を作成します" >フォールバックとして表示するために使用するビルドプロセスに接続することさえ可能です。</p><p>人魚が人気を博し続けているため、このようなネイティブの人魚統合がより多くなることを願っています。ドキュメントと一緒に視覚チャートや図を持つことの有用性は、製品のロードマップから意思決定ツリーやその間のすべてまで、疑いの余地がありません。それは、言葉だけで文書化するのが非常に難しい情報の一種です。</p><p>マーメイドチャートはそれを解決し、情報を残りのドキュメントと一緒に管理および維持できるようにする方法で解決します。</p></pre> </div></pre>