Mermaid

外観

Mermaidの作成者によるMermaidホワイトボードを体験してください

使い方 ​

Mermaidは、Markdownベースの構文を使用してカスタマイズ可能なダイアグラム、チャート、視覚化をレンダリングするJavaScriptツールです。

ダイアグラムは、その記述を修正することで再レンダリング/変更できます。

CDN ​

https://www.jsdelivr.com/package/npm/mermaid

右上にあるドロップダウンボックスでバージョンを切り替えることができることに注意してください。

mermaidの使用 ​

ほとんどのユーザーにとって、ライブエディターを使用するだけで十分ですが、mermaidを依存関係としてデプロイしたり、Mermaid APIを使用することもできます。

Mermaidライブエディターの使用方法に関するビデオチュートリアルをまとめました。

WebページでのMermaidのインストールとホスティング ​

npmパッケージの使用

要件

  • Node >= 16
bash
# NPM
npm install mermaid
# Yarn
yarn add mermaid
# PNPM
pnpm add mermaid

Webページでのmermaidのホスティング

注：このトピックは、初心者向けユーザーガイドでより詳細に説明されています。

Webページにmermaidを統合する最も簡単な方法は、2つの要素が必要です。

  • <pre>タグ内のclass=mermaidとラベル付けされたグラフ定義。

例

html
<pre class="mermaid">
    graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</pre>
  • mermaid jsスクリプト。ESMインポートとしてscriptタグを使用して追加されます。

例

html
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

これらの指示に従うと、mermaidはページ読み込み時に開始し、（ページが読み込まれると）class="mermaid"を持つpreタグ内のグラフ定義を特定し、指定された定義に従ってSVG形式でダイアグラムを返します。

簡単な完全な例：​

html
<!doctype html>
<html lang="en">
  <body>
    <pre class="mermaid">
  graph LR
      A --- B
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
    </pre>
    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

注：​

id属性も、idのないmermaidタグに追加されます。

Mermaidは、同じページで複数のダイアグラムをロードできます。

試してみてください。このコードをHTMLとして保存し、任意のブラウザーを使用してロードしてください。（Internet Explorerは使用しないでください。）

ノードでのクリックイベントとタグの有効化 ​

最初にsecurityLevel設定をクリアする必要があります。securityLevelは、解析されたダイアグラムの信頼レベルを設定し、クリック機能を制限します。これは、悪意のある使用を防ぐことを目的として、バージョン8.2でセキュリティの改善として導入されました。

信頼できるユーザーベースと信頼できないユーザーベースを区別するのはサイト所有者の責任であり、慎重な使用を推奨します。

securityLevel ​

パラメーター説明タイプ必須値
securityLevel解析された図の信頼レベル文字列オプション'sandbox'、'strict'、'loose'、'antiscript'

値

  • strict：（デフォルト）テキスト内のHTMLタグはエンコードされ、クリック機能は無効になります。
  • antiscript：テキスト内のHTMLタグは許可され（script要素のみが削除されます）、クリック機能が有効になります。
  • loose：テキスト内のHTMLタグは許可され、クリック機能が有効になります。
  • sandbox：このセキュリティレベルでは、すべてのレンダリングはサンドボックス化されたiframe内で行われます。これにより、コンテキストでJavaScriptが実行されるのを防ぎます。これにより、ダイアグラムのインタラクティブ機能（スクリプト、シーケンス図のポップアップ、他のタブまたはターゲットへのリンクなど）が妨げられる可能性があります。

情報

これにより、mermaidのデフォルトの動作が変更され、8.2へのアップグレード後、securityLevelが変更されない限り、フローチャートのタグはタグとしてエンコードされ、クリックが無効になります。 sandboxセキュリティレベルはまだベータ版です。

ダイアグラムソースのセキュリティに責任を負う場合は、securityLevelを任意の値を設定できます。これにより、クリックとタグが許可されます。

securityLevelを変更するには、mermaid.initializeを呼び出す必要があります

javascript
mermaid.initialize({
  securityLevel: 'loose',
});

範囲外のラベル ​

フォントなどのCSSを介してロードされる動的にロードされたフォントを使用する場合、mermaidはページ全体のロード（dom +アセット、特にフォントファイル）を待機する必要があります。

javascript
$(document).ready(function () {
  mermaid.initialize();
});

そうしないと、ラベルが範囲外にあるグラフをmermaidがレンダリングする可能性が高くなります。mermaidのデフォルトの統合では、window.loadイベントを使用してレンダリングを開始します。

ページ本文に他のフォントがある場合、mermaidフォントの代わりにそれらが使用される可能性があります。スタイルでフォントを指定することは、この問題の回避策です。

css
pre.mermaid {
  font-family: 'trebuchet ms', verdana, arial;
}

mermaid.runの使用 ​

mermaid.runはv10で追加され、より複雑な統合を処理するための推奨される方法です。デフォルトでは、mermaid.runはドキュメントの準備ができたときに呼び出され、class="mermaid"を持つすべての要素をレンダリングします。

await mermaid.run(<config>)を呼び出すことで、その動作をカスタマイズできます。

mermaid.initialize({startOnLoad: false})は、ロード後にmermaid.runが自動的に呼び出されるのを防ぎます。

querySelector ".someOtherClass"を持つすべての要素をレンダリングします

js
mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  querySelector: '.someOtherClass',
});

配列として渡されたすべての要素をレンダリングします

js
mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  nodes: [document.getElementById('someId'), document.getElementById('anotherId')],
});
await mermaid.run({
  nodes: document.querySelectorAll('.yetAnotherClass'),
});

エラーを抑制しながら、すべての.mermaid要素をレンダリングします

js
mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  suppressErrors: true,
});

mermaid.initの呼び出し - 非推奨 ​

警告

mermaid.initはv10で非推奨となり、将来のリリースで削除されます。代わりにmermaid.runを使用してください。

デフォルトでは、mermaid.initはドキュメントの準備ができたときに呼び出され、class="mermaid"を持つすべての要素を検索します。mermaidがロードされた後にコンテンツを追加する場合、またはこの動作をより細かく制御する必要がある場合は、initを自分で呼び出すことができます。

  • 構成オブジェクト
  • いくつかのノード、次のように
    • ノード
    • ノードの配列のようなもの
    • またはノードを検索するW3Cセレクター

例

javascript
mermaid.init({ noteMargin: 10 }, '.someOtherClass');

または、構成オブジェクトなしで、jQuery選択

javascript
mermaid.init(undefined, $('#someId .yetAnotherClass'));

webpackでの使用 ​

mermaidはwebpackを完全にサポートしています。これは動作するデモです。

APIの使用 ​

APIの主なアイデアは、グラフ定義を文字列として指定してレンダリング関数を呼び出すことができるようにすることです。レンダリング関数はグラフをレンダリングし、結果のSVGコードを使用してコールバックを呼び出します。このアプローチでは、サイト作成者がサイトから（おそらくテキストエリアから）グラフ定義を取得し、レンダリングして、グラフをサイトのどこかに配置するのは、サイト作成者の責任となります。

以下の例は、この機能がどのように使用できるかを示す例です。この例では、結果として得られるSVGをJavaScriptコンソールに出力するだけです。

html
<script type="module">
  import mermaid from './mermaid.esm.mjs';
  mermaid.initialize({ startOnLoad: false });

  // Example of using the render function
  const drawDiagram = async function () {
    element = document.querySelector('#graphDiv');
    const graphDefinition = 'graph TB\na-->b';
    const { svg } = await mermaid.render('graphDiv', graphDefinition);
    element.innerHTML = svg;
  };

  await drawDiagram();
</script>

特定のテキストに存在する図の種類を判別するには、以下の例で示すように、mermaid.detectType関数を利用できます。

html
<script type="module">
  import mermaid from './mermaid.esm.mjs';
  const graphDefinition = `sequenceDiagram
    Pumbaa->>Timon:I ate like a pig.
    Timon->>Pumbaa:Pumbaa, you ARE a pig.`;
  try {
    const type = mermaid.detectType(graphDefinition);
    console.log(type); // 'sequence'
  } catch (error) {
    // UnknownDiagramError
  }
</script>

イベントのバインド ​

生成されたグラフには、ツールチップやクリックイベントなどのインタラクションが定義されている場合があります。APIを使用する場合、グラフがDOMに挿入された後にこれらのイベントを追加する必要があります。

以下のサンプルコードは、APIを使用する際にmermaidが行う処理の一部を抜粋したものです。この例では、レンダリングにAPIを使用する際に、SVGにイベントをバインドする方法を示しています。

javascript
// Example of using the bindFunctions
const drawDiagram = async function () {
  element = document.querySelector('#graphDiv');
  const graphDefinition = 'graph TB\na-->b';
  const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
  element.innerHTML = svg;
  // This can also be written as `bindFunctions?.(element);` using the `?` shorthand.
  if (bindFunctions) {
    bindFunctions(element);
  }
};
  1. グラフはrender呼び出しを使用して生成されます。
  2. 生成後、render関数は提供されたコールバック関数を呼び出します。この場合はinsertSvgという名前です。
  3. コールバック関数は、生成されたグラフのSVGコードと、関数の2つのパラメーターで呼び出されます。この関数は、SVGがDOMに挿入された後にイベントをSVGにバインドします。
  4. 表示のためにSVGコードをDOMに挿入します。
  5. イベントをバインドするバインド関数を呼び出します。

マーク付きレンダラーの例 ​

これは、ドキュメントをMarkdownから、mermaid図を含むHTMLに変換するために使用されるレンダラーです。

javascript
const renderer = new marked.Renderer();
renderer.code = function (code, language) {
  if (code.match(/^sequenceDiagram/) || code.match(/^graph/)) {
    return '<pre class="mermaid">' + code + '</pre>';
  } else {
    return '<pre><code>' + code + '</code></pre>';
  }
};

生成されたマークアップにmermaidスクリプトタグも含まれるCoffeeScriptの別の例。

coffee
marked = require 'marked'

module.exports = (options) ->
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) ->
    if language is 'mermaid'
      html = ''
      if not hasMermaid
        hasMermaid = true
        html += '<script src="'+options.mermaidPath+'"></script>'
      html + '<pre class="mermaid">'+code+'</pre>'
    else
      @defaultCode(code, language)

  renderer

高度な使用法 ​

レンダリングなしの構文検証 ​

mermaid.parse(text, parseOptions)関数は、グラフをレンダリングせずにグラフ定義を検証します。

関数mermaid.parse(text, parseOptions)は、引数としてテキスト文字列を受け取り、定義がmermaidの構文に従っている場合は{ diagramType: string }を返します。

定義が無効な場合、parseOptions.suppressErrorsがtrueに設定されていると、関数はfalseを返します。それ以外の場合は、エラーをスローします。

parseError関数は、parse関数がエラーをスローしたときに呼び出されます。parseOptions.suppressErrorsがtrueに設定されている場合は呼び出されません。

アプリケーション固有の方法でエラーを処理するために、この関数をオーバーライドすることができます。

メタコードの以下のコード例は、これがどのように機能するかを示しています。

javascript
mermaid.parseError = function (err, hash) {
  displayErrorInGui(err);
};

const textFieldUpdated = async function () {
  const textStr = getTextFromFormField('code');

  if (await mermaid.parse(textStr)) {
    reRender(textStr);
  }
};

bindEventHandler('change', 'code', textFieldUpdated);

構成 ​

必要な構成は、mermaid.initialize呼び出しに渡すことができます。これがmermaidを構成する推奨される方法です。構成オブジェクトのリストは、mermaidAPIドキュメントに記載されています。

html
<script type="module">
  import mermaid from './mermaid.esm.mjs';
  let config = { startOnLoad: true, flowchart: { useMaxWidth: false, htmlLabels: true } };
  mermaid.initialize(config);
</script>

情報

これがmermaidを構成する推奨される方法です。

次のメソッドは非推奨であり、下位互換性のためにのみ保持されています。 ​

mermaidオブジェクトの使用 ​

mermaidオブジェクトを介していくつかの構成を設定することができます。このアプローチを使用してサポートされている2つのパラメーターは次のとおりです。

  • mermaid.startOnLoad
  • mermaid.htmlLabels
javascript
mermaid.startOnLoad = true;

警告

この構成の設定方法は非推奨です。代わりに、initializeメソッドを使用することをお勧めします。この機能は、下位互換性のためにのみ保持されています。