Mermaid ドキュメント

Appearance

使用方法 ​

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

ダイアグラムは、説明を修正することで再レンダリングまたは変更できます。

CDN ​

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

右上のドロップダウンボックスからバージョンを切り替えることができますのでご注意ください。

mermaidの使用 ​

大多数のユーザーにとって、Live Editorを使用することで十分ですが、mermaidを依存関係としてデプロイするか、Mermaid APIを使用することもできます。

Mermaid Live Editorの使用方法に関する動画チュートリアルをまとめました。

ウェブページにMermaidをインストールしてホスティングする ​

npmパッケージを使用する:

要件:

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

ウェブページにmermaidをホスティングする:

注: このトピックは初心者向けユーザーガイドでより深く探求されています。

ウェブページに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 '<CDN_URL>/mermaid@<MERMAID_VERSION>/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 '<CDN_URL>/mermaid@<MERMAID_VERSION>/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

注意事項: ​

mermaidタグには、もともとid属性が追加されます。

Mermaidは同じページに複数のダイアグラムを読み込むことができます。

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

ノード内でのクリックイベントとタグを有効にする ​

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

それはサイトの所有者の責任で信頼できるユーザーベースと信頼できないユーザーベースを区別する必要があり、裁量を使用することをお勧めします。

securityLevel ​

パラメータ説明タイプ必須値
securityLevel解析されたダイアグラムの信頼レベルStringオプション'sandbox', 'strict', 'loose', 'antiscript'

値:

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

NOTE

これにより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のデフォルト統合は、ウィンドウのロードイベントを使用してレンダリングを開始します。

ページに他のフォントが含まれている場合、それらが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が呼び出されるのを防ぎます。

.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の呼び出し - 非推奨 ​

WARNING

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 });

  // レンダー関数の使用例
  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
// 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;
  // これは`bindFunctions?.(element);`としても書くことができます。
  if (bindFunctions) {
    bindFunctions(element);
  }
};
  1. レンダー呼び出しを使用してグラフが生成されます。
  2. 生成後、レンダーファンクションは指定されたコールバック関数を呼び出します。この場合、それはinsertSvgと呼ばれます。
  3. コールバック関数は、生成されたグラフのSVGコードと、一時的にSVGにイベントをバインドする関数の2つのパラメーターで呼び出されます。
  4. 提示のためにDOMにSVGコードを挿入します。
  5. イベントをバインドするバインディング関数を呼び出します。

マークされたレンダラーの例 ​

これは、MarkdownからHTMLへのドキュメントを変換するために使用されるレンダラーで、HTML内のmermaidダイアグラムが含まれています。

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>';
  }
};

もう一つの例はCoffeeScriptで、生成されたマークアップにmermaidスクリプトタグも含まれています。

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>

NOTE

これはmermaidを設定するための推奨方法です。

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

mermaidオブジェクトの使用 ​

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

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

WARNING

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